DOCSEARCHbyAlgolia
Submit Docs

Jakarta Persistence

repository·main·Indexed 43 days ago

https://github.com/jakartaee/persistence

The standard Java API for object/relational mapping (ORM), allowing developers to manage relational data using Java objects. It supports standalone Java applications and the Jakarta EE platform, with common implementations including Hibernate ORM 7 and EclipseLink 5. Current stable version is 3.2, with version 4.0 introducing enhancements for query management and new @Index annotation attributes.

Tokens
60.8K
Snippets
122
Records
262
Agent score
52%

What's inside Jakarta Persistence

  1. Overview of the Jakarta Persistence TCK

    main

    The Jakarta Persistence Technology Compatibility Kit (TCK) is a portable, configurable, and automated test suite designed to verify that a vendor's implementation of the Jakarta Persistence specification conforms to the official requirements.

    Key aspects of the TCK include:

    • Purpose: Ensures correctness, completeness, and consistency across different implementations, preventing platform fragmentation.
    • Test Suite: A collection of precompiled and indexed JUnit tests that correspond to assertions in the specification. Most tests are self-checking and return a Pass or Fail status.
    • Certification: For a platform to be certified, all required tests must pass. The definition of required tests may change between versions.
    • JESP Deliverables: Under the Jakarta EE Specification Process (JESP), a complete release must include the Technology Specification, a Compatible Implementation (CI), and the TCK.

  2. Overview of Jakarta Persistence

    main

    Jakarta Persistence is the industry standard for object/relational mapping (ORM) and persistence management in Java environments. It provides a standardized API for managing data between Java objects and relational databases.

    Key details for developers:

    • Current Stable Version: Jakarta Persistence 3.2.
    • Major Revision: Jakarta Persistence 4.0 (targeted for late 2026).
    • Implementations: Common open-source implementations include EclipseLink 5 and Hibernate ORM 7.
    • Environment: While designed to integrate with the Jakarta EE platform, implementations can operate both inside and outside of a container environment (e.g., standalone Java SE applications).

  3. Use the Static Query API in jakarta.persistence.query

    main

    The Static Query API is located in the jakarta.persistence.query package. It provides interfaces for managing and referencing queries that are defined statically, allowing for more structured access to query execution and configuration. The core components include:

    • JakartaQuery: The base interface for queries within the Jakarta Persistence ecosystem.
    • NativeQuery: An interface for executing queries written in the native language of the underlying database.
    • QueryOptions: An interface used to configure specific behaviors or parameters for a query.
    • StaticStatementReference: A reference to a statically defined statement.
    • StaticTypedQueryReference: A reference to a statically defined typed query.

  4. Use the Jakarta Persistence Criteria API

    main

    The Criteria API is located in the jakarta.persistence.criteria package. It provides a type-safe way to construct queries for various operations including selection, updates, and deletions.

    Core components include:

    • CriteriaBuilder: The primary entry point used to create query components like predicates, expressions, and the queries themselves.
    • CriteriaQuery: Used to define the structure of a selection query.
    • CriteriaUpdate and CriteriaDelete: Used for bulk update and delete operations.
    • Root: Represents the entity being queried.
    • Join and Fetch: Used to navigate associations between entities.

  6. Explore the Jakarta Persistence Metamodel API

    main
    The jakarta.persistence.metamodel package provides a set of interfaces used to navigate the persistence unit's metamodel. This allows developers to interact with the structure of the managed entities (types, attributes, and their relationships) programmatically at runtime, which is essential for building type-safe criteria queries and dynamic data processing tools.

  8. Use the Result Set Mapping API in jakarta.persistence.sql

    main

    The jakarta.persistence.sql package provides a set of APIs for defining how database result sets are mapped to Java objects. This API allows for complex mappings including entities, embedded objects, and constructor-based projections.

    Core components include:

    • ResultSetMapping: The top-level container for mapping definitions.
    • MappingElement: A base abstraction for all mapping components.
    • MemberMapping: Defines mappings for individual members (fields, properties, or constructors).
    • ColumnMapping: Maps specific database columns to Java elements.
    • FieldMapping: Maps database results directly to class fields.
    • EntityMapping: Maps result sets to managed entities.
    • EmbeddedMapping: Maps result sets to @Embeddable objects.
    • CompoundMapping: Represents a collection of mappings that form a single logical unit.
    • ConstructorMapping: Maps result set columns to a specific class constructor.
    • TupleMapping: Maps result sets to a collection of values (tuples).

  9. Overview of the Jakarta Persistence Criteria API

    main

    The Jakarta Persistence Criteria API allows you to define queries by constructing object-based query definition objects. This is an alternative to the string-based Jakarta Persistence Query Language (JPQL).

    Key characteristics:

    • Data Model: Based on the abstract persistence schema of entities, embedded objects, and relationships.
    • Metamodel: Uses metamodel objects to provide type safety and define navigation through joins and paths.
    • Flexibility: Supports both strongly-typed construction (using static metamodel classes) and string-based navigation (using attribute names). Both approaches are equivalent in range and semantics.

  10. Use the # syntax for relative persistence unit paths

    main

    When defining persistence unit locations, you can use the # syntax to specify a persistence unit within a specific JAR file. The path name is interpreted relative to the referencing application component JAR file.

    For example, the syntax ../lib/persistenceUnitRoot.jar#myPersistenceUnit resolves to a persistence unit where:

    • The name is myPersistenceUnit (as defined in the name element of the persistence.xml inside that JAR).
    • The root is the relative path ../lib/persistenceUnitRoot.jar.
    ../lib/persistenceUnitRoot.jar#myPersistenceUnit

  11. Commercial Distribution Responsibilities

    main

    Commercial distributors (referred to as "Commercial Contributors") who include the Program in a commercial product offering may accept additional responsibilities to facilitate commercial use.

    To avoid creating potential liability for other Contributors, a Commercial Contributor agrees to defend and indemnify every other Contributor against losses, damages, and costs arising from third-party claims or lawsuits related to the distribution of the Program in a commercial product, provided the claim is caused by the acts or omissions of the Commercial Contributor.

    Note: This obligation does not apply to claims relating to actual or alleged intellectual property infringement. To qualify for indemnification, the Indemnified Contributor must promptly notify the Commercial Contributor in writing and allow them to control the defense.

  12. Configure Query Flush Modes

    main

    Flush modes control when changes in the persistence context are synchronized with the database before a query executes. You can set the flush mode at the EntityManager level or override it for a specific query.

    EntityManager Flush Mode (FlushModeType)

    Controls the behavior for the entire persistence context.

    Query Flush Mode (QueryFlushMode)

    Overrides the EntityManager setting for a specific execution via setQueryFlushMode().

    Effective Flush Behavior

    When executing a query within a transaction:

    1. QueryFlushMode.FLUSH: The provider must flush modifications before the query.
    2. QueryFlushMode.NO_FLUSH: The provider is not required to flush. If the EntityManager is set to FlushModeType.EXPLICIT, the provider is forbidden from flushing.
    3. QueryFlushMode.DEFAULT:
      • If FlushModeType.AUTO: The provider must ensure all modifications that could affect the query result are visible (usually by flushing).
      • If FlushModeType.EXPLICIT: The provider is not permitted to flush before the query.
      • If FlushModeType.COMMIT: The effect on query results is unspecified.

    Note: If no transaction is active or the context is not joined to the transaction, the provider must not flush, regardless of the mode.