Define basic terms: "entity", "repository", "identifier", etc.

[gavinking]

A challenge this spec faces is the extremely high level of abstraction. At this level of abstraction we can't be sure that we all mean the same things by the words we use. There's a risk of accidentally smuggling the semantics of one sort of data storage technology into the specification without even realizing it.

To make a start on nailing down the meaning of words here, I propose the following starting point. Please let me know what you think.

Entities and repositories

Abstractly, an entity (or entity type) is a schema for data. Here we assume that data is persistent, that is, that the data outlives any Java process which makes use of it.

• The schema may be as simple as a tuple of types, as is typical in the relational model, or it might be structured, as in document data stores.
• The schema might be explicit, as in the case of DDL which declares a relational table, or it might be implicit, as is commonplace in key/value stores.
• In either case, we assume that the entity is represented in Java as a class, which we call the entity class. (We will not consider generic programs which work with entity data via detyped representations.)
• Each persistent instantiation of the schema is distinguishable by a unique identifier. For example, a row of a relational database table is identifiable by the value of its primary key.
• Any persistent instantiation of the schema is representable by an instance of the entity class. In a given Java program, multiple entity class instances might represent the same persistent instance of the schema.

When there's no risk of confusion, we will often use the word “entity” to mean the entity class, or even an instance of the entity class.

A repository is a Java interface which acts as a gateway for access to persistent data of one or more entity types.

• The repository usually exposes operations for querying and retrieving entity class instances representing persistent instances of the entities.
• The repository might also expose operations for modifying data: creating new persistent instances in the data store, removing persistent instances, or modifying the state of persistent instances. Conventionally, these operations are named insert, delete, and update, respectively.
• The repository and its entities might expose only a subset of the full data set available in the data store.
• Entities belonging to a given repository might have associations between them. This is extremely common if the repository provides access to relational data. This specification does not define the semantics of associations between entities belonging to different repositories.
• Repositories are typically stateless. This specification does not address the definition of repositories backed by Jakarta Persistence-style stateful persistence contexts.

Jakarta Data allows the developer to define:

• a set of entity classes and mappings to a given data store, and
• one or more repository interfaces, written according certain rules, including the rules laid out by this specification.

Then an implementation of Jakarta Data which targets the same data store is responsible for providing an implementation of each repository interface.

[otaviojava]

Thank you.

I've proposed a PR based on what you said here and merged it with what we already had in our documentation.

Please, let me know your thoughts:

#245

[njr-11]

Thank you.

I've proposed a PR based on what you said here and merged it with what we already had in our documentation.

Please, let me know your thoughts:

#245

Thanks for contributing this. It looks great. I added a few comments no Otavio's pull, which are more related to some things he may have replaced/reworded when adding this in rather than the content as written within this issue. I do want to be careful when contributing other participants' ideas on their behalf. The best approach would be for Gavin to have created the pull with his own contributions in it. Otavio - please check that Gavin is okay with you authoring the pull with your take on his contributions within it rather than him doing so directly.

[otaviojava]

Thanks for the contribution; I'll close it.
If you have any further points, please open the issue again or open another one.