Jakarta Data

By using and/or copying this document, or the Eclipse Foundation document from which this statement is linked or incorporated by reference, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:

Permission to copy, and distribute the contents of this document, or the Eclipse Foundation document from which this statement is linked, in any medium for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the document, or portions thereof, that you use:

Inclusion of the full text of this NOTICE must be provided. We request that authorship attribution be provided in any software, documents, or other items or products that you create pursuant to the implementation of the contents of this document, or any portion thereof.

No right to create modifications or derivatives of Eclipse Foundation documents is granted pursuant to this license, except anyone may prepare and distribute derivative works and portions of this document in software that implements the specification, in supporting materials accompanying such software, and in documentation of such software, PROVIDED that all such works include the notice below. HOWEVER, the publication of derivative works of this document for use as a technical specification is expressly prohibited.

The notice is:

The name and trademarks of the copyright holders or the Eclipse Foundation AISBL may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.

Jakarta Data addresses a fundamental challenge in Java application development: the seamless integration of diverse data sources amid the dissimilarities in their respective programming models. Offering the Java developer a common, familiar starting point for data access is helpful for solutions involving multiple databases and storage technologies.

The primary problem Jakarta Data sets out to solve is the complexity and inconsistency that arises when Java applications encounter various database systems—relational, document, column, key-value, graph, and others. Managing these diverse data sources can be daunting, often requiring developers to write specialized code for each storage technology.

Jakarta Data combines the concept of a persistence agnostic API with a domain-centric approach. This approach enables developers to work with different databases and storage engines while aligning their data access strategies with the core principles of a domain-centric architecture, where the domain model plays a central role in shaping the application’s structure.

Jakarta Data is guided by a set of clear and well-defined objectives to simplify data integration and enhance data access for Java developers. These objectives serve as the pillars of its design philosophy, ensuring that it addresses real-world challenges and provides concrete advantages to developers:

The following are not goals of Jakarta Data:

The term entity attribute, and in some places persistent attribute, is used through the Jakarta Data specification to refer to a field or property of an Entity that is persisted to a data store. The Jakarta Persistence specification also uses these terms, as well as the term persistent fields and properties, which has the same meaning. Additionally, the Jakarta Data specification sometimes refers to an entity attribute by its name. For example, the price attribute of the Product entity. In other cases, an entity attribute is referred to by what it represents. For example, an entity’s Id attribute or Version attribute.

This specification is being developed as part of Jakarta Data project under the Jakarta EE Specification Process. It is the result of the collaborative work of the project committers and various contributors.

Within the context of Jakarta Data, the repository plays a pivotal role in simplifying data access for various persistence stores. The repository is a Java interface that acts as a gateway for accessing persistent data of one or more entity types. Repositories offer a streamlined approach to working with data by exposing operations for querying, retrieving, and modifying entity class instances that represent data in the persistent store.

Several characteristics define repositories:

Repositories in Jakarta Data serve as efficient gateways for managing and interacting with persistent data, offering a simplified and consistent approach to data access and modification within Java applications.

The application must provide the following when using repositories in Jakarta Data:

An implementation of Jakarta Data, specifically tailored to the chosen data store, assumes the responsibility of implementing each repository interface. This symbiotic relationship between developers and Jakarta Data ensures that data access and manipulation remain consistent, efficient, and aligned with best practices.

Jakarta Data empowers developers to shape their data access strategies by defining entity classes and repositories, with implementations seamlessly adapting to the chosen data store. This flexibility and Jakarta Data’s persistence-agnostic approach promote robust data management within Java applications.

The Jakarta Data specification supports two basic ways to define a repository interface:

A Java developer creates an interface, marks it with the @Repository annotation, and has the option to extend one or more built-in generic repository interfaces, or to annotate its lifecycle methods.

Jakarta Data provides two core ways to express queries:

Newly written code should use these approaches. A typical application based on Jakarta Data uses a mix of both approaches, with the choice of approach depending on the complexity of the query.

As an extension to the core specification, Jakarta Data 1.0 offers a Query by Method Name facility to provide a migration path for existing applications written for repository frameworks which offer similar functionality. Query by Method name is described in a companion document to this specification.

A Jakarta Data provider is required to support the Query by Method Name extension in Jakarta Data 1.0. This requirement will be removed in a future version of Jakarta Data.

A programming model for entity classes specifies:

Jakarta Data does not define its own programming model for entities, but instead:

This section lays out the core requirements that an entity programming model must satisfy in order to be compatible with Jakarta Data, and for the defining provider to be considered a fully-compliant implementation of this specification.

Every entity programming model specifies an entity-defining annotation. For Jakarta Persistence, this is jakarta.persistence.Entity. For Jakarta NoSQL, it is jakarta.nosql.Entity. A Jakarta Data provider must provide repository implementations for entity classes bearing the entity-defining annotations it supports, and must ignore entity classes with entity-defining annotations it does not support.

Furthermore, an entity programming model must define an annotation which identifies the attribute holding the unique identifier of an entity. For Jakarta Persistence, it is jakarta.persistence.Id or jakarta.persistence.EmbeddedId. For Jakarta NoSQL, it is jakarta.nosql.Id. Alternatively, an entity programming model might allow the identifier attribute to be identified via some convention.

Typically, an entity programming model specifies additional annotations which are used to make the schema of the entity explicit, for example, jakarta.persistence.Id and jakarta.persistence.Column, or jakarta.nosql.Id and jakarta.nosql.Column. The nature of such annotations is beyond the scope of this specification.

In a given entity programming model, entity classes might always be mutable, or might always be immutable, or, alternatively, the model might support a mix of mutable and immutable entity classes.

In either case, an entity programming model might place restrictions on the visibility of fields and property accessors of an entity class.

Entities and their persistent attributes may be referenced by name in the query language defined in Jakarta Common Query Language.

Jakarta Data provides a static metamodel that allows entity attributes to be accessed by applications in a type-safe manner.

For each entity class, the application developer or a compile-time annotation processor can define a corresponding metamodel class following a prescribed set of conventions.

The application can use the field values of the metamodel class to obtain artifacts relating to the entity attribute in a type-safe manner, for example, _Book.title.asc() or Sort.asc(_Book.title.name()) or Sort.asc(_Book.TITLE) rather than Sort.asc("title").

A lifecycle method is an abstract method annotated with a lifecycle annotation. Lifecycle methods allow the program to make changes to persistent data in the data store.

A lifecycle method must be annotated with a lifecycle annotation. The method signature of the lifecycle method, including its return type, must follow the requirements that are specified by the Javadoc of the lifecycle annotation.

Lifecycle method signatures follow one of these generic patterns:

where Lifecycle is a lifecycle annotation, lifecycle is the arbitrary name of the method, and Entity is either E, List<E>, or E[], where E is a concrete entity class. In this context, any variadic parameter declared E…​ is treated as if it were declared with type E[].

This specification defines two sets of built-in lifecycle annotations:

The semantics of a lifecycle method annotated with one of these annotations are defined by the Javadoc of the annotation.

For example:

Lifecycle methods are not guaranteed to be portable between all providers.

Jakarta Data providers must support lifecycle methods to the extent that the data store is capable of the corresponding operation. If the data store is not capable of the operation, the Jakarta Data provider must raise UnsupportedOperationException when the operation is attempted, per the requirements of the Javadoc for the lifecycle annotation, or the Jakarta Data provider must report the error at compile time.

There is no special programming model for lifecycle annotations. The Jakarta Data implementation automatically recognizes the lifecycle annotations it supports.

An annotated query method is an abstract method annotated by a query annotation type. The query annotation specifies a query in some datastore-native query language.

Each parameter of an annotated query method must either:

A repository with annotated query methods with named parameters must be compiled so that parameter names are preserved in the class file (for example, using javac -parameters), or the parameter names must be specified explicitly using the @Param annotation.

An annotated query method must not also be annotated with a lifecycle annotation.

The return type of the annotated query method must be consistent with the result type of the query specified by the query annotation.

This specification defines the built-in @Query annotation, which may be used to specify a query written in the Jakarta Common Query Language defined in the next chapter.

For example, using a named parameter:

Or, using a positional parameter:

Programs which make use of annotated query methods are not in general portable between providers. However, when the @Query annotation specifies a query written in JCQL, the annotated query method is portable between providers to the extent to which its semantics can be implemented on the underlying data store.

There is no special programming model for query annotations. The Jakarta Data implementation automatically recognizes the query annotations it supports.

A parameter-based automatic query method is an abstract method annotated with an automatic query annotation.

Each automatic query method must be assigned an entity type. The rules for inferring the entity type depend on the semantics of the automatic query annotation. Typically:

Jakarta Data infers a query based on the parameters of the method. Each parameter must either:

Parameter names map parameters to persistent attributes. A repository with parameter-based automatic query methods must either:

The attribute name specified using @By may be a compound name, as specified below in Persistent attribute names.

This specification defines the built-in automatic query annotations @Find and @Delete. The semantics of these annotations are specified in their Javadoc. Note that @Delete is both a lifecycle annotation and an automatic query annotation. The signature of a repository method annotated @Delete must be used to disambiguate the interpretation of the @Delete annotation.

For example:

Automatic query methods annotated with @Find or @Delete are portable between providers.

A resource accessor method is a method with no parameters which returns a type supported by the Jakarta Data provider. The purpose of this method is to provide the program with direct access to the data store.

For example, if the Jakarta Data provider is based on JDBC, the return type might be java.sql.Connection or javax.sql.DataSource. Or, if the Jakarta Data provider is backed by Jakarta Persistence, the return type might be jakarta.persistence.EntityManager.

The Jakarta Data provider recognizes the connection types it supports and implements the method such that it returns an instance of the type of resource. If the resource type implements java.lang.AutoCloseable and the resource is obtained within the scope of a default method of the repository, then the Jakarta Data provider automatically closes the resource upon completion of the default method. If the method for obtaining the resource is invoked outside the scope of a default method of the repository, then the user is responsible for closing the resource instance.

For example:

A repository may have at most one resource accessor method.

A resource accessor method with return type jakarta.persistence.EntityManager should only be declared by a stateful repository.

Annotations like @Find, @Query, @Insert, @Update, @Delete, and @Save are mutually-exclusive. A given method of a repository interface may have at most one:

If a method of a repository interface has more than one such annotation, the annotated repository method must raise UnsupportedOperationException every time it is called. Alternatively, a Jakarta Data provider is permitted to reject such a method declaration at compile time.

An annotated, parameter-based, or Query by Method Name query method may have special parameters of type Sort, Order, Limit, or PageRequest if the method return type indicates that the method may return multiple entities, that is, if the return type is:

Any annotated or parameter-based query method may also have a special parameter of type Restriction.

A special parameter controls which query results are returned to the caller of a repository method, or in what order the results are returned:

The types Restriction, Sort, and Order are parameterized by an entity type. Any special parameter declared with one of these types must be declared with type argument E or ? super E where E is the queried entity type. Usage of the generic type argument ? in a special parameter of type Sort<?>…​ is deprecated.

For example, this repository method allows a list of cars to be filtered and sorted by attributes of Car or of its supertype Vehicle:

A repository method throws NullPointerException if an argument to a special parameter of the method is null.

A repository method must throw UnsupportedOperationException if it has:

Alternatively, a Jakarta Data provider is permitted to reject such a repository method declaration at compile time.

A repository method must throw DataException if the database is incapable of ordering the query results using the given sort criteria.

The following example demonstrates the use of special parameters:

An instance of Sort may be obtained by specifying an entity attribute name:

Even better, the static metamodel may be used to obtain an instance of Sort in a typesafe way:

This PageRequest specifies a starting page and maximum page size:

The specification defines different ways of providing sort criteria on queries. This section discusses how these different mechanisms relate to each other.

A method annotated @Find, @Delete, or @Query may have a special parameter of type Restriction<T>. This parameter allows the caller of a repository method to programmatically express additional restrictions on the results returned by the repository method, often using a generated metamodel class for type safety.

For example:

Programmatic restrictions passed to a parameter of type Restriction combine conjunctively with static restrictions:

For example:

The static methods Restrict.all(…​) or Restrict.any(…​) allow restrictions to be combined:

Instances of Restriction<T> are immutable and may be reused across multiple repository calls.

Dividing up large sets of data into pages is a beneficial strategy for data access and retrieval in many applications, including those developed in Java. Pagination helps improve the efficiency of handling large datasets in a way that is also user-friendly. In Jakarta Data, APIs are provided to help Java developers efficiently manage and navigate through data.

Jakarta Data supports two types of pagination: offset-based and cursor-based. These approaches differ in how they manage and retrieve paginated data:

Offset pagination is the more traditional form based on position relative to the first record in the dataset. It is typically used with a fixed page size, where a specified number of records is retrieved starting from a given offset position.

Cursor-based pagination, also known as seek method or keyset pagination, uses a unique key or unique combination of values (referred to as the key) to navigate the dataset relative to the first or last record of the current page. Cursor-based pagination is typically used with fixed page sizes but can accommodate varying the page size if desired. It is more robust when dealing with datasets where the underlying data might change and offers the the potential for improved performance by avoiding the need to scan records prior to the cursor.

The critical differences between offset-based and cursor-based pagination lie in their retrieval methods:

The following order, with the lower number having higher precedence, is used when interpreting the meaning of repository methods.

A repository method that does not fit any of the above patterns and is not handled as a vendor-specific extension to the specification must either result in an error at build time or raise UnsupportedOperationException at runtime.

When a repository method is called with a null value as an argument to one of its parameters, the repository implementation might throw an exception:

An asynchronous repository method is a repository method which returns an object representing a value which will eventually be obtained from the database, but which might not yet be available. An asynchronous repository method is permitted to return such an object immediately, and access the database asynchronously.

An asynchronous repository method has a signature of form:

where:

For example, the following is an asynchronous parameter-based query method that relies on the Jakarta Concurrency @Asynchronous interceptor to control the asynchronous behavior:

This method is an asynchronous lifecycle method that relies on the Jakarta Data provider to control the asynchronous behavior:

An asynchronous repository is a repository which declares asynchronous repository methods. A repository may declare a mixture of synchronous and asynchronous repository methods if every asynchronous method is annotated with the @Asynchronous annotation, so that Jakarta Concurrency provides the asynchronous behavior. Otherwise, the Jakarta Data provider is not required to support mixing synchronous and asynchronous repository methods within the same repository interface. The @Asynchronous annotation must not be used on repositories implemented using reactive streams.

Repositories in Jakarta Data are usually stateless. That is, the repository does not maintain any relationship with any entity instance across invocations of repository methods. Any instance of an entity class may be passed to a method of a stateless repository which accepts the entity type.

A stateful repository is a repository which maintains an association with a set of managed entity instances. Support for stateful repositories is defined in the dedicated module jakarta.data.stateful.

Jakarta Data imposes some additional requirements when a repository query method is annotated to run a JCQL query.

This section describes some limitations on JCQL queries that apply when accessing a non-relational datastore.

A Jakarta Data provider must supply an implementation of each repository interface which either:

The repository implementation and the Jakarta Data provider are responsible for mediating interaction between the application program and the datastore, often taking advantage of other Jakarta EE services such as datasource provisioning and transaction management.

An application usually obtains a reference to an implementation of a repository via dependency injection. Therefore, the provider must make its repository implementations available to the bean container responsible for dependency injection.

Multiple Jakarta Data providers may coexist within a single program and provide repository implementations. It is the responsibility of the application developer to ensure that each repository is eligible for implementation by exactly one provider, according to the rules specified below.

A Jakarta Data provider typically supports one entity-defining annotation type, but it may support multiple entity-defining annotation types. A provider may even have no entity-defining annotation and feature a programming model for entity classes where the entity classes are unannotated.

In particular:

A Jakarta Data provider might define a custom entity-defining annotation. Custom entity-defining annotations must be marked with @EntityDefining. This allows other Jakarta Data providers and tools to recognize and process entities declared with custom entity-defining annotations.

The lifecycle methods and query methods of a repository operate on a set of entities associated with that repository. All entities associated with a given repository should be declared using the same entity-defining annotation type. If the entities associated with a given repository are declared using a mix of annotation types, the behavior is undefined by this specification.

A Jakarta Data provider must ignore every repository associated with entity classes declared using an entity-defining annotation which is available at runtime, but not recognized by the provider, allowing another Jakarta Data provider to supply the implementation.

On the other hand, if an entity class is annotated with an entity-defining annotation which is not available at runtime, the Jakarta Data provider must completely ignore the annotation, and treat the entity as if that entity-defining annotation were missing.

The entity-defining annotation type is the preferred way to avoid conflicts between Jakarta Data providers. But when multiple Jakarta Data providers support the same entity-defining annotation, the application must disambiguate the Jakarta Data provider for a repository by explicitly specifying the provider attribute of the Repository annotation.

A Jakarta Data provider must ignore every repository which specifies the name of a different provider in its @Repository annotation.

Contexts and Dependency Injection ^[5] (CDI) is a specification in the Jakarta EE Core profile that provides a powerful and flexible dependency injection framework for Java applications. CDI provides a programming model based around decoupled components with container-managed lifecycles and container-injected dependencies, enabling loose coupling and promoting modular and reusable code.

A repository interface or method of a repository interface may be annotated with an interceptor binding annotation. In the Jakarta EE environment—​or in any other environment where Jakarta Interceptors ^[6] is available and integrated with Jakarta CDI—​if the repository implementation is instantiated by the CDI bean container then the interceptor binding annotation is inherited by the repository implementation. That is, the interceptor binding annotation must be treated as if it were placed directly on the repository implementation bean. The interceptors bound to the annotation are applied automatically by the implementation of Jakarta Interceptors.

Work performed by a repository might occur within the scope of a transaction managed by Jakarta Transactions.^[7] This is usually transparent to the code acting as client of the repository. When:

then the repository operation must be performed within the context of the global transaction. That is, the data source resources involved in the operation must be enlisted as participants in the transaction.

The repository operation must not commit or roll back a transaction which was already associated with the thread in which the repository operation was called, but it might cause the transaction to be marked for rollback if the repository operation fails, that is, it may set the transaction status to jakarta.transaction.Status.STATUS_MARKED_ROLLBACK.

A repository interface or method of a repository interface may be marked with the annotation jakarta.transaction.Transactional. When a repository operation marked @Transactional is called in an environment where both Jakarta Transactions and Jakarta CDI are available, the semantics of this annotation must be observed during execution of the repository operation.

Integration with Jakarta Persistence is left undefined in this first release of Jakarta Data.

When integrating Jakarta Data with Jakarta NoSQL, developers can use the NoSQL annotations to define the mapping of entities in repositories. Entities in Jakarta NoSQL are typically annotated with jakarta.nosql.Entity to indicate their suitability for persistence in NoSQL databases.

A Jakarta Data provider that supports Jakarta NoSQL will scan classes marked with the jakarta.nosql.Entity annotation.

By supporting Jakarta NoSQL 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.

Integrating with Jakarta Bean Validation ^[8] ensures data consistency within the Java layer. By applying validation rules to the data, developers can enforce constraints and business rules, preventing invalid or inconsistent information from being processed or persisted.

Using Jakarta Validation brings several advantages. It helps maintain data integrity, improves data quality, and enhances the reliability of the application. Catching validation errors early in the Java layer can identify and resolve potential issues before further processing or persistence occurs. Additionally, Jakarta Validation allows for declarative validation rules, simplifying the validation logic and promoting cleaner and more maintainable code.

In Jakarta Data, repository methods participate in method validation as defined by the section "Method and constructor validation" of the Jakarta Validation specification. Method validation includes validation of constraints on method parameters and results. The jakarta.validation.Valid annotation is used to opt in to cascading validation that validates constraints that are found on an object that is supplied as a parameter or returned as a result.

The following code snippet demonstrates the usage of Jakarta Validation annotations in the Student entity class:

In this example, the name field is annotated with @NotBlank, indicating that it must not be blank. The age field is annotated with both @Positive and @Min(18), ensuring it is a positive integer greater than or equal to 18.

The School repository interface, shown below, uses the jakarta.validation.Valid annotation to cause the constraints from the Student entity to be validated during the save operation, whereas the validation constraints are not applied to the Student entities returned as a result of the findByAgeLessThanEqual operation because the findByAgeLessThanEqual method does not include a jakarta.validation.Valid annotation that applies to the return value.

A Jakarta Data provider backed by 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. It must also fully support Jakarta Data query methods, including pagination, ordering, and limiting, subject to the caveat that follows.

If the provider is backed by JDBC, it should support resource accessor methods of type java.sql.Connection.

Portability in Jakarta Data extends to various NoSQL databases, each presenting unique challenges and capabilities. Jakarta Data aims to provide a consistent experience across these NoSQL database types. This section covers the key portability aspects for four categories of NoSQL databases: key-value, wide-column, document, and graph databases.

The ability to supply generic, untyped Sort criteria to a repository method by means of a variable arguments Sort<?>…​ parameter is deprecated. Use an Order parameter instead.

For example,

is replaced by,