-
Notifications
You must be signed in to change notification settings - Fork 39
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* chore: renaming Workflows * use TypeId and Id annotations in Workflows * migrate to TypeId and Id in samples * Update docs/src/modules/java/pages/event-sourced-entities.adoc Co-authored-by: Andrzej Ludwikowski <[email protected]> --------- Co-authored-by: Andrzej Ludwikowski <[email protected]>
- Loading branch information
Showing
91 changed files
with
865 additions
and
667 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,26 +1,26 @@ | ||
|
|
||
| == Identifying the Entity | ||
|
|
||
| In order to interact with an Entity in Kalix, we need to assign an *entity type* and one or more *entity keys*: | ||
| In order to interact with an Entity in Kalix, we need to assign an *type id* and one or more instance *ids*: | ||
|
|
||
| * *entity type* is a unique identifier for all entities of a given type. To define the entity type, the entity class must be annotated with `@EntityType` and have a unique and stable name assigned. | ||
| * *entity key*, on the other hand, is unique per instance. In most cases, the entity key is passed as a path parameter of a REST request. The exception to the rule is when we request Kalix to auto-generate a key for us. In such a case, Kalix won't try to extract the key from the endpoint path. | ||
| * *type id* is a unique identifier for all entities of a given type. To define the entity type id, the entity class must be annotated with `@TypeId` and have a unique and stable identifier assigned. | ||
| * *id*, on the other hand, is unique per instance. In most cases, the entity id is passed as a path parameter of a REST request. The exception to the rule is when we request Kalix to auto-generate a id for us. In such a case, Kalix won't try to extract the id from the endpoint path. | ||
|
|
||
| The entity key can be defined in different ways, as detailed below. | ||
| The entity id can be defined in different ways, as detailed below. | ||
|
|
||
| === Single keys | ||
|
|
||
| The most common use is to annotate the class with `@EntityKey` and assign one path variable name to it. | ||
| For instance, `@EntityKey("id")` will instruct Kalix to look up a matching path variable. For an endpoint defined with `@RequestMapping("/users/\{id}")`, Kalix will extract whatever path segment is used to replace `\{id}` and treat it as the Entity unique identifier. | ||
| The most common use is to annotate the class with `@Id` and assign one path variable name to it. | ||
| For instance, `@Id("id")` will instruct Kalix to look up a matching path variable. For an endpoint defined with `@RequestMapping("/users/\{id}")`, Kalix will extract whatever path segment is used to replace `\{id}` and treat it as the Entity unique identifier. | ||
|
|
||
| === Composite keys | ||
|
|
||
| It's also possible to have composite keys. For example, `@EntityKey({"groupId", "id"})` defines a composite key made of `groupId` and `id`. In such a case, the endpoints for this entity will need to have both path variables, e.g.: `@RequestMapping("/users/\{groupId}/\{id}")`. | ||
| It's also possible to have composite keys. For example, `@Id({"groupId", "id"})` defines a composite key made of `groupId` and `id`. In such a case, the endpoints for this entity will need to have both path variables, e.g.: `@RequestMapping("/users/\{groupId}/\{id}")`. | ||
|
|
||
| === Generated keys | ||
|
|
||
| Finally, you can ask Kalix to generate an Entity key, this is typically useful when creating an Entity, and the key is a surrogate key. To indicate to Kalix that an Entity key should be generated rather than extracted from the path, be sure to annotate the corresponding command method with `@GenerateEntityKey`. Typically, an Entity has only one method annotated with `@GenerateEntityKey`. The one that creates the Entity. All other methods will have `@EntityKey` annotation in order to extract the surrogate key from the endpoint path. | ||
| Finally, you can ask Kalix to generate an unique identifier, this is typically useful when creating an Entity, and the id is a surrogate id. To indicate to Kalix that an Entity id should be generated rather than extracted from the path, be sure to annotate the corresponding command method with `@GenerateId`. Typically, an Entity has only one method annotated with `@GenerateId`. The one that creates the Entity. All other methods will have `@Id` annotation in order to extract the surrogate id from the endpoint path. | ||
|
|
||
| It will often be necessary to access the generated entity key from inside the entities code. This can be done using the link:{attachmentsdir}/api/kalix/javasdk/EntityContext.html#entityId()[`EntityContext.entityId`{tab-icon},window="new"] method. | ||
| It will often be necessary to access the generated entity id from inside the entities code. This can be done using the link:{attachmentsdir}/api/kalix/javasdk/EntityContext.html#entityId()[`EntityContext.entityId`{tab-icon},window="new"] method. | ||
|
|
||
| NOTE: Kalix generates a UUID version 4 (random) keys. Only version 4 UUIDs are currently supported for generated Entity keys. | ||
| NOTE: Kalix generates a UUID version 4 (random) keys. Only version 4 UUIDs are currently supported for generated Entity identifiers. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.