Jakarta Data

The complete list of Jakarta Data contributors may be found here.

Jakarta Data defines a hierarchy of built-in interfaces which user-defined repositories may inherit. At the root of this hierarchy is the DataRepository interface. A repository is permitted to extend one or more of the members of the hierarchy, or none at all. When a repository extends a built-in interface, the implementation of every method inherited from the built-in interface must preserve the semantics specified by the built-in interface.

A repository which extends a built-in supertype usually acts as a home for operations acting on a single entity type called the primary entity type of the repository. The primary entity type is determined by the argument to the first generic type variable of the generic supertype.

Given a Product entity with ID of type long, the repository could be as simple as:

There is no nomenclature restriction requiring the Repository suffix. For example, a repository for the Car entity does not need to be named CarRepository. It could be named Cars, Vehicles, or even Garage.

Alternatively, Jakarta Data allows a custom repository interface which does not extend any built-in type. This option:

In this approach, database operations involving fundamental data changes, such as insertion, update, and removal, are realized via the use of lifecycle annotations like @Insert, @Update, @Delete, and @Save. These annotations enable the crafting of expressive and contextually meaningful repository methods, resulting in a repository API that closely mirrors the semantics of the domain.

For instance, consider the Garage repository interface below:

Notice that the @Insert annotation is used to declare the park() method.

The previous example illustrates the design of a repository interface which captures some of the essence of the business domain. This approach fosters a shared understanding and more intuitive communication within the development team, with database operations named according to the language of the domain.

An entity programming model might support inheritance between entities. Two entities are related by inheritance if:

It’s possible for two entity classes to be related by Java inheritance, but not by entity inheritance in the sense defined here. An entity programming model specifies which Java inheritance relationships are interpreted as entity inheritance.

When entities are related by inheritance, a query method which returns the entity supertype might also return instances of its subtypes.

The Jakarta Data provider determines how entity classes which participate in an entity inheritance hierarchy "map" to the data schema. For example, in a relational datastore, all entities in the hierarchy might be stored together on one table, or each entity might have its own dedicated table.

Support for entity inheritance is not required by this specification.

A field of an entity class may or may not represent state which is persistent in the datastore. A persistent field has some corresponding representation in the data schema of the entity, for example, it might map to a column or columns in a relational database table. Any programming model for entity classes must provide well-defined rules for distinguishing fields which are persistent in the datastore from which fields are transient, having no persistent representation in the datastore. Furthermore, the programming model must specify how the Jakarta Data provider accesses the persistent fields of an entity to read and write their values.

Every programming model for entity classes must support direct field access, that is, access to the persistent fields of an entity class without triggering any intermediating user-written code such as JavaBeans-style property accessors. When direct field access is used, every Java field marked with the Java language transient modifier must be treated as transient. A programming model might place constraints on the visibility of persistent fields. For example, Jakarta Persistence disallows public persistent fields. Every programming model must permit private persistent fields.

A programming model for entity classes might also support property-based access, that is, access to persistent fields via JavaBeans-style property accessors, or, especially for Java record types, via accessor methods combined with constructor-based initialization. Such programming models should provide an annotation or other convention to distinguish transient properties. For example, Jakarta Persistence provides jakarta.persistence.Transient. When property-based access is supported, a programming model might place constraints on the visibility of property accessors. For example, Jakarta Persistence requires that property accessors be public or protected. Support for property-based access is not required by this specification.

Jakarta Data distinguishes three kinds of persistent field within entity classes.

Every Jakarta Data provider must support the following basic types within its programming model:

For example, the following entity class has five basic fields:

In addition to the types listed above, an entity programming model might support additional domain-specific basic types. This extended set of basic types might include types with a nontrivial internal structure. An entity programming model might even provide mechanisms to convert between user-written types and natively-supported basic types. For example, Jakarta Persistence defines the AttributeConverter interface.

An embeddable class differs from an entity class in that:

An embedded field is a field whose type is an embeddable class.

Like entities, embeddable classes may have basic fields, embeddable fields, and association fields, but, unlike entities, they do not have identifier fields.

Like entities, a programming model for entity classes might support mutable embeddable classes, immutable embeddable classes, or both.

A programming model for entity classes might define an annotation that identifies a user-written class as an embeddable class. For example, Jakarta Persistence defines the annotation jakarta.persistence.Embeddabe. Alternatively, the programming model might define an annotation that identifies a field as an embedded field. For example, Jakarta Persistence defines the annotation jakarta.persistence.Embedded.

There are two natural ways that a Jakarta Data provider might store the state of an instance of an embedded class in a database:

In a flattened representation of an embedded field, the fields of the embeddable class occur directly alongside the basic fields of the entity class in the data schema of the entity. There is no representation of the embeddable class itself in the data schema.

For example, consider the following Java classes:

In a document, wide-column, or graph database, the JSON representation of an instance of the Person entity might be as follows:

Or, in a relational database, the DDL for the Person table might look like this:

In a structured representation, the fields of the embeddable class are somehow grouped together in the data schema.

For example, the JSON representation of Person might be:

Or the SQL DDL could be:

An association field is a field of an entity class whose declared type is also an entity class. Given an instance of the first entity class, its association field holds a reference to an instance of a second entity class.

For example, consider the following Java classes:

In a relational database, these entities might map to the following data schema:

Each entity must be assigned an entity name by the provider. By default, this must be the unqualified Java class name of the entity class. A programming model for entity classes might provide a way to explicitly specify an entity name. For example, Jakarta Persistence allows the entity name to be specified via the name member of the @Entity annotation.

Each persistent field of an entity, as defined above in Persistent Fields, or of an embeddable class, as defined in Embedded Fields and Embeddable Classes, must be assigned a name, allowing the persistent field to be referenced by an automatic query method, a Query by Method Name, or from a query specified within the @Query annotation.

Any programming model for entity classes which supports property-based access must also define a rule for assigning names to persistent fields. Typically, a property with accessors named getX and setX is assigned a persistent field name obtained by calling java.beans.Introspector.decapitalize("X").

Within a given entity class or embeddable class, names assigned to persistent fields must be unique ignoring case. A Jakarta Data provider is permitted to reject an entity class if two persistent fields would be assigned the same name.

Furthermore, within the context of a given entity, each persistent field of an embeddable class reachable by navigation from the entity class may be assigned a compound name. The compound name is obtained by concatenating the names assigned to each field traversed by navigation from the entity class to the persistent field of the embedded class, optionally joined by a delimiter.

The rule for concatenating compound names depends on the context, and is specified in Field Name Concatenation and Delimiters. The examples in the table assume an Order entity has an address of type MailingAddress with a zipCode of type int.

When an application programmer writes a static metamodel class for an entity by hand:

The static metamodel class is not required to include a field for every persistent field of the entity.

A convenience implementation of each subinterface of Attribute is provided in the package jakarta.data.metamodel.impl.

When an annotation processor generates a static metamodel class for an entity:

The fields may be statically initialized, or they may be initialized by the provider during system initialization.

The following are conventions for static metamodel classes:

Example entity class:

Example metamodel class for the entity:

Example usage:

Sort criteria can be hard-coded directly within query language by making use of the @Query annotation. A repository method that is annotated with @Query with a value that contains an ORDER BY clause (or query language equivalent) must not provide sort criteria via the other mechanisms.

A repository method that is annotated with @Query with a value that does not contain an ORDER BY clause and ends with a WHERE clause (or query language equivalents to these) can use other mechanisms that are defined by this specification for providing sort criteria.

Sort criteria are provided statically for a repository method by using the OrderBy keyword or by annotating the method with one or more @OrderBy annotations. The OrderBy keyword cannot be intermixed with the @OrderBy annotation or the @Query annotation. Static sort criteria takes precedence over dynamic sort criteria in that static sort criteria are evaluated first. When static sort criteria sorts entities to the same position, dynamic sort criteria are applied to further order those entities.

Sort criteria are provided dynamically to repository methods either via Sort parameters or via a Order parameter that has one or more Sort values.

In the following examples, the query results are sorted by age, using the dynamic sorting criteria passed to the sorts parameter to break ties between records with the same age.

Offset pagination is a popular method for managing and retrieving large datasets efficiently. It is based on dividing the dataset into pages containing a specified number of elements. This method allows developers to retrieve a subset of the dataset by identifying the page number and the maximum number of elements per page.

Offset pagination is motivated by the need to provide efficient navigation through large datasets. Loading an entire dataset into memory at once can be resource-intensive and lead to performance issues. By breaking the dataset into smaller, manageable pages, offset pagination improves performance, reduces resource consumption, and enhances the overall user experience.

Offset pagination offers several key features that make it a valuable approach for managing and retrieving large datasets in a controlled and efficient manner:

Cursor-based pagination aims to reduce missed and duplicate results across pages by querying relative to the observed values of entity properties that constitute the sorting criteria. Cursor-based pagination can also offer an improvement in performance because it avoids fetching and ordering results from prior pages by causing those results to be non-matching. A Jakarta Data provider appends additional conditions to the query and tracks cursor-based values automatically when CursoredPage is used as the repository method return type. The application invokes nextPageRequest or previousPageRequest on the CursoredPage to obtain a PageRequest which keeps track of the cursor-based values.

For example,

You can obtain the initial page relative to an offset and subsequent pages relative to the last entity of the current page as follows,

Or you can obtain the next (or previous) page relative to a known entity,

The sort criteria for a repository method that performs cursor-based pagination must uniquely identify each entity and must be provided by:

The values of the entity attributes of the combined sort criteria define the cursor for cursor-based cursor based pagination. Within the cursor, each entity attribute has the same sorting and order of precedence that it has within the combined sort criteria.

An identifier is any legal Java identifier which is not a keyword. Identifiers are case-sensitive: hello, Hello, and HELLO are distinct identifiers.

In the JDQL grammar, identifiers are labelled with the IDENTIFIER token type.

The following identifiers are keywords: select, update, set, delete, from, where, order, by, asc, desc, not, and, or, between, like, in, null, local, true, false. In addition, every reserved identifier listed in section 4.4.1 of the Jakarta Persistence specification version 3.2 is also considered a reserved identifier. Keywords and other reserved identifiers are case-insensitive: null, Null, and NULL are three ways to write the same keyword.

A named parameter is a legal Java identifier prefixed with the : character, for example, :name.

An ordinal parameter is a decimal integer prefixed with the ? character, for example, ?1.

Ordinal parameters are numbered sequentially, starting with ?1.

The character sequences +, -, *, /, ||, =, <, >, <>, <=, >= are operators.

The characters (, ), and , are punctuation characters.

A literal string is a character sequence quoted using the character '.

A single literal ' character may be included within a string literal by self-escaping it, that is, by writing ''. For example, the string literal 'Furry''s theorem has nothing to do with furries.' evaluates to the string Furry's theorem has nothing to do with furries..

In the grammar, literal strings are labelled with the STRING token type.

Numeric literals come in two flavors:

In the grammar, integer and decimal literals are labelled with the INTEGER and DOUBLE token types respectively.

The characters Space, Horizontal Tab, Line Feed, Form Feed, and Carriage Return are considered whitespace characters and make no contribution to the token stream.

As usual, token recognition is "greedy". Therefore, whitespace must be placed between two tokens when:

A string, integer, or decimal literal is assigned the type it would be assigned in Java. So, for example, 'Hello' is assigned the type java.lang.String, 123 is assigned the type int, 1e4 is assigned the type double, and 1.23f is assigned the type float.

The syntax for literal expressions is given by the literal grammar rule, and in the previous section titled Lexical structure.

When executed, a literal expression evaluates to its literal value.

The special values true and false are assigned the type boolean, and evaluate to their literal values.

The special values local date, local time, and local datetime are assigned the types java.time.LocalDate, java.time.LocalTime, and java.time.LocalDateTime, and evaluate to the current date and current datetime of the database server, respectively.

The syntax for special values is given by the special_expression grammar rule.

A parameter expression, with syntax given by input_parameter, is assigned the type of the repository method parameter it matches. For example, the parameter :titlePattern is assigned the type java.lang.String:

When executed, a parameter expression evaluates to the argument supplied to the parameter of the repository method.

An enum literal expression is a Java identifier, with syntax specified by enum_literal, and may only occur as the right operand of a set assignment or =/<> equality comparison. It is assigned the type of the left operand of the assignment or comparison. The type must be a Java enum type, and the identifier must be the name of an enumerated value of the enum type including the fully qualified Java enum class name. For example, day <> java.time.DayOfWeek.MONDAY is a legal comparison expression.

When executed, an enum expression evaluates to the named member of the Java enum type.

A path expression is a period-separated list of Java identifiers, with syntax specified by state_field_path_expression. Each identifier is interpreted as the name of a field of an entity or embeddable class. Each prefix of the list is assigned a Java type:

The type of the whole path expression is the type of the last element of the list. For example, pages is assigned the type int, address is assigned the type org.example.Address, and address.street is assigned the type java.lang.String.

When a path expression is executed, each element of the path is evaluated in turn:

If any element of a path expression evaluates to a null value, the whole path expression evaluates to a null value.

A function call is the name of a JDQL function, followed by a parenthesized list of argument expressions, with syntax given by function_expression.

When any argument expression of any function call evaluates to a null value, the whole function call evaluates to null.

If the JDQL implementation does not support a standard function explicitly listed above, it must throw UnsupportedOperationException when the function name occurs in a query. Alternatively, the Jakarta Data provider is permitted to reject a repository method declaration at compilation time if its @Query annotation uses an unsupported function.

The syntax of an operator expression is given by the scalar_expression rule. Within an operator expression, parentheses indicate grouping.

All binary infix operators are left-associative. The relative precedence, from highest to lowest precedence, is given by:

The unary prefix operators + and - have higher precedence than the binary infix operators. Thus, 2 * -3 + 5 means (2 * (-3)) + 5 and evaluates to -1.

The concatenation operator || is assigned the type java.lang.String. Its operand expressions must also be of type java.lang.String. When executed, a concatenation operator expression evaluates to a new string concatenating the strings to which its arguments evaluate.

The numeric operators +, -, *, and / have the same meaning for primitive numeric types they have in Java, and operator expression involving these operators are assigned the types they would be assigned in Java.

The four numeric operators may also be applied to an operand of wrapper type, for example, to java.lang.Integer or java.lang.Double. In this case, the operator expression is assigned a wrapper type, and evaluates to a null value when either of its operands evaluates to a null value. When both operands are non-null, the semantics are identical to the semantics of an operator expression involving the corresponding primitive types.

The four numeric operators may also be applied to operands of type java.math.BigInteger or java.math.BigDecimal.

A numeric operator expression is evaluated according to the native semantics of the database. In translating an operator expression to the native query language of the database, a Jakarta Data provider is encouraged, but not required, to apply reasonable transformations so that evaluation of the expression more closely mimics the semantics of the Java language.

The type assigned to an operator expression depends on the types of its operand expression, which need not be identical. The rules for numeric promotion are given in section 4.7 of the Jakarta Persistence specification version 3.2:

A null comparison, with syntax given by null_comparison_expression is satisfied when:

An in expression, with syntax given by in_expression is satisfied when its leftmost operand evaluates to a non-null value, and:

All operands must have the same type.

A between expression, with syntax given by between_expression is satisfied when its operands all evaluate to non-null values, and, if the not keyword is missing, its left operand evaluates to a value which is:

Or, if the not keyword occurs, the left operand must evaluate to a value which is:

All three operands must have the same type.

A like expression is satisfied when its left operand evaluates to a non-null value and:

The left operand must have type java.lang.String.

Within the pattern, _ matches any single character, and % matches any sequence of characters.

The equality and inequality operators are =, <>, <, >, <=, >=.

The operands of an equality or inequality operator must have the same type.

Every basic type can, in principle, be equipped with a total order. An order for a type determines the result of inequality comparisons, and the effect of the Order clause.

For numeric types, and for date, time, and datetime types, the total order is unique and completely determined by the semantics of the type. JDQL implementations must sort these types according to their natural order, that is, the order in JDQL must agree with the order defined by Java.

Boolean values must be ordered so that false < true is satisfied.

For other types, there is at least some freedom in the choice of order. Usually, the order is determined by the native semantics of the database. Note that:

The logical operators are and, or, and not.

This specification leaves undefined the interpretation of the not operator when its operand is not satisfied.

Syntactically, logical operators are parsed with lower precedence than equality and inequality operators and other conditional expressions listed above. The not operator has higher precedence than and and or. The and operator has higher precedence than or.

The from clause, with syntax given by from_clause, specifies an entity name which identifies the queried entity. Path expressions occurring in later clauses are interpreted with respect to this entity. That is, the first element of each path expression in the query must be a persistent field of the entity named in the from clause. The entity name is a Java identifier, usually the unqualified name of the entity class, as specified in Entity Names.

The from clause is optional in select statements. When it is missing, the queried entity is determined by the return type of the repository method, or, if the return type is not an entity type, by the primary entity type of the repository.

For example, this repository method declaration:

is equivalent to:

The where clause, with syntax given by where_clause, specifies a conditional expression used to restrict the records returned, deleted, or updated by the query. Only records for which the conditional expression is satisfied are returned, deleted, or updated.

The where clause is always optional. When it is missing, there is no restriction, and all records of the queried entity type are returned, deleted, or updated.

The select clause, with syntax given by select_clause, specifies a path expression which determines the values returned by the query. The path expression is evaluated for each record which satisfies the restriction imposed by the where clause, as specified in Path expressions, and the value of the last element of the path expression is added to the query results.

Alternatively, the select clause may contain a single count(this) aggregate expression, which evaluates to the number of records which satisfy the restriction. A query beginning with select count(this) always returns a single result of type Long, no matter how many records satisfy the conditional expression in the where clause.

If the JDQL implementation does not support count(this), it must throw UnsupportedOperationException when this aggregate expression occurs in a query. Alternatively, the Jakarta Data provider is permitted to reject a repository method declaration at compilation time if its @Query annotation uses the unsupported aggregate expression.

The select clause is optional in select statements. When it is missing, the query returns the queried entity.

The set clause, with syntax given by set_clause, specifies a list of updates to fields of the queried entity. For each record which satisfies the restriction imposed by the where clause, and for each element of the list, the scalar expression is evaluated and assigned to the entity field identified by the path expression.

The order clause (or order by clause), with syntax given by orderby_clause, specifies a lexicographic order for the query results, that is, a list of entity fields used to sort the records which satisfy the restriction imposed by the where clause. The keywords asc and desc specify that a given field should be sorted in ascending or descending order respectively; when neither is specified, ascending order is the default.

Entity fields occurring earlier in the order by clause take precedence. That is, a field occurring later in the order by clause is only used to resolve "ties" between records which cannot be unambiguously ordered using only earlier fields.

This specification does not define how null values are ordered with respect to non-null values. The ordering of null values may vary between data stores and between Jakarta Data providers.

The order clause is always optional. When it is missing, and when no sort criteria are given as arguments to a parameter of the repository method, the order of the query results is undefined, and might not be deterministic.

If the Jakarta Data provider cannot satisfy a request for sorted query results, it must throw DataException.

A select statement, with syntax given by select_statement, returns data to the client. For each record which satisfies the restriction imposed by the where clause, a result is returned containing the value obtained by evaluating the path expression in the select clause. Alternatively, for the case of select count(this), the query returns the number of records which satisfied the restriction.

An update statement, with syntax given by update_statement, updates each record which satisfies the restriction imposed by the where clause, and returns the number of updated records to the client.

A delete statement, with syntax given by delete_statement, deletes each record which satisfies the restriction imposed by the where clause, and returns the number of deleted records to the client.

In environments where CDI Full or CDI Lite is available, Jakarta Data providers can make use of a CDI extension—​an implementation of jakarta.enterprise.inject.spi.Extension or jakarta.enterprise.inject.build.compatible.spi.BuildCompatibleExtension--to discover interfaces annotated with @Repository and make their implementations available for injection.

Key-value databases resemble dictionaries or Maps in Java, where data is primarily accessed using a key. In such databases, queries unrelated to keys are typically limited. To ensure a minimum level of support, Jakarta Data mandates the implementation of BasicRepository built-in methods that require an identifier or a key. However, the deleteAll and count methods are not required. Methods relying on complex queries, which are defined as queries that do not use the Key or identifier, raise java.lang.UnsupportedOperationException due to the fundamental nature of key-value databases.

Wide-column databases offer more query flexibility, even allowing the use of secondary indexes, albeit potentially impacting performance. When interacting with wide-column databases, Jakarta Data requires the implementation of the BasicRepository along with all of its methods. However, developers should be mindful that certain query keywords, such as "And" or "Or," may not be universally supported in these databases. The full set of required keywords is documented in the section of the Jakarta Data module Javadoc that is titled "Reserved Keywords for Query by Method Name".

Document databases provide query flexibility akin to relational databases, offering robust query capabilities. They encourage denormalization for performance optimization. When interfacing with document databases, Jakarta Data goes a step further by supporting both built-in repositories: BasicRepository and CrudRepository. Additionally, Query by Method Name is available, though developers should be aware that some keywords may not be universally supported. The full set of required keywords is documented in the section of the Jakarta Data module Javadoc that is titled "Reserved Keywords for Query by Method Name".

These portability considerations reflect Jakarta Data’s commitment to providing a consistent data access experience across diverse NoSQL database types. While specific capabilities and query support may vary, Jakarta Data aims to simplify data access, promoting flexibility and compatibility in NoSQL database interactions.

A Graph database, a specialized NoSQL variant, excels in managing intricate data relationships, rivaling traditional relational databases. Its unique strength lies in its ability to handle both directed and undirected edges (or relationships) between vertices (or nodes) and store properties on both vertices and edges.

Graph databases excel at answering queries that return rows containing flat objects, collections, or a combination of flat objects and connections. However, portability is only guaranteed when mapping rows to classes, and when queries specified via annotations or other supported means are used. It should be noted that queries derived from keywords and combinations of mapped classes/properties will be translated into vendor-specific queries.

It is important to note that in Jakarta Data the Graph database supports the built-in repositories: BasicRepository and DataRepository. Additionally, Query by Method Name is available, though developers should be aware that some keywords may not be universally supported. The full set of required keywords is documented in the section of the Jakarta Data module Javadoc that is titled "Reserved Keywords for Query by Method Name".