Jakarta Data Specification

Jakarta Data is a specification that provides a high-level, persistence-agnostic API to simplify data access in Java applications. It allows developers to focus on the domain model rather than the complexities of specific database implementations.

Key features include:

• Pre-built interfaces for common data access patterns.
• Pagination strategies including both offset-based and cursor-based approaches.
• Custom query composition where the framework implements methods based on developer definitions.
• Domain-centric approach: Aligning data access strategies with core business rules and domain concepts.

Jakarta Data is designed to complement, not replace, existing specifications like Jakarta Persistence or Jakarta NoSQL.

The Jakarta Data TCK (Technology Compatibility Kit) distribution bundle contains the following components for testing Jakarta Data implementations:

• artifacts/*: Contains the TCK tests JAR and a sample script used to install the TCK into a local Maven repository.
• docs/*: Includes the TCK user guide available in both HTML and PDF formats.
• starter/*: A TCK starter project containing sample code derived from the user guide to help get started with implementation testing.
• LICENSE: The EFTL license terms governing the use of this distribution.

Jakarta Common Query Language (JCQL) is a dialect of SQL used within the @Query annotation to define the semantics of query methods in Jakarta Data repositories. It is a subset of Jakarta Persistence Query Language (JPQL).

Key Characteristics:

• Single Entity Constraint: The from clause in a JCQL query may contain only a single entity.
• Portability: It is designed to be lightweight enough to be implemented across various data storage technologies, including non-relational (NoSQL) datastores.
• Compatibility: JCQL is the successor to Jakarta Data Query Language (JDQL) and is fully backward compatible.
• Provider Extensions: While JCQL is a limited subset, providers backed by relational databases may choose to support a larger subset of JPQL via the @Query annotation, though this is not required by the specification.

Query by Method Name is a feature in Jakarta Data 1.0 that allows you to express database queries using Java method names. The syntax is limited to legal Java identifier characters, meaning no whitespace, punctuation, or numeric/comparison operators are allowed in the name itself.

Note on Usage: This functionality is considered deprecated. For new code, it is strongly preferred to use parameter-based automatic query methods (@Find, @Delete) or annotated query methods (@Query with Jakarta Persistence Query Language).

@Repository
public interface ProductRepository extends BasicRepository<Product, Long> {

List<Product> findByName(String name);

@OrderBy("price")
List<Product> findByNameLike(String namePattern);

List<Product> findByNameLikeAndPriceLessThanOrderByPriceDesc(String namePattern, float priceBelow);

}

A repository can be either stateful or stateless. Stateful repositories manage entities according to a persistence context and use specific lifecycle annotations to control state transitions.

Note: Lifecycle annotations for stateful operations must not be intermixed with lifecycle annotations for stateless operations.

Wide-column databases offer more flexibility than key-value stores, including secondary indexes.

Requirements:

• Must implement BasicRepository and all of its methods.

Caveats:

• Certain query keywords (such as And or Or) may not be universally supported. Developers should consult the "Reserved Keywords for Query by Method Name" section in the Jakarta Data module Javadoc for the full set of required keywords.

Jakarta Data supports two pagination strategies:

• Offset Pagination: Computes pages relative to a positional offset from the start of the dataset using a page number and page size. Returns a Page<T>.
• Cursor-based Pagination: Uses a cursor (a pointer to a specific position in the dataset) to navigate, reducing missed or duplicate results. This is typically used with @Find and @OrderBy annotations. Returns a CursoredPage<T>.

Both methods utilize PageRequest to define the pagination parameters.

@Repository
public interface CarRepository extends BasicRepository<Car, Long> {

    Page<Car> findByTypeOrderByName(CarType type, PageRequest pageRequest);

    @Find
    @OrderBy(_Car.NAME)
    @OrderBy(_Car.VIN)
    CursoredPage<Car> type(CarType type, PageRequest pageRequest);
}

In the Jakarta Data specification, the terms entity attribute and persistent attribute are used to refer to a field or property of an Entity that is persisted to a data store.

This terminology is consistent with the Jakarta Persistence specification (which also uses persistent fields and properties). Attributes may be referred to by their specific name (e.g., the price attribute of a Product entity) or by their functional role (e.g., an Id attribute or a Version attribute).

Graph databases manage complex relationships using vertices (nodes) and edges (relationships).

Requirements:

• Must support built-in repositories: BasicRepository and DataRepository.
• Query by Method Name: Supported, though keyword support may vary.

Caveats:

• Portability Guarantee: Portability is only guaranteed when mapping rows to classes and using queries specified via annotations or other supported means.
• Keyword Translation: Queries derived from keywords and combinations of mapped classes/attributes will be translated into vendor-specific queries.
• Consult the "Reserved Keywords for Query by Method Name" section in the Jakarta Data module Javadoc for keyword details.

A Jakarta Data provider backed by a relational database must support the following core features:

• Lifecycle Annotations: @Insert, @Update, and @Delete.
• Built-in Repository Types: BasicRepository and CrudRepository.
• Query Capabilities: Full support for Jakarta Data query methods, including pagination, ordering, and limiting.
• JDBC Integration: If the provider is backed by JDBC, it should support java.sql.Connection resource accessor methods.

Note on Limitations: A provider is not required to implement repository methods that map to operations not supported by the underlying SQL dialect or database engine. Implementation is subject to the limits of the database itself.

Once extracted, the TCK directory contains the following components:

• artifacts: Contains test artifacts, including:
  • TCK test classes and source.
  • The TCKTestPlatform configuration file.
  • A copy of the SignatureTest file for reference.
  • A script to copy the TCK into your local Maven repository.
• docs: Contains the TCK documentation and reference guides.
• starter: A basic Maven starter project designed to help you begin testing your implementation.