diff --git a/spec/src/main/asciidoc/jakarta-ee.adoc b/spec/src/main/asciidoc/jakarta-ee.adoc index 14577f7ed..fd7cd0906 100644 --- a/spec/src/main/asciidoc/jakarta-ee.adoc +++ b/spec/src/main/asciidoc/jakarta-ee.adoc @@ -82,15 +82,14 @@ When a repository method is annotated with an interceptor binding annotation, th === Jakarta Persistence -When integrating Jakarta Data with Jakarta Persistence, developers can leverage the JPA annotations to define the mapping of entities in repositories. Entities in Jakarta Persistence are typically annotated with `jakarta.persistence.Entity` to indicate their persistence capability. +When integrating Jakarta Data with Jakarta Persistence, a developer uses the annotations defined in `jakarta.persistence` to specify the object/relational mapping metadata for entity types stored in a relational database. -A Jakarta Data provider that supports Jakarta Persistence allows you to define repositories for classes marked with the `jakarta.persistence.Entity` annotation. +According to the Jakarta Persistence specification, every entity class should be annotated `jakarta.persistence.Entity`. Jakarta Data places an additional interpretation on this annotation, treating it as an entity-defining annotation. -By supporting Jakarta Persistence annotations, Jakarta Data providers enable Java developers to utilize familiar and standardized mapping techniques when defining entities in repositories, ensuring compatibility and interoperability with the respective technologies. +Thus, a Jakarta Data provider which supports Jakarta Persistence is able to supply an implementation of any repository whose associated entity classes are marked with the `jakarta.persistence.Entity` annotation. Typically, such an implementation simply delegates operations declared by the repository interface to the Jakarta Persistence `EntityManager`. Management of persistence contexts and integration with Jakarta Transactions remains the responsibility of the Jakarta Persistence provider. -==== Persistence Context +By supporting Jakarta Persistence, a Jakarta Data provider enables Java developers to utilize familiar and standardized mapping techniques when defining entities associated with Jakarta Data repositories, ensuring compatibility and interoperability with the respective technologies. -Repository operations must behave as though backed by a stateless Entity Manager in that persistence context is not preserved across the end of repository methods. All entities that are returned by repository methods must be in a detached state such that modifications to these entities are not persisted to the database unless the application explicitly invokes a `Save` or `Update` life cycle method for the entity. === Jakarta NoSQL diff --git a/spec/src/main/asciidoc/portability.asciidoc b/spec/src/main/asciidoc/portability.asciidoc index 2b3d0843e..82c246bc2 100644 --- a/spec/src/main/asciidoc/portability.asciidoc +++ b/spec/src/main/asciidoc/portability.asciidoc @@ -7,23 +7,47 @@ The portability that is offered by Jakarta Data pertains to usage of the Jakarta === Portability for Relational Databases -All functionality defined by Jakarta Data must be supported when using relational databases. +Jakarta Data is intended to be compatible with two very different approaches to relational data access: -==== Jakarta Persistence Annotations +- In the approach typified by Jakarta Persistence, entities are _managed objects_ associated with a _persistence context_, and have a well-defined _persistence lifecycle_. Under this approach, an entity instance maintains its association with the Jakarta Data provider between repository method calls. -A Jakarta Data provider backed by Jakarta Persistence must allow the use of `jakarta.persistence.Entity` as an entity-defining annotation. +- In the _persistence context free_ approach, entity instances are unmanaged objects, and their association with the Jakarta Data provider never outlasts a single call to a lifecycle method or query method of a repository. -==== Built-In Repositories +The two approaches feature very different patterns of interaction with the repository, and it is not a goal of Jakarta Data to abstract away the differences. -Jakarta Data's built-in repositories, such as `BasicRepository` and `CrudRepository`, are designed to offer consistent and well-defined methods compatible with relational databases. Developers can rely on these repositories to perform common data access tasks. +Regardless of the approach, a Jakarta Data provider backed by access to relational data must fully support Jakarta Data query methods, including pagination, ordering, and limiting, subject to the caveats specified below. -==== Query Methods +==== Jakarta Persistence -Jakarta Data's support for query methods, including pagination, ordering, and limiting, is designed to work seamlessly with relational databases. +In Jakarta Persistence, an instance of `EntityManager` reifies access to a given persistence context. +Jakarta Persistence does not currently support the persistence context free approach. -All limitations of Jakarta Persistence, the respective Jakarta Persistence provider, JPQL, SQL, and the database apply when using entities that are annotated with `jakarta.persistence.Entity`. Repository methods must correspond to operations that are valid via `JPQL` and `SQL` queries. For example, although one can write a repository method that asks for sorting by a collection attribute or attempts to perform a Like operation on a numeric type rather than a String, there is no expectation for a Jakarta Data provider to support doing so because Jakarta Persistence, JPQL, and SQL do not offer the ability. +A Jakarta Data provider backed by Jakarta Persistence must: -By aligning Jakarta Data closely with relational databases, developers can expect high portability and compatibility. This approach ensures that Jakarta Data remains a powerful tool for simplifying data access, irrespective of the specific relational database used. +- allow the use of `jakarta.persistence.Entity` as an entity-defining annotation, +- along with resource accessor methods of type `jakarta.persistence.EntityManager`. + +A Jakarta Data provider backed by Jakarta Persistence should define a query annotation accepting JPQL as the query language, along with an annotation accepting native SQL as the query language. + +[CAUTION] +==== +This release of Jakarta Data does not standardize lifecycle annotations or query annotations for use with Jakarta Data providers backed by Jakarta Persistence. +==== + +The Jakarta Persistence specification, the respective Jakarta Persistence provider, JPQL, SQL, and the database all set limitations on what is possible for a repository implementation backed by Jakarta Persistence. All such limitations apply when the entities associated with a Jakarta Data repository are declared using the annotation `jakarta.persistence.Entity`. In particular, repository query methods must correspond to operations which are legal JPQL and SQL queries. + +For example, although one can write a repository method that asks for sorting by a collection attribute or attempts to perform a Like operation on a numeric type rather than a String, there is no expectation that a Jakarta Data provider backed by Jakarta Persistence should be able to supply an implementation of such a repository. + +==== Other Relational Data Access Technologies + +A Jakarta Data provider for relational data does not need to be based on Jakarta Persistence, and is not required to feature persistence contexts. + +A Jakarta Data provider based on persistence context free access to relational data must support the built-in lifecycle annotations `@Insert`, `@Update`, and `@Delete`, along with the built-in repository types `BasicRepository` and `CrudRepository`. + +If the provider is backed by JDBC, it should support resource accessor methods of type `java.sql.Connection`. + +As above, the SQL dialect and the database set limits on what operations are implementable. +The Jakarta Data provider is not required to supply an implementation of a repository which declares query methods mapping to operations which are not supported by the database itself. === Portability for NoSQL Databases