From 2ed66838756593c2631d1cfb6039c20be4194ceb Mon Sep 17 00:00:00 2001 From: Gavin King Date: Fri, 22 Mar 2024 23:01:05 +0100 Subject: [PATCH 1/4] move API definitions to appendices --- ...ndixes.adoc => appA-revision-history.adoc} | 0 spec/src/main/asciidoc/appB-persistence.adoc | 122 + spec/src/main/asciidoc/appC-criteria.adoc | 188 + spec/src/main/asciidoc/appD-metamodel.adoc | 88 + spec/src/main/asciidoc/appE-spi.adoc | 44 + .../main/asciidoc/ch03-entity-operations.adoc | 3487 +-------------- .../src/main/asciidoc/ch05-metamodel-api.adoc | 1015 +---- spec/src/main/asciidoc/ch06-criteria-api.adoc | 3769 +---------------- ...titymanagers-and-persistence-contexts.adoc | 599 +-- .../ch09-container-provider-contracts.adoc | 884 +--- .../asciidoc/jakarta.persistence-spec.adoc | 6 +- 11 files changed, 513 insertions(+), 9689 deletions(-) rename spec/src/main/asciidoc/{appendixes.adoc => appA-revision-history.adoc} (100%) create mode 100644 spec/src/main/asciidoc/appB-persistence.adoc create mode 100644 spec/src/main/asciidoc/appC-criteria.adoc create mode 100644 spec/src/main/asciidoc/appD-metamodel.adoc create mode 100644 spec/src/main/asciidoc/appE-spi.adoc diff --git a/spec/src/main/asciidoc/appendixes.adoc b/spec/src/main/asciidoc/appA-revision-history.adoc similarity index 100% rename from spec/src/main/asciidoc/appendixes.adoc rename to spec/src/main/asciidoc/appA-revision-history.adoc diff --git a/spec/src/main/asciidoc/appB-persistence.adoc b/spec/src/main/asciidoc/appB-persistence.adoc new file mode 100644 index 00000000..78730421 --- /dev/null +++ b/spec/src/main/asciidoc/appB-persistence.adoc @@ -0,0 +1,122 @@ +[appendix] +== Persistence API Interfaces + +=== `EntityManager` [[_entitymanager_]] +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/EntityManager.java[lines=18..-1] +---- + +=== `EntityTransaction` [[_entitytransaction_]] +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/EntityTransaction.java[lines=18..-1] +---- + +=== `EntityManagerFactory` [[_entitymanagerfactory_]] +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/EntityManagerFactory.java[lines=18..-1] +---- + +=== `LockModeType` [[_lockmodetype_]] +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/LockModeType.java[lines=18..-1] +---- + +=== `Cache` [[_cache_]] +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/Cache.java[lines=18..-1] +---- + +=== `Query` [[a3127]] +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/Query.java[lines=18..-1] +---- + +=== `TypedQuery` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/TypedQuery.java[lines=18..-1] +---- + +=== `StoredProcedureQuery` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/StoredProcedureQuery.java[lines=18..-1] +---- + +=== `Tuple` [[a3868]] +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/Tuple.java[lines=18..-1] +---- + +=== `TupleElement` [[a3949]] +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/TupleElement.java[lines=18..-1] +---- + +=== `Parameter` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/Parameter.java[lines=18..-1] +---- + +=== `Graph` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/Graph.java[lines=18..-1] +---- + +=== `EntityGraph` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/EntityGraph.java[lines=18..-1] +---- + +=== `Subgraph` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/Subgraph.java[lines=18..-1] +---- + +=== `AttributeNode` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/AttributeNode.java[lines=18..-1] +---- + +=== `SchemaManager` [[_schemamanager_]] +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/SchemaManager.java[lines=18..-1] +---- + +=== `Persistence` [[_persistence_]] +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/Persistence.java[lines=18..-1] +---- + +=== `PersistenceConfiguration` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/PersistenceConfiguration.java[lines=18..-1] +---- + +=== `PersistenceUtil` [[_persistenceutil_]] +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/PersistenceUtil.java[lines=18..-1] +---- + +=== `PersistenceUnitUtil` [[_persistenceunitutil_]] +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/PersistenceUnitUtil.java[lines=18..-1] +---- \ No newline at end of file diff --git a/spec/src/main/asciidoc/appC-criteria.adoc b/spec/src/main/asciidoc/appC-criteria.adoc new file mode 100644 index 00000000..8631ca8c --- /dev/null +++ b/spec/src/main/asciidoc/appC-criteria.adoc @@ -0,0 +1,188 @@ +[appendix] +== Criteria API Interfaces [[a6997]] + +=== `CriteriaBuilder` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/CriteriaBuilder.java[lines=18..-1] +---- + +=== `CriteriaDelete` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/CriteriaDelete.java[lines=18..-1] +---- + +=== `CriteriaQuery` [[a8857]] +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/CriteriaQuery.java[lines=18..-1] +---- + +=== `CriteriaSelect` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/CriteriaSelect.java[lines=18..-1] +---- + +=== `CriteriaUpdate` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/CriteriaUpdate.java[lines=18..-1] +---- + +=== `AbstractQuery` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/AbstractQuery.java[lines=18..-1] +---- + +=== `CollectionJoin` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/CollectionJoin.java[lines=18..-1] +---- + +=== `CommonAbstractCriteria` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/CommonAbstractCriteria.java[lines=18..-1] +---- + +=== `CompoundSelection` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/CompoundSelection.java[lines=18..-1] +---- + +=== `Expression` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/Expression.java[lines=18..-1] +---- + +=== `Fetch` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/Fetch.java[lines=18..-1] +---- + +=== `FetchParent` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/FetchParent.java[lines=18..-1] +---- + +=== `AbstractQuery` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/From.java[lines=18..-1] +---- + +=== `Join` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/Join.java[lines=18..-1] +---- + +=== `JoinType` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/JoinType.java[lines=18..-1] +---- + +=== `ListJoin` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/ListJoin.java[lines=18..-1] +---- + +=== `LocalDateField` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/LocalDateField.java[lines=18..-1] +---- + +=== `LocalDateTimeField` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/LocalDateTimeField.java[lines=18..-1] +---- + +=== `LocalTimeField` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/LocalTimeField.java[lines=18..-1] +---- + +=== `MapJoin` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/MapJoin.java[lines=18..-1] +---- + +=== `Nulls` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/Nulls.java[lines=18..-1] +---- + +=== `Order` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/Order.java[lines=18..-1] +---- + +=== `ParameterExpression` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/ParameterExpression.java[lines=18..-1] +---- + +=== `Path` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/Path.java[lines=18..-1] +---- + +=== `PluralJoin` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/PluralJoin.java[lines=18..-1] +---- + +=== `Predicate` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/Predicate.java[lines=18..-1] +---- + +=== `Root` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/Root.java[lines=18..-1] +---- + +=== `Selection` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/Selection.java[lines=18..-1] +---- + +=== `SetJoin` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/SetJoin.java[lines=18..-1] +---- + +=== `Subquery` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/Subquery.java[lines=18..-1] +---- + +=== `TemporalField` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/criteria/TemporalField.java[lines=18..-1] +---- \ No newline at end of file diff --git a/spec/src/main/asciidoc/appD-metamodel.adoc b/spec/src/main/asciidoc/appD-metamodel.adoc new file mode 100644 index 00000000..55c7b65a --- /dev/null +++ b/spec/src/main/asciidoc/appD-metamodel.adoc @@ -0,0 +1,88 @@ +[appendix] +== Metamodel API Interfaces + +=== `Metamodel` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/metamodel/Metamodel.java[lines=18..-1] +---- +=== `StaticMetamodel` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/metamodel/StaticMetamodel.java[lines=18..-1] +---- +=== `Attribute` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/metamodel/Attribute.java[lines=18..-1] +---- +=== `BasicType` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/metamodel/BasicType.java[lines=18..-1] +---- +=== `Bindable` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/metamodel/Bindable.java[lines=18..-1] +---- +=== `CollectionAttribute` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/metamodel/CollectionAttribute.java[lines=18..-1] +---- +=== `EmbeddableType` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/metamodel/EmbeddableType.java[lines=18..-1] +---- +=== `EntityType` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/metamodel/EntityType.java[lines=18..-1] +---- +=== `IdentifiableType` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/metamodel/IdentifiableType.java[lines=18..-1] +---- +=== `ListAttribute` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/metamodel/ListAttribute.java[lines=18..-1] +---- +=== `ManagedType` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/metamodel/ManagedType.java[lines=18..-1] +---- +=== `MapAttribute` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/metamodel/MapAttribute.java[lines=18..-1] +---- +=== `MappedSuperclassType` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/metamodel/MappedSuperclassType.java[lines=18..-1] +---- +=== `PluralAttribute` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/metamodel/PluralAttribute.java[lines=18..-1] +---- +=== `SetAttribute` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/metamodel/SetAttribute.java[lines=18..-1] +---- +=== `SingularAttribute` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/metamodel/SingularAttribute.java[lines=18..-1] +---- +=== `Type` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/metamodel/Type.java[lines=18..-1] +---- diff --git a/spec/src/main/asciidoc/appE-spi.adoc b/spec/src/main/asciidoc/appE-spi.adoc new file mode 100644 index 00000000..ce26f398 --- /dev/null +++ b/spec/src/main/asciidoc/appE-spi.adoc @@ -0,0 +1,44 @@ +[appendix] +== Persistence SPI Interfaces + +=== `ClassTransformer` [[_classtransformer_]] +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/spi/ClassTransformer.java[lines=18..-1] +---- + +=== `LoadState` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/spi/LoadState.java[lines=18..-1] +---- + +=== `PersistenceProvider` [[_persistenceprovider_]] +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/spi/PersistenceProvider.java[lines=18..-1] +---- + +=== `PersistenceProviderResolver` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/spi/PersistenceProviderResolver.java[lines=18..-1] +---- + +=== `PersistenceProviderResolverHolder` +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/spi/PersistenceProviderResolverHolder.java[lines=18..-1] +---- + +=== `PersistenceUnitInfo` [[_persistenceunitinfo_]] +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/spi/PersistenceUnitInfo.java[lines=18..-1] +---- + +=== `ProviderUtil` [[_providerutil_]] +[source,java] +---- +include::../../../../api/src/main/java/jakarta/persistence/spi/ProviderUtil.java[lines=18..-1] +---- diff --git a/spec/src/main/asciidoc/ch03-entity-operations.adoc b/spec/src/main/asciidoc/ch03-entity-operations.adoc index 4aa1d389..bfb74d41 100644 --- a/spec/src/main/asciidoc/ch03-entity-operations.adoc +++ b/spec/src/main/asciidoc/ch03-entity-operations.adoc @@ -60,1219 +60,7 @@ representations for attributes of basic types. === EntityManager Interface [[a1066]] -[source,java] ----- -package jakarta.persistence; - -import java.util.Map; -import java.util.List; -import jakarta.persistence.metamodel.Metamodel; -import jakarta.persistence.criteria.CriteriaBuilder; -import jakarta.persistence.criteria.CriteriaQuery; -import jakarta.persistence.criteria.CriteriaUpdate; -import jakarta.persistence.criteria.CriteriaDelete; - -/** - * Interface used to interact with the persistence context. - * - *

An EntityManager instance is associated with - * a persistence context. A persistence context is a set of entity - * instances in which for any persistent entity identity there is - * a unique entity instance. Within the persistence context, the - * entity instances and their lifecycle are managed. - * The EntityManager API is used - * to create and remove persistent entity instances, to find entities - * by their primary key, and to query over entities. - * - *

The set of entities that can be managed by a given - * EntityManager instance is defined by a persistence - * unit. A persistence unit defines the set of all classes that are - * related or grouped by the application, and which must be - * colocated in their mapping to a single database. - * - * @see Query - * @see TypedQuery - * @see CriteriaQuery - * @see PersistenceContext - * @see StoredProcedureQuery - * - * @since 1.0 - */ -public interface EntityManager extends AutoCloseable { - - /** - * Make an instance managed and persistent. - * @param entity entity instance - * @throws EntityExistsException if the entity already exists. - * (If the entity already exists, the EntityExistsException may - * be thrown when the persist operation is invoked, or the - * EntityExistsException or another PersistenceException may be - * thrown at flush or commit time.) - * @throws IllegalArgumentException if the instance is not an - * entity - * @throws TransactionRequiredException if there is no transaction when - * invoked on a container-managed entity manager of that is of type - * PersistenceContextType.TRANSACTION - */ - public void persist(Object entity); - - /** - * Merge the state of the given entity into the - * current persistence context. - * @param entity entity instance - * @return the managed instance that the state was merged to - * @throws IllegalArgumentException if instance is not an - * entity or is a removed entity - * @throws TransactionRequiredException if there is no transaction when - * invoked on a container-managed entity manager of that is of type - * PersistenceContextType.TRANSACTION - */ - public T merge(T entity); - - /** - * Remove the entity instance. - * @param entity entity instance - * @throws IllegalArgumentException if the instance is not an - * entity or is a detached entity - * @throws TransactionRequiredException if invoked on a - * container-managed entity manager of type - * PersistenceContextType.TRANSACTION and there is - * no transaction - */ - public void remove(Object entity); - - /** - * Find by primary key. - * Search for an entity of the specified class and primary key. - * If the entity instance is contained in the persistence context, - * it is returned from there. - * @param entityClass entity class - * @param primaryKey primary key - * @return the found entity instance or null if the entity does - * not exist - * @throws IllegalArgumentException if the first argument does - * not denote an entity type or the second argument is - * is not a valid type for that entity's primary key or - * is null - */ - public T find(Class entityClass, Object primaryKey); - - /** - * Find by primary key, using the specified properties. - * Search for an entity of the specified class and primary key. - * If the entity instance is contained in the persistence - * context, it is returned from there. - * If a vendor-specific property or hint is not recognized, - * it is silently ignored. - * @param entityClass entity class - * @param primaryKey primary key - * @param properties standard and vendor-specific properties - * and hints - * @return the found entity instance or null if the entity does - * not exist - * @throws IllegalArgumentException if the first argument does - * not denote an entity type or the second argument is - * is not a valid type for that entity's primary key or - * is null - * @since 2.0 - */ - public T find(Class entityClass, Object primaryKey, - Map properties); - - /** - * Find by primary key and lock. - * Search for an entity of the specified class and primary key - * and lock it with respect to the specified lock type. - * If the entity instance is contained in the persistence context, - * it is returned from there, and the effect of this method is - * the same as if the lock method had been called on the entity. - *

If the entity is found within the persistence context and the - * lock mode type is pessimistic and the entity has a version - * attribute, the persistence provider must perform optimistic - * version checks when obtaining the database lock. If these - * checks fail, the OptimisticLockException will be thrown. - *

If the lock mode type is pessimistic and the entity instance - * is found but cannot be locked: - *

- * @param entityClass entity class - * @param primaryKey primary key - * @param lockMode lock mode - * @return the found entity instance or null if the entity does - * not exist - * @throws IllegalArgumentException if the first argument does - * not denote an entity type or the second argument is - * not a valid type for that entity's primary key or - * is null - * @throws TransactionRequiredException if there is no - * transaction and a lock mode other than NONE is - * specified or if invoked on an entity manager which has - * not been joined to the current transaction and a lock - * mode other than NONE is specified - * @throws OptimisticLockException if the optimistic version - * check fails - * @throws PessimisticLockException if pessimistic locking - * fails and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - * @since 2.0 - */ - public T find(Class entityClass, Object primaryKey, - LockModeType lockMode); - - /** - * Find by primary key and lock, using the specified properties. - * Search for an entity of the specified class and primary key - * and lock it with respect to the specified lock type. - * If the entity instance is contained in the persistence context, - * it is returned from there. - *

If the entity is found - * within the persistence context and the lock mode type - * is pessimistic and the entity has a version attribute, the - * persistence provider must perform optimistic version checks - * when obtaining the database lock. If these checks fail, - * the OptimisticLockException will be thrown. - *

If the lock mode type is pessimistic and the entity instance - * is found but cannot be locked: - *

    - *
  • the PessimisticLockException will be thrown if the database - * locking failure causes transaction-level rollback - *
  • the LockTimeoutException will be thrown if the database - * locking failure causes only statement-level rollback - *
- *

If a vendor-specific property or hint is not recognized, - * it is silently ignored. - *

Portable applications should not rely on the standard timeout - * hint. Depending on the database in use and the locking - * mechanisms used by the provider, the hint may or may not - * be observed. - * @param entityClass entity class - * @param primaryKey primary key - * @param lockMode lock mode - * @param properties standard and vendor-specific properties - * and hints - * @return the found entity instance or null if the entity does - * not exist - * @throws IllegalArgumentException if the first argument does - * not denote an entity type or the second argument is - * not a valid type for that entity's primary key or - * is null - * @throws TransactionRequiredException if there is no - * transaction and a lock mode other than NONE is - * specified or if invoked on an entity manager which has - * not been joined to the current transaction and a lock - * mode other than NONE is specified - * @throws OptimisticLockException if the optimistic version - * check fails - * @throws PessimisticLockException if pessimistic locking - * fails and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - * @since 2.0 - */ - public T find(Class entityClass, Object primaryKey, - LockModeType lockMode, - Map properties); - - /** - * Find an instance of the given entity class by primary key, - * using the specified {@linkplain FindOption options}. - * Search for an entity with the specified class and primary key. - * If the given options include a {@link LockModeType}, lock it - * with respect to the specified lock type. - * If the entity instance is contained in the persistence context, - * it is returned from there. - *

If the entity is found within the persistence context and - * the lock mode type is pessimistic and the entity has a version - * attribute, the persistence provider must perform optimistic - * version checks when obtaining the database lock. If these checks - * fail, the OptimisticLockException will be thrown. - *

If the lock mode type is pessimistic and the entity instance - * is found but cannot be locked: - *

    - *
  • the PessimisticLockException will be thrown - * if the database locking failure causes transaction-level - * rollback - *
  • the LockTimeoutException will be thrown if - * the database locking failure causes only statement-level - * rollback - *
- *

If a vendor-specific {@linkplain FindOption option} is not - * recognized, it is silently ignored. - *

Portable applications should not rely on the standard - * {@linkplain Timeout timeout option}. Depending on the database - * in use and the locking mechanisms used by the provider, this - * option may or may not be observed. - * @param entityClass entity class - * @param primaryKey primary key - * @param options standard and vendor-specific options - * @return the found entity instance or null if the entity does - * not exist - * @throws IllegalArgumentException if there are contradictory - * options, if the first argument does not denote an entity - * type belonging to the persistence unit, or if the second - * argument is not a valid non-null instance of the entity - * primary key type - * @throws TransactionRequiredException if there is no transaction - * and a lock mode other than NONE is - * specified or if invoked on an entity manager which has - * not been joined to the current transaction and a lock - * mode other than NONE is specified - * @throws OptimisticLockException if the optimistic version check - * fails - * @throws PessimisticLockException if pessimistic locking fails - * and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call is made - * @since 3.2 - */ - public T find(Class entityClass, Object primaryKey, - FindOption... options); - - /** - * Find an instance of the root entity of the given {@link EntityGraph} - * by primary key, using the specified {@linkplain FindOption options}, - * and interpreting the {@code EntityGraph} as a load graph. - * Search for an entity with the specified type and primary key. - * If the given options include a {@link LockModeType}, lock it - * with respect to the specified lock type. - * If the entity instance is contained in the persistence context, - * it is returned from there. - *

If the entity is found within the persistence context and - * the lock mode type is pessimistic and the entity has a version - * attribute, the persistence provider must perform optimistic - * version checks when obtaining the database lock. If these checks - * fail, the OptimisticLockException will be thrown. - *

If the lock mode type is pessimistic and the entity instance - * is found but cannot be locked: - *

    - *
  • the PessimisticLockException will be thrown - * if the database locking failure causes transaction-level - * rollback - *
  • the LockTimeoutException will be thrown if - * the database locking failure causes only statement-level - * rollback - *
- *

If a vendor-specific {@linkplain FindOption option} is not - * recognized, it is silently ignored. - *

Portable applications should not rely on the standard - * {@linkplain Timeout timeout option}. Depending on the database - * in use and the locking mechanisms used by the provider, this - * option may or may not be observed. - * @param entityGraph entity graph interpreted as a load graph - * @param primaryKey primary key - * @param options standard and vendor-specific options - * @return the found entity instance or null if the entity does - * not exist - * @throws IllegalArgumentException if there are contradictory - * options, if the first argument does not denote an entity - * type belonging to the persistence unit, or if the second - * argument is not a valid non-null instance of the entity - * primary key type - * @throws TransactionRequiredException if there is no transaction - * and a lock mode other than NONE is - * specified or if invoked on an entity manager which has - * not been joined to the current transaction and a lock - * mode other than NONE is specified - * @throws OptimisticLockException if the optimistic version check - * fails - * @throws PessimisticLockException if pessimistic locking fails - * and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call is made - * @since 3.2 - */ - public T find(EntityGraph entityGraph, Object primaryKey, - FindOption... options); - - /** - * Obtain a reference to an instance of the given entity class - * with the given primary key, whose state may be lazily fetched. - *

If the requested instance does not exist in the database, - * the EntityNotFoundException is thrown when the - * instance state is first accessed. - * (The persistence provider runtime is permitted but not - * required to throw the EntityNotFoundException - * when getReference is called.) - *

The application should not expect the instance state to - * be available upon detachment, unless it was accessed by the - * application while the entity manager was open. - * @param entityClass entity class - * @param primaryKey primary key - * @return a reference to the entity instance - * @throws IllegalArgumentException if the first argument does - * not denote an entity type or the second argument is - * not a valid type for that entity's primary key or - * is null - * @throws EntityNotFoundException if the entity state cannot - * be accessed - */ - public T getReference(Class entityClass, Object primaryKey); - - /** - * Obtain a reference to an instance of the entity class of the - * given object, with the same primary key as the given object, - * whose state may be lazily fetched. The given object may be - * persistent or detached, but may be neither new nor removed. - *

If the requested instance does not exist in the database, - * the EntityNotFoundException is thrown when the - * instance state is first accessed. - * (The persistence provider runtime is permitted but not - * required to throw the EntityNotFoundException - * when getReference is called.) - *

The application should not expect the instance state to - * be available upon detachment, unless it was accessed by the - * application while the entity manager was open. - * @param entity a persistent or detached entity instance - * @return a reference to the entity instance - * @throws IllegalArgumentException if the given object is not - * an entity, or if it is neither persistent nor detached - * @throws EntityNotFoundException if the entity state cannot be - * accessed - */ - public T getReference(T entity); - - /** - * Synchronize the persistence context to the - * underlying database. - * @throws TransactionRequiredException if there is - * no transaction or if the entity manager has not been - * joined to the current transaction - * @throws PersistenceException if the flush fails - */ - public void flush(); - - /** - * Set the flush mode that applies to all objects contained - * in the persistence context. - * @param flushMode flush mode - */ - public void setFlushMode(FlushModeType flushMode); - - /** - * Get the flush mode that applies to all objects contained - * in the persistence context. - * @return flushMode - */ - public FlushModeType getFlushMode(); - - /** - * Lock an entity instance that is contained in the persistence - * context with the specified lock mode type. - *

If a pessimistic lock mode type is specified and the entity - * contains a version attribute, the persistence provider must - * also perform optimistic version checks when obtaining the - * database lock. If these checks fail, the - * OptimisticLockException will be thrown. - *

If the lock mode type is pessimistic and the entity instance - * is found but cannot be locked: - *

    - *
  • the PessimisticLockException will be thrown if the database - * locking failure causes transaction-level rollback - *
  • the LockTimeoutException will be thrown if the database - * locking failure causes only statement-level rollback - *
- * @param entity entity instance - * @param lockMode lock mode - * @throws IllegalArgumentException if the instance is not an - * entity or is a detached entity - * @throws TransactionRequiredException if there is no - * transaction or if invoked on an entity manager which - * has not been joined to the current transaction - * @throws EntityNotFoundException if the entity does not exist - * in the database when pessimistic locking is - * performed - * @throws OptimisticLockException if the optimistic version - * check fails - * @throws PessimisticLockException if pessimistic locking fails - * and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - */ - public void lock(Object entity, LockModeType lockMode); - - /** - * Lock an entity instance that is contained in the persistence - * context with the specified lock mode type and with specified - * properties. - *

If a pessimistic lock mode type is specified and the entity - * contains a version attribute, the persistence provider must - * also perform optimistic version checks when obtaining the - * database lock. If these checks fail, the - * OptimisticLockException will be thrown. - *

If the lock mode type is pessimistic and the entity instance - * is found but cannot be locked: - *

    - *
  • the PessimisticLockException will be thrown if the database - * locking failure causes transaction-level rollback - *
  • the LockTimeoutException will be thrown if the database - * locking failure causes only statement-level rollback - *
- *

If a vendor-specific property or hint is not recognized, - * it is silently ignored. - *

Portable applications should not rely on the standard timeout - * hint. Depending on the database in use and the locking - * mechanisms used by the provider, the hint may or may not - * be observed. - * @param entity entity instance - * @param lockMode lock mode - * @param properties standard and vendor-specific properties - * and hints - * @throws IllegalArgumentException if the instance is not an - * entity or is a detached entity - * @throws TransactionRequiredException if there is no - * transaction or if invoked on an entity manager which - * has not been joined to the current transaction - * @throws EntityNotFoundException if the entity does not exist - * in the database when pessimistic locking is - * performed - * @throws OptimisticLockException if the optimistic version - * check fails - * @throws PessimisticLockException if pessimistic locking fails - * and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - * @since 2.0 - */ - public void lock(Object entity, LockModeType lockMode, - Map properties); - - /** - * Lock an entity instance that is contained in the persistence - * context with the specified lock mode type, using specified - * {@linkplain LockOption options}. - *

If a pessimistic lock mode type is specified and the entity - * contains a version attribute, the persistence provider must - * also perform optimistic version checks when obtaining the - * database lock. If these checks fail, the - * OptimisticLockException will be thrown. - *

If the lock mode type is pessimistic and the entity instance - * is found but cannot be locked: - *

    - *
  • the PessimisticLockException will be thrown - * if the database locking failure causes transaction-level - * rollback - *
  • the LockTimeoutException will be thrown if - * the database locking failure causes only statement-level - * rollback - *
- *

If a vendor-specific {@link LockOption} is not recognized, - * it is silently ignored. - *

Portable applications should not rely on the standard - * {@linkplain Timeout timeout option}. Depending on the database - * in use and the locking mechanisms used by the provider, the - * option may or may not be observed. - * @param entity entity instance - * @param lockMode lock mode - * @param options standard and vendor-specific options - * @throws IllegalArgumentException if the instance is not an - * entity or is a detached entity - * @throws TransactionRequiredException if there is no - * transaction or if invoked on an entity manager which - * has not been joined to the current transaction - * @throws EntityNotFoundException if the entity does not exist - * in the database when pessimistic locking is - * performed - * @throws OptimisticLockException if the optimistic version - * check fails - * @throws PessimisticLockException if pessimistic locking fails - * and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call is made - * @since 3.2 - */ - public void lock(Object entity, LockModeType lockMode, - LockOption... options); - - /** - * Refresh the state of the instance from the database, - * overwriting changes made to the entity, if any. - * @param entity entity instance - * @throws IllegalArgumentException if the instance is not - * an entity or the entity is not managed - * @throws TransactionRequiredException if there is no - * transaction when invoked on a container-managed - * entity manager of type PersistenceContextType.TRANSACTION - * @throws EntityNotFoundException if the entity no longer - * exists in the database - */ - public void refresh(Object entity); - - /** - * Refresh the state of the instance from the database, using - * the specified properties, and overwriting changes made to - * the entity, if any. - *

If a vendor-specific property or hint is not recognized, - * it is silently ignored. - * @param entity entity instance - * @param properties standard and vendor-specific properties - * and hints - * @throws IllegalArgumentException if the instance is not - * an entity or the entity is not managed - * @throws TransactionRequiredException if there is no - * transaction when invoked on a container-managed - * entity manager of type PersistenceContextType.TRANSACTION - * @throws EntityNotFoundException if the entity no longer - * exists in the database - * @since 2.0 - */ - public void refresh(Object entity, - Map properties); - - /** - * Refresh the state of the instance from the database, - * overwriting changes made to the entity, if any, and - * lock it with respect to given lock mode type. - *

If the lock mode type is pessimistic and the entity instance - * is found but cannot be locked: - *

    - *
  • the PessimisticLockException will be thrown if the database - * locking failure causes transaction-level rollback - *
  • the LockTimeoutException will be thrown if the - * database locking failure causes only statement-level - * rollback. - *
- * @param entity entity instance - * @param lockMode lock mode - * @throws IllegalArgumentException if the instance is not - * an entity or the entity is not managed - * @throws TransactionRequiredException if invoked on a - * container-managed entity manager of type - * PersistenceContextType.TRANSACTION when there is - * no transaction; if invoked on an extended entity manager when - * there is no transaction and a lock mode other than NONE - * has been specified; or if invoked on an extended entity manager - * that has not been joined to the current transaction and a - * lock mode other than NONE has been specified - * @throws EntityNotFoundException if the entity no longer exists - * in the database - * @throws PessimisticLockException if pessimistic locking fails - * and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - * @since 2.0 - */ - public void refresh(Object entity, LockModeType lockMode); - - /** - * Refresh the state of the instance from the database, - * overwriting changes made to the entity, if any, and - * lock it with respect to given lock mode type and with - * specified properties. - *

If the lock mode type is pessimistic and the entity instance - * is found but cannot be locked: - *

    - *
  • the PessimisticLockException will be thrown if the database - * locking failure causes transaction-level rollback - *
  • the LockTimeoutException will be thrown if the database - * locking failure causes only statement-level rollback - *
- *

If a vendor-specific property or hint is not recognized, - * it is silently ignored. - *

Portable applications should not rely on the standard timeout - * hint. Depending on the database in use and the locking - * mechanisms used by the provider, the hint may or may not - * be observed. - * @param entity entity instance - * @param lockMode lock mode - * @param properties standard and vendor-specific properties - * and hints - * @throws IllegalArgumentException if the instance is not - * an entity or the entity is not managed - * @throws TransactionRequiredException if invoked on a - * container-managed entity manager of type - * PersistenceContextType.TRANSACTION when there is - * no transaction; if invoked on an extended entity manager when - * there is no transaction and a lock mode other than NONE - * has been specified; or if invoked on an extended entity manager - * that has not been joined to the current transaction and a - * lock mode other than NONE has been specified - * @throws EntityNotFoundException if the entity no longer exists - * in the database - * @throws PessimisticLockException if pessimistic locking fails - * and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - * @since 2.0 - */ - public void refresh(Object entity, LockModeType lockMode, - Map properties); - - /** - * Refresh the state of the given entity instance from the - * database, using the specified {@linkplain RefreshOption options}, - * overwriting changes made to the entity, if any. If the supplied - * options include a {@link LockModeType}, lock the given entity with - * respect to the specified lock type. - *

If the lock mode type is pessimistic and the entity instance is - * found but cannot be locked: - *

    - *
  • the PessimisticLockException will be thrown if - * the database locking failure causes transaction-level rollback - *
  • the LockTimeoutException will be thrown if the - * database locking failure causes only statement-level rollback - *
- *

If a vendor-specific {@link RefreshOption} is not recognized, - * it is silently ignored. - *

Portable applications should not rely on the standard - * {@linkplain Timeout timeout option}. Depending on the database in - * use and the locking mechanisms used by the provider, the hint may - * or may not be observed. - * @param entity entity instance - * @param options standard and vendor-specific options - * @throws IllegalArgumentException if the instance is not an entity - * or the entity is not managed - * @throws TransactionRequiredException if invoked on a - * container-managed entity manager of type - * PersistenceContextType.TRANSACTION when there - * is no transaction; if invoked on an extended entity manager - * when there is no transaction and a lock mode other than - * NONE has been specified; or if invoked on an - * extended entity manager that has not been joined to the - * current transaction and a lock mode other than - * NONE has been specified - * @throws EntityNotFoundException if the entity no longer exists in - * the database - * @throws PessimisticLockException if pessimistic locking fails and - * the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and only - * the statement is rolled back - * @throws PersistenceException if an unsupported lock call is made - * @since 3.2 - */ - public void refresh(Object entity, - RefreshOption... options); - - /** - * Clear the persistence context, causing all managed - * entities to become detached. Changes made to entities that - * have not been flushed to the database will not be - * persisted. - */ - public void clear(); - - /** - * Remove the given entity from the persistence context, causing - * a managed entity to become detached. Unflushed changes made - * to the entity if any (including removal of the entity), - * will not be synchronized to the database. Entities which - * previously referenced the detached entity will continue to - * reference it. - * @param entity entity instance - * @throws IllegalArgumentException if the instance is not an - * entity - * @since 2.0 - */ - public void detach(Object entity); - - /** - * Check if the instance is a managed entity instance belonging - * to the current persistence context. - * @param entity entity instance - * @return boolean indicating if entity is in persistence context - * @throws IllegalArgumentException if not an entity - */ - public boolean contains(Object entity); - - /** - * Get the current lock mode for the entity instance. - * @param entity entity instance - * @return lock mode - * @throws TransactionRequiredException if there is no - * transaction or if the entity manager has not been - * joined to the current transaction - * @throws IllegalArgumentException if the instance is not a - * managed entity and a transaction is active - * @since 2.0 - */ - public LockModeType getLockMode(Object entity); - - /** - * Set the cache retrieval mode that is in effect during - * query execution. This cache retrieval mode overrides the - * cache retrieve mode in use by the entity manager. - * @param cacheRetrieveMode cache retrieval mode - * @since 3.2 - */ - public void setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode); - - /** - * Set the default cache storage mode for this persistence context. - * @param cacheStoreMode cache storage mode - * @since 3.2 - */ - public void setCacheStoreMode(CacheStoreMode cacheStoreMode); - - /** - * The cache retrieval mode for this persistence context. - * @since 3.2 - */ - public CacheRetrieveMode getCacheRetrieveMode(); - - /** - * The cache storage mode for this persistence context. - * @since 3.2 - */ - public CacheStoreMode getCacheStoreMode(); - - /** - * Set an entity manager property or hint. - * If a vendor-specific property or hint is not recognized, it is - * silently ignored. - * @param propertyName name of property or hint - * @param value value for property or hint - * @throws IllegalArgumentException if the second argument is - * not valid for the implementation - * @since 2.0 - */ - public void setProperty(String propertyName, Object value); - - /** - * Get the properties and hints and associated values that are in effect - * for the entity manager. Changing the contents of the map does - * not change the configuration in effect. - * @return map of properties and hints in effect for entity manager - * @since 2.0 - */ - public Map getProperties(); - - /** - * Create an instance of Query for executing a - * Jakarta Persistence query language statement. - * @param qlString a Jakarta Persistence query string - * @return the new query instance - * @throws IllegalArgumentException if the query string is - * found to be invalid - */ - public Query createQuery(String qlString); - - /** - * Create an instance of TypedQuery for executing a - * criteria query. - * @param criteriaQuery a criteria query object - * @return the new query instance - * @throws IllegalArgumentException if the criteria query is - * found to be invalid - * @since 2.0 - */ - public TypedQuery createQuery(CriteriaQuery criteriaQuery); - - /** - * Create an instance of TypedQuery for executing a - * criteria query, which may be a union or intersection of - * top-level queries. - * @param criteriaQuery a criteria query object - * @return the new query instance - * @throws IllegalArgumentException if the criteria query is - * found to be invalid - * @since 3.2 - */ - TypedQuery createQuery(CriteriaSelect criteriaQuery); - - /** - * Create an instance of Query for executing a criteria - * update query. - * @param updateQuery a criteria update query object - * @return the new query instance - * @throws IllegalArgumentException if the update query is - * found to be invalid - * @since 2.1 - */ - public Query createQuery(CriteriaUpdate updateQuery); - - /** - * Create an instance of Query for executing a criteria - * delete query. - * @param deleteQuery a criteria delete query object - * @return the new query instance - * @throws IllegalArgumentException if the delete query is - * found to be invalid - * @since 2.1 - */ - public Query createQuery(CriteriaDelete deleteQuery); - - /** - * Create an instance of TypedQuery for executing a - * Jakarta Persistence query language statement. - * The select list of the query must contain only a single - * item, which must be assignable to the type specified by - * the resultClass argument. - * @param qlString a Jakarta Persistence query string - * @param resultClass the type of the query result - * @return the new query instance - * @throws IllegalArgumentException if the query string is found - * to be invalid or if the query result is found to - * not be assignable to the specified type - * @since 2.0 - */ - public TypedQuery createQuery(String qlString, Class resultClass); - - /** - * Create an instance of Query for executing a named query - * (in the Jakarta Persistence query language or in native SQL). - * @param name the name of a query defined in metadata - * @return the new query instance - * @throws IllegalArgumentException if a query has not been - * defined with the given name or if the query string is - * found to be invalid - */ - public Query createNamedQuery(String name); - - /** - * Create an instance of TypedQuery for executing a - * Jakarta Persistence query language named query. - * The select list of the query must contain only a single - * item, which must be assignable to the type specified by - * the resultClass argument. - * @param name the name of a query defined in metadata - * @param resultClass the type of the query result - * @return the new query instance - * @throws IllegalArgumentException if a query has not been - * defined with the given name or if the query string is - * found to be invalid or if the query result is found to - * not be assignable to the specified type - * @since 2.0 - */ - public TypedQuery createNamedQuery(String name, Class resultClass); - - /** - * Create an instance of Query for executing - * a native SQL statement, e.g., for update or delete. - * If the query is not an update or delete query, query - * execution will result in each row of the SQL result - * being returned as a result of type Object[] (or a result - * of type Object if there is only one column in the select - * list.) Column values are returned in the order of their - * appearance in the select list and default JDBC type - * mappings are applied. - * @param sqlString a native SQL query string - * @return the new query instance - */ - public Query createNativeQuery(String sqlString); - - /** - * Create an instance of Query for executing - * a native SQL query. - * @param sqlString a native SQL query string - * @param resultClass the class of the resulting instance(s) - * @return the new query instance - */ - public Query createNativeQuery(String sqlString, Class resultClass); - - /** - * Create an instance of Query for executing - * a native SQL query. - * @param sqlString a native SQL query string - * @param resultSetMapping the name of the result set mapping - * @return the new query instance - */ - public Query createNativeQuery(String sqlString, String resultSetMapping); - - /** - * Create an instance of StoredProcedureQuery for executing a - * stored procedure in the database. - *

Parameters must be registered before the stored procedure can - * be executed. - *

If the stored procedure returns one or more result sets, - * any result set will be returned as a list of type Object[]. - * @param name name assigned to the stored procedure query - * in metadata - * @return the new stored procedure query instance - * @throws IllegalArgumentException if a query has not been - * defined with the given name - * @since 2.1 - */ - public StoredProcedureQuery createNamedStoredProcedureQuery(String name); - - /** - * Create an instance of StoredProcedureQuery for executing a - * stored procedure in the database. - *

Parameters must be registered before the stored procedure can - * be executed. - *

If the stored procedure returns one or more result sets, - * any result set will be returned as a list of type Object[]. - * @param procedureName name of the stored procedure in the - * database - * @return the new stored procedure query instance - * @throws IllegalArgumentException if a stored procedure of the - * given name does not exist (or the query execution will - * fail) - * @since 2.1 - */ - public StoredProcedureQuery createStoredProcedureQuery(String procedureName); - - /** - * Create an instance of StoredProcedureQuery for executing a - * stored procedure in the database. - *

Parameters must be registered before the stored procedure can - * be executed. - *

The resultClass arguments must be specified in the order in - * which the result sets will be returned by the stored procedure - * invocation. - * @param procedureName name of the stored procedure in the - * database - * @param resultClasses classes to which the result sets - * produced by the stored procedure are to - * be mapped - * @return the new stored procedure query instance - * @throws IllegalArgumentException if a stored procedure of the - * given name does not exist (or the query execution will - * fail) - * @since 2.1 - */ - public StoredProcedureQuery createStoredProcedureQuery( - String procedureName, Class... resultClasses); - - /** - * Create an instance of StoredProcedureQuery for executing a - * stored procedure in the database. - *

Parameters must be registered before the stored procedure can - * be executed. - *

The resultSetMapping arguments must be specified in the order - * in which the result sets will be returned by the stored - * procedure invocation. - * @param procedureName name of the stored procedure in the - * database - * @param resultSetMappings the names of the result set mappings - * to be used in mapping result sets - * returned by the stored procedure - * @return the new stored procedure query instance - * @throws IllegalArgumentException if a stored procedure or - * result set mapping of the given name does not exist - * (or the query execution will fail) - */ - public StoredProcedureQuery createStoredProcedureQuery( - String procedureName, String... resultSetMappings); - - /** - * Indicate to the entity manager that a JTA transaction is - * active and join the persistence context to it. - *

This method should be called on a JTA application - * managed entity manager that was created outside the scope - * of the active transaction or on an entity manager of type - * SynchronizationType.UNSYNCHRONIZED to associate - * it with the current JTA transaction. - * @throws TransactionRequiredException if there is - * no transaction - */ - public void joinTransaction(); - - /** - * Determine whether the entity manager is joined to the - * current transaction. Returns false if the entity manager - * is not joined to the current transaction or if no - * transaction is active - * @return boolean - * @since 2.1 - */ - public boolean isJoinedToTransaction(); - - /** - * Return an object of the specified type to allow access to the - * provider-specific API. If the provider's EntityManager - * implementation does not support the specified class, the - * PersistenceException is thrown. - * @param cls the class of the object to be returned. This is - * normally either the underlying EntityManager implementation - * class or an interface that it implements. - * @return an instance of the specified class - * @throws PersistenceException if the provider does not - * support the call - * @since 2.0 - */ - public T unwrap(Class cls); - - /** - * Return the underlying provider object for the EntityManager, - * if available. The result of this method is implementation - * specific. - *

The unwrap method is to be preferred for new applications. - * @return underlying provider object for EntityManager - */ - public Object getDelegate(); - - /** - * Close an application-managed entity manager. - * After the close method has been invoked, all methods - * on the EntityManager instance and any - * Query, TypedQuery, and - * StoredProcedureQuery objects obtained from - * it will throw the IllegalStateException - * except for getProperties, - * getTransaction, and isOpen (which will return false). - * If this method is called when the entity manager is - * joined to an active transaction, the persistence - * context remains managed until the transaction completes. - * @throws IllegalStateException if the entity manager - * is container-managed - */ - public void close(); - - /** - * Determine whether the entity manager is open. - * @return true until the entity manager has been closed - */ - public boolean isOpen(); - - /** - * Return the resource-level EntityTransaction object. - * The EntityTransaction instance may be used serially to - * begin and commit multiple transactions. - * @return EntityTransaction instance - * @throws IllegalStateException if invoked on a JTA - * entity manager - */ - public EntityTransaction getTransaction(); - - /** - * Return the entity manager factory for the entity manager. - * @return EntityManagerFactory instance - * @throws IllegalStateException if the entity manager has - * been closed - * @since 2.0 - */ - public EntityManagerFactory getEntityManagerFactory(); - - /** - * Return an instance of CriteriaBuilder for the creation of - * CriteriaQuery objects. - * @return CriteriaBuilder instance - * @throws IllegalStateException if the entity manager has - * been closed - * @since 2.0 - */ - public CriteriaBuilder getCriteriaBuilder(); - - /** - * Return an instance of Metamodel interface for access to the - * metamodel of the persistence unit. - * @return Metamodel instance - * @throws IllegalStateException if the entity manager has - * been closed - * @since 2.0 - */ - public Metamodel getMetamodel(); - - /** - * Return a mutable EntityGraph that can be used to dynamically create an - * EntityGraph. - * @param rootType class of entity graph - * @return entity graph - * @since 2.1 - */ - public EntityGraph createEntityGraph(Class rootType); - - /** - * Return a mutable copy of the named EntityGraph. If there - * is no entity graph with the specified name, null is returned. - * @param graphName name of an entity graph - * @return entity graph - * @since 2.1 - */ - public EntityGraph createEntityGraph(String graphName); - - /** - * Return a named EntityGraph. The returned EntityGraph - * should be considered immutable. - * @param graphName name of an existing entity graph - * @return named entity graph - * @throws IllegalArgumentException if there is no EntityGraph of - * the given name - * @since 2.1 - */ - public EntityGraph getEntityGraph(String graphName); - - /** - * Return all named EntityGraphs that have been defined for the provided - * class type. - * @param entityClass entity class - * @return list of all entity graphs defined for the entity - * @throws IllegalArgumentException if the class is not an entity - * @since 2.1 - */ - public List> getEntityGraphs(Class entityClass); - - /** - * Execute the given action using the database connection underlying this - * {@code EntityManager}. Usually, the connection is a JDBC connection, but a - * provider might support some other native connection type, and is not required - * to support {@code java.sql.Connection}. If this {@code EntityManager} is - * associated with a transaction, the action is executed in the context of the - * transaction. The given action should close any resources it creates, but should - * not close the connection itself, nor commit or roll back the transaction. If - * the given action throws an exception, the persistence provider must mark the - * transaction for rollback. - * @param action the action - * @param the connection type, usually {@code java.sql.Connection} - * @throws PersistenceException wrapping the checked {@link Exception} thrown by - * {@link ConnectionConsumer#accept}, if any - * @since 3.2 - */ - public void runWithConnection(ConnectionConsumer action); - - /** - * Call the given function and return its result using the database connection - * underlying this {@code EntityManager}. Usually, the connection is a JDBC - * connection, but a provider might support some other native connection type, - * and is not required to support {@code java.sql.Connection}. If this - * {@code EntityManager} is associated with a transaction, the function is - * executed in the context of the transaction. The given function should close - * any resources it creates, but should not close the connection itself, nor - * commit or roll back the transaction. If the given action throws an exception, - * the persistence provider must mark the transaction for rollback. - * @param function the function - * @param the connection type, usually {@code java.sql.Connection} - * @param the type of result returned by the function - * @return the value returned by {@link ConnectionFunction#apply}. - * @throws PersistenceException wrapping the checked {@link Exception} thrown by - * {@link ConnectionFunction#apply}, if any - * @since 3.2 - */ - public T callWithConnection(ConnectionFunction function); - -} ----- - -[NOTE] -==== -The semantics of - - public TypedQuery createQuery(String qlString, Class resultClass) - -method may be extended in a future release of this specification to -support other result types. Applications that specify other result types -(e.g., Tuple.class) will not be portable. -==== - -[NOTE] -==== -The semantics - - public TypedQuery createNamedQuery(String name, Class resultClass) - -method may be extended in a future release of this specification to -support other result types. Applications that specify other result types -(e.g., Tuple.class) will not be portable. -==== +The `EntityManager` interface may be found in <<_entitymanager_>>. The `persist`, `merge`, `remove`, and `refresh` methods must be invoked within a transaction context when an @@ -1356,6 +144,29 @@ public class OrderEntryBean implements OrderEntry { } ---- +[NOTE] +==== +The semantics of + + public TypedQuery createQuery(String qlString, Class resultClass) + +method may be extended in a future release of this specification to +support other result types. Applications that specify other result types +(e.g., Tuple.class) will not be portable. +==== + +[NOTE] +==== +The semantics + + public TypedQuery createNamedQuery(String name, Class resultClass) + +method may be extended in a future release of this specification to +support other result types. Applications that specify other result types +(e.g., Tuple.class) will not be portable. +==== + + === Entity Instance's Life Cycle [[a1929]] This section describes the `EntityManager` @@ -1773,12 +584,7 @@ with injection or JNDI lookup). See <>. [source,java] ---- -package jakarta.persistence; - -public enum PersistenceContextType { - TRANSACTION, - EXTENDED -} +include::../../../../api/src/main/java/jakarta/persistence/PersistenceContextType.java[lines=18..-1] ---- By default, the lifetime of the persistence @@ -2083,12 +889,7 @@ The values of the [source,java] ---- -package jakarta.persistence; - -public enum PessimisticLockScope { - NORMAL, - EXTENDED -} +include::../../../../api/src/main/java/jakarta/persistence/PessimisticLockScope.java[lines=18..-1] ---- This specification does not define the @@ -2133,21 +934,7 @@ NONE may be specified as a value of lock mode arguments and also provides a default value for annotations.] The latter are to be preferred for new applications. -[source,java] ----- -package jakarta.persistence; - -public enum LockModeType { - READ, - WRITE, - OPTIMISTIC, - OPTIMISTIC_FORCE_INCREMENT, - PESSIMISTIC_READ, - PESSIMISTIC_WRITE, - PESSIMISTIC_FORCE_INCREMENT, - NONE -} ----- +This enum may be found in <<_lockmodetype_>>. ===== OPTIMISTIC, OPTIMISTIC_FORCE_INCREMENT [[a2100]] @@ -2189,8 +976,9 @@ required to support calling `lock(entity, LockModeType.OPTIMISTIC)` on a non-versioned object. When it cannot support such a lock call, it must throw the `PersistenceException`. When supported, whether for versioned or non-versioned objects, `LockModeType.OPTIMISTIC` must always prevent -the phenomena P1 and P2. Applications that call `lock(entity, -LockModeType.OPTIMISTIC)` on non-versioned objects will not be portable. +the phenomena P1 and P2. Applications that call +`lock(entity, LockModeType.OPTIMISTIC)` on non-versioned objects are not +portable. If transaction T1 calls `lock(entity, LockModeType.OPTIMISTIC_FORCE_INCREMENT)` on a versioned object, the entity manager must avoid the phenomena P1 and P2 @@ -3121,517 +1909,7 @@ override these annotations or to define additional named entity graphs. The semantics of entity graphs with regard to find and query operations are described in <>. -==== Graph Interface - -[source,java] ----- -package jakarta.persistence; - -import jakarta.persistence.metamodel.Attribute; -import jakarta.persistence.metamodel.MapAttribute; -import jakarta.persistence.metamodel.PluralAttribute; - -import java.util.List; - -/** -* Declares operations common to {@link EntityGraph} and {@link Subgraph}. -* -* @see EntityGraph -* @see Subgraph -* -* @since 3.2 -*/ -public interface Graph { - - /** - * Add an attribute nodes to the entity graph. - * - * @param attributeName name of the attribute - * @throws IllegalArgumentException if the attribute is not an - * attribute of this entity. - * @throws IllegalStateException if the EntityGraph has been - * statically defined - * - * @since 3.2 - */ - public void addAttributeNode(String attributeName); - - /** - * Add an attribute node to the entity graph. - * - * @param attribute attribute - * @throws IllegalStateException if the EntityGraph has been - * statically defined - * - * @since 3.2 - */ - public void addAttributeNode(Attribute attribute); - - /** - * Remove an attribute node from the entity graph. - * When this graph is interpreted as a load graph, this operation - * suppresses inclusion of an attribute mapped for eager fetching. - * The effect of this call may be overridden by subsequent - * invocations of {@link #addAttributeNode} or {@link #addSubgraph}. - * @param attributeName name of the attribute - * @since 3.2 - */ - public void removeAttributeNode(String attributeName); - - /** - * Remove an attribute node from the entity graph. - * When this graph is interpreted as a load graph, this operation - * suppresses inclusion of an attribute mapped for eager fetching. - * The effect of this call may be overridden by subsequent - * invocations of {@link #addAttributeNode} or {@link #addSubgraph}. - * @param attribute attribute - * @since 3.2 - */ - public void removeAttributeNode(Attribute attribute); - - /** - * Remove all attribute nodes of the given attribute types. - * When this graph is interpreted as a load graph, this operation - * suppresses inclusion of attributes mapped for eager fetching. - * The effect of this call may be overridden by subsequent - * invocations of {@link #addAttributeNode} or {@link #addSubgraph}. - * @since 3.2 - */ - public void removeAttributeNodes(Attribute.PersistentAttributeType nodeTypes); - - /** - * Add one or more attribute nodes to the entity graph. - * - * @param attributeName name of the attribute - * @throws IllegalArgumentException if the attribute is not an - * attribute of this managed type. - * @throws IllegalStateException if the EntityGraph has been - * statically defined - */ - public void addAttributeNodes(String ... attributeName); - - /** - * Add one or more attribute nodes to the entity graph. - * @param attribute attribute - * - * @throws IllegalStateException if this EntityGraph has been - * statically defined - */ - public void addAttributeNodes(Attribute... attribute); - - /** - * Add a node to the graph that corresponds to a managed - * type. This allows for construction of multi-node entity graphs - * that include related managed types. - * - * @param attribute attribute - * @return subgraph for the attribute - * @throws IllegalArgumentException if the attribute's target - * type is not a managed type - * @throws IllegalStateException if the EntityGraph has been - * statically defined - */ - public Subgraph addSubgraph(Attribute attribute); - - /** - * Add a node to the graph that corresponds to a managed - * type with inheritance. This allows for multiple subclass - * subgraphs to be defined for this node of the entity - * graph. Subclass subgraphs will automatically include the - * specified attributes of superclass subgraphs. - * - * @param attribute attribute - * @param type entity subclass - * @return subgraph for the attribute - * @throws IllegalArgumentException if the attribute's target - * type is not a managed type - * @throws IllegalStateException if the EntityGraph has been - * statically defined - * - * @since 3.2 - */ - public Subgraph addTreatedSubgraph(Attribute attribute, Class type); - - /** - * Add a node to the graph that corresponds to a managed - * type with inheritance. This allows for multiple subclass - * subgraphs to be defined for this node of the entity - * graph. Subclass subgraphs will automatically include the specified - * attributes of superclass subgraphs - * - * @param attribute attribute - * @param type entity subclass - * @return subgraph for the attribute - * @throws IllegalArgumentException if the attribute's target - * type is not a managed type - * @throws IllegalStateException if this EntityGraph has been - * statically defined - * @deprecated use {@link #addTreatedSubgraph(Attribute, Class)} - */ - @Deprecated(since = "3.2", forRemoval = true) - public Subgraph addSubgraph(Attribute attribute, Class type); - - /** - * Add a node to the graph that corresponds to a managed - * type. This allows for construction of multi-node entity graphs - * that include related managed types. - * - * @param attributeName name of the attribute - * @return subgraph for the attribute - * @throws IllegalArgumentException if the attribute is not an - * attribute of this managed type. - * @throws IllegalArgumentException if the attribute's target - * type is not a managed type - * @throws IllegalStateException if this EntityGraph has been - * statically defined - */ - public Subgraph addSubgraph(String attributeName); - - /** - * Add a node to the graph that corresponds to a managed - * type with inheritance. This allows for multiple subclass - * subgraphs to be defined for this node of the entity - * graph. Subclass subgraphs will automatically include the - * specified attributes of superclass subgraphs - * - * @param attributeName name of the attribute - * @param type entity subclass - * @return subgraph for the attribute - * @throws IllegalArgumentException if the attribute is not - * an attribute of this managed type. - * @throws IllegalArgumentException if the attribute's target - * type is not a managed type - * @throws IllegalStateException if this EntityGraph has been - * statically defined - */ - public Subgraph addSubgraph(String attributeName, Class type); - - /** - * Add a node to the graph that corresponds to a collection element - * that is a managed type. This allows for construction of - * multi-node entity graphs that include related managed types. - * - * @param attribute attribute - * @return subgraph for the element attribute - * @throws IllegalArgumentException if the attribute's target type - * is not an entity - * @throws IllegalStateException if this EntityGraph has been - * statically defined - * - * @since 3.2 - */ - public Subgraph addElementSubgraph(PluralAttribute attribute); - - /** - * Add a node to the graph that corresponds to a collection element - * that is a managed type. This allows for construction of - * multi-node entity graphs that include related managed types. - * - * @param attribute attribute - * @return subgraph for the element attribute - * @throws IllegalArgumentException if the attribute's target type - * is not an entity - * @throws IllegalStateException if this EntityGraph has been - * statically defined - * - * @since 3.2 - */ - public Subgraph addTreatedElementSubgraph(PluralAttribute attribute, Class type); - - /** - * Add a node to the graph that corresponds to a collection element - * that is a managed type. This allows for construction of - * multi-node entity graphs that include related managed types. - * - * @param attributeName name of the attribute - * @return subgraph for the element attribute - * @throws IllegalArgumentException if the attribute is not an - * attribute of this entity. - * @throws IllegalArgumentException if the attribute's target - * type is not a managed type - * @throws IllegalStateException if this EntityGraph has been - * statically defined - */ - public Subgraph addElementSubgraph(String attributeName); - - /** - * Add a node to the graph that corresponds to a collection element - * that is a managed type. This allows for construction of - * multi-node entity graphs that include related managed types. - * - * @param attributeName name of the attribute - * @param type entity subclass - * @return subgraph for the element attribute - * @throws IllegalArgumentException if the attribute is not an - * attribute of this entity. - * @throws IllegalArgumentException if the attribute's target - * type is not a managed type - * @throws IllegalStateException if this EntityGraph has been - * statically defined - */ - public Subgraph addElementSubgraph(String attributeName, Class type); - - /** - * Add a node to the graph that corresponds to a map key - * that is a managed type. This allows for construction of - * multi-node entity graphs that include related managed types. - * - * @param attribute attribute - * @return subgraph for the key attribute - * @throws IllegalArgumentException if the attribute's target - * type is not a managed type entity - * @throws IllegalStateException if this EntityGraph has been - * statically defined - */ - public Subgraph addMapKeySubgraph(MapAttribute attribute); - - /** - * Add a node to the graph that corresponds to a map key - * that is a managed type with inheritance. This allows for - * construction of multi-node entity graphs that include related - * managed types. Subclass subgraphs will automatically include - * the specified attributes of superclass subgraphs - * - * @param attribute attribute - * @param type entity subclass - * @return subgraph for the attribute - * @throws IllegalArgumentException if the attribute's target - * type is not a managed type entity - * @throws IllegalStateException if this EntityGraph has been - * statically defined - */ - public Subgraph addTreatedMapKeySubgraph(MapAttribute attribute, Class type); - - /** - * Add a node to the graph that corresponds to a map key - * that is a managed type. This allows for construction of - * multi-node entity graphs that include related managed types. - * - * @param attribute attribute - * @return subgraph for the key attribute - * @throws IllegalArgumentException if the attribute's target - * type is not a managed type entity - * @throws IllegalStateException if this EntityGraph has been - * statically defined - * @deprecated use {@link #addMapKeySubgraph(MapAttribute)} - */ - @Deprecated(since = "3.2", forRemoval = true) - public Subgraph addKeySubgraph(Attribute attribute); - - /** - * Add a node to the graph that corresponds to a map key - * that is a managed type with inheritance. This allows for - * construction of multi-node entity graphs that include related - * managed types. Subclass subgraphs will automatically include - * the specified attributes of superclass subgraphs - * - * @param attribute attribute - * @param type entity subclass - * @return subgraph for the attribute - * @throws IllegalArgumentException if the attribute's target - * type is not a managed type entity - * @throws IllegalStateException if this EntityGraph has been - * statically defined - * @deprecated use {@link #addTreatedMapKeySubgraph(MapAttribute, Class)} - */ - @Deprecated(since = "3.2", forRemoval = true) - public Subgraph addKeySubgraph(Attribute attribute, Class type); - - /** - * Add a node to the graph that corresponds to a map key - * that is a managed type. This allows for construction of - * multi-node entity graphs that include related managed types. - * - * @param attributeName name of the attribute - * @return subgraph for the key attribute - * @throws IllegalArgumentException if the attribute is not an - * attribute of this entity. - * @throws IllegalArgumentException if the attribute's target - * type is not a managed type - * @throws IllegalStateException if this EntityGraph has been - * statically defined - */ - public Subgraph addKeySubgraph(String attributeName); - - /** - * Add a node to the graph that corresponds to a map key - * that is a managed type with inheritance. This allows for - * construction of multi-node entity graphs that include related - * managed types. Subclass subgraphs will include the specified - * attributes of superclass subgraphs - * - * @param attributeName name of the attribute - * @param type entity subclass - * @return subgraph for the attribute - * @throws IllegalArgumentException if the attribute is not an - * attribute of this entity. - * @throws IllegalArgumentException if the attribute's target - * type is not a managed type - * @throws IllegalStateException if this EntityGraph has been - * statically defined - */ - public Subgraph addKeySubgraph(String attributeName, Class type); - - /** - * Return the attribute nodes corresponding to the attributes of - * this managed type that are included in the graph. - * @return list of attribute nodes included in the graph or an - * empty list if none have been defined - */ - public List> getAttributeNodes(); - -} ----- - -The deprecated methods of this interface will be removed -in a future major release of this specification. - -==== EntityGraph Interface - -[source,java] ----- -package jakarta.persistence; - -/** - * This type represents the root of an entity graph that will be used - * as a template to define the attribute nodes and boundaries of a - * graph of entities and entity relationships. The root must be an - * entity type. - *

- * The methods to add subgraphs implicitly create the - * corresponding attribute nodes as well; such attribute nodes - * should not be redundantly specified. - * - * @param The type of the root entity. - * - * @see AttributeNode - * @see Subgraph - * @see NamedEntityGraph - * - * @since 2.1 - */ -public interface EntityGraph extends Graph { - - /** - * Return the name of a named EntityGraph (an entity graph - * defined by means of the NamedEntityGraph - * annotation, XML descriptor element, or added by means of the - * addNamedEntityGraph method. Returns null if the - * EntityGraph is not a named EntityGraph. - */ - public String getName(); - - /** - * Add additional attributes to this entity graph that - * correspond to attributes of subclasses of this EntityGraph's - * entity type. Subclass subgraphs will automatically include the - * specified attributes of superclass subgraphs. - * - * @param type entity subclass - * @return subgraph for the subclass - * @throws IllegalArgumentException if the type is not an entity type - * @throws IllegalStateException if the EntityGraph has been - * statically defined - */ - public Subgraph addTreatedSubgraph(Class type); - - /** - * Add additional attributes to this entity graph that - * correspond to attributes of subclasses of this EntityGraph's - * entity type. Subclass subgraphs will automatically include the - * specified attributes of superclass subgraphs. - * - * @param type entity subclass - * @return subgraph for the subclass - * @throws IllegalArgumentException if the type is not an entity type - * @throws IllegalStateException if the EntityGraph has been - * statically defined - * @deprecated use {@link #addTreatedSubgraph(Class)} - */ - @Deprecated(since = "3.2", forRemoval = true) - public Subgraph addSubclassSubgraph(Class type); - -} ----- - -The deprecated method of this interface will be removed -in a future major release of this specification. - -==== AttributeNode Interface - -[source,java] ----- -package jakarta.persistence; - -import java.util.Map; - -/** - * Represents an attribute node of an entity graph. - * - * @param The type of the attribute. - * - * @see EntityGraph - * @see Subgraph - * @see NamedAttributeNode - * - * @since 2.1 - */ -public interface AttributeNode { - - /** - * Return the name of the attribute corresponding to the - * attribute node. - * @return name of the attribute - */ - public String getAttributeName(); - - /** - * Return the Map<Class, Subgraph> of subgraphs associated - * with this attribute node. - * @return Map of subgraphs associated with this attribute node - * or empty Map if none have been defined - */ - public Map getSubgraphs(); - - /** - * Return the Map<Class, Subgraph> of subgraphs associated - * with this attribute node's map key. - * @return Map of subgraphs associated with this attribute - * node's map key or empty Map if none have been defined - */ - public Map getKeySubgraphs(); -} ----- - -==== Subgraph Interface - -[source,java] ----- -package jakarta.persistence; - -/** - * This type represents a subgraph for an attribute node that - * corresponds to a Managed Type. Using this class, an entity subgraph - * can be embedded within an EntityGraph. - * - * @param The type of the attribute. - * - * @see EntityGraph - * @see AttributeNode - * @see NamedSubgraph - * - * @since 2.1 - */ -public interface Subgraph extends Graph { - - /** - * Return the type for which this subgraph was defined. - * @return managed type referenced by the subgraph - */ - public Class getClassType(); - -} ----- +These interfaces may be found in <>. ==== Use of Entity Graphs in find and query operations [[a2814]] @@ -3981,46 +2259,10 @@ other, more complex attribute types. See <>. [source,java] ---- -package jakarta.persistence; - -/** - * A class that implements this interface can be used to convert - * entity attribute state into database column representation - * and back again. - * Note that the X and Y types may be the same Java type. - * - * @param the type of the entity attribute - * @param the type of the database column - */ -public interface AttributeConverter { - - /** - * Converts the value stored in the entity attribute into the - * data representation to be stored in the database. - * - * @param attribute the entity attribute value to be converted - * @return the converted data to be stored in the database - * column - */ - public Y convertToDatabaseColumn (X attribute); - - /** - * Converts the data stored in the database column into the - * value to be stored in the entity attribute. - * Note that it is the responsibility of the converter writer to - * specify the correct dbData type for the corresponding - * column for use by the JDBC driver: i.e., persistence providers are - * not expected to do such type conversion. - * - * @param dbData the data from the database column to be - * converted - * @return the converted value to be stored in the entity - * attribute - */ - public X convertToEntityAttribute (Y dbData); -} +include::../../../../api/src/main/java/jakarta/persistence/AttributeConverter.java[lines=18..-1] ---- + Attribute converter classes in Jakarta EE environments support dependency injection through the Contexts and Dependency Injection API (CDI) <> when CDI is @@ -4236,70 +2478,17 @@ specification. The semantics of each mode is defined by its Javadoc. [source,java] ---- -package jakarta.persistence; - -/** - * Used as the value of the - * jakarta.persistence.cache.retrieveMode property to - * specify the behavior when data is retrieved by the - * find methods and by queries. - * - * @since 2.0 - */ -public enum CacheRetrieveMode { - - /** - * Read entity data from the cache: this is - * the default behavior. - */ - USE, - - /** - * Bypass the cache: get data directly from - * the database. - */ - BYPASS -} +include::../../../../api/src/main/java/jakarta/persistence/CacheRetrieveMode.java[lines=18..-1] ---- + `CacheStoreMode` enumerates the cache store modes recognized by this specification. The semantics of each mode is defined by its Javadoc. [source,java] ---- -package jakarta.persistence; - -/** - * Used as the value of the - * jakarta.persistence.cache.storeMode property to specify - * the behavior when data is read from the database and when data is - * committed into the database. - * - * @since 2.0 - */ -public enum CacheStoreMode { - - /** - * Insert entity data into cache when read from database - * and insert/update entity data when committed into database: - * this is the default behavior. Does not force refresh - * of already cached items when reading from database. - */ - USE, - - /** - * Don't insert into cache. - */ - BYPASS, - - /** - * Insert/update entity data into cache when read - * from database and when committed into database. - * Forces refresh of cache for items read from database. - */ - REFRESH -} +include::../../../../api/src/main/java/jakarta/persistence/CacheStoreMode.java[lines=18..-1] ---- ==== Cache Interface [[a12124]] @@ -4308,62 +2497,7 @@ The `Cache` interface allows the application to request eviction of entity data from the second-level cache directly and immediately, outside the scope of any persistence context. -[source,java] ----- -package jakarta.persistence; - -/** - * Interface used to interact with the second-level cache. - * If a cache is not in use, the methods of this interface have - * no effect, except for contains, which returns false. - * - * @since 2.0 - */ -public interface Cache { - - /** - * Whether the cache contains data for the given entity. - * @param cls entity class - * @param primaryKey primary key - * @return boolean indicating whether the entity is in the cache - */ - public boolean contains(Class cls, Object primaryKey); - - /** - * Remove the data for the given entity from the cache. - * @param cls entity class - * @param primaryKey primary key - */ - public void evict(Class cls, Object primaryKey); - - /** - * Remove the data for entities of the specified class (and its - * subclasses) from the cache. - * @param cls entity class - */ - public void evict(Class cls); - - /** - * Clear the cache. - */ - public void evictAll(); - - /** - * Return an object of the specified type to allow access to the - * provider-specific API. If the provider's Cache - * implementation does not support the specified class, the - * PersistenceException is thrown. - * @param cls the class of the object to be returned. This is - * normally either the underlying Cache implementation - * class or an interface that it implements. - * @return an instance of the specified class - * @throws PersistenceException if the provider does not - * support the call - * @since 2.1 - */ - public T unwrap(Class cls); -} ----- +This interface may be found in <<_cache_>>. === Query APIs [[a3125]] @@ -4373,1535 +2507,7 @@ also support parameter binding and pagination control. The `StoredProcedureQuery` API is used for the execution of queries that invoke stored procedures defined in the database. -==== Query Interface [[a3127]] - -[source,java] ----- -package jakarta.persistence; - -import java.util.Calendar; -import java.util.Date; -import java.util.List; -import java.util.Set; -import java.util.Map; -import java.util.stream.Stream; - -/** - * Interface used to control query execution. - * - * @see TypedQuery - * @see StoredProcedureQuery - * @see Parameter - * - * @since 1.0 - */ -public interface Query { - - /** - * Execute a SELECT query and return the query results - * as an untyped List. - * @return a list of the results - * @throws IllegalStateException if called for a Jakarta - * Persistence query language UPDATE or DELETE statement - * @throws QueryTimeoutException if the query execution exceeds - * the query timeout value set and only the statement is - * rolled back - * @throws TransactionRequiredException if a lock mode other than - * NONE has been set and there is no transaction - * or the persistence context has not been joined to the transaction - * @throws PessimisticLockException if pessimistic locking - * fails and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking - * fails and only the statement is rolled back - * @throws PersistenceException if the query execution exceeds - * the query timeout value set and the transaction - * is rolled back - */ - List getResultList(); - - /** - * Execute a SELECT query and return the query results - * as an untyped java.util.stream.Stream. - * By default this method delegates to getResultList().stream(), - * however persistence provider may choose to override this method - * to provide additional capabilities. - * - * @return a stream of the results - * @throws IllegalStateException if called for a Jakarta - * Persistence query language UPDATE or DELETE statement - * @throws QueryTimeoutException if the query execution exceeds - * the query timeout value set and only the statement is - * rolled back - * @throws TransactionRequiredException if a lock mode other than - * NONE has been set and there is no transaction - * or the persistence context has not been joined to the transaction - * @throws PessimisticLockException if pessimistic locking - * fails and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking - * fails and only the statement is rolled back - * @throws PersistenceException if the query execution exceeds - * the query timeout value set and the transaction - * is rolled back - * @see Stream - * @see #getResultList() - * @since 2.2 - */ - default Stream getResultStream() { - return getResultList().stream(); - } - - /** - * Execute a SELECT query that returns a single untyped result. - * @return the result - * @throws NoResultException if there is no result - * @throws NonUniqueResultException if more than one result - * @throws IllegalStateException if called for a Jakarta - * Persistence query language UPDATE or DELETE statement - * @throws QueryTimeoutException if the query execution exceeds - * the query timeout value set and only the statement is - * rolled back - * @throws TransactionRequiredException if a lock mode other than - * NONE has been set and there is no transaction - * or the persistence context has not been joined to the transaction - * @throws PessimisticLockException if pessimistic locking - * fails and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking - * fails and only the statement is rolled back - * @throws PersistenceException if the query execution exceeds - * the query timeout value set and the transaction - * is rolled back - */ - Object getSingleResult(); - - /** - * Execute a SELECT query that returns a single untyped result. - * @return the result, or null if there is no result - * @throws NonUniqueResultException if more than one result - * @throws IllegalStateException if called for a Jakarta - * Persistence query language UPDATE or DELETE statement - * @throws QueryTimeoutException if the query execution exceeds - * the query timeout value set and only the statement is - * rolled back - * @throws TransactionRequiredException if a lock mode other than - * NONE has been set and there is no transaction - * or the persistence context has not been joined to the transaction - * @throws PessimisticLockException if pessimistic locking - * fails and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking - * fails and only the statement is rolled back - * @throws PersistenceException if the query execution exceeds - * the query timeout value set and the transaction - * is rolled back - */ - Object getSingleResultOrNull(); - - /** - * Execute an update or delete statement. - * @return the number of entities updated or deleted - * @throws IllegalStateException if called for a Jakarta - * Persistence query language SELECT statement or for - * a criteria query - * @throws TransactionRequiredException if there is - * no transaction or the persistence context has not - * been joined to the transaction - * @throws QueryTimeoutException if the statement execution - * exceeds the query timeout value set and only - * the statement is rolled back - * @throws PersistenceException if the query execution exceeds - * the query timeout value set and the transaction - * is rolled back - */ - int executeUpdate(); - - /** - * Set the maximum number of results to retrieve. - * @param maxResult maximum number of results to retrieve - * @return the same query instance - * @throws IllegalArgumentException if the argument is negative - */ - Query setMaxResults(int maxResult); - - /** - * The maximum number of results the query object was set to - * retrieve. Returns Integer.MAX_VALUE if setMaxResults was not - * applied to the query object. - * @return maximum number of results - * @since 2.0 - */ - int getMaxResults(); - - /** - * Set the position of the first result to retrieve. - * @param startPosition position of the first result, - * numbered from 0 - * @return the same query instance - * @throws IllegalArgumentException if the argument is negative - */ - Query setFirstResult(int startPosition); - - /** - * The position of the first result the query object was set to - * retrieve. Returns 0 if setFirstResult was not applied to the - * query object. - * @return position of the first result - * @since 2.0 - */ - int getFirstResult(); - - /** - * Set a query property or hint. The hints elements may be used - * to specify query properties and hints. Properties defined by - * this specification must be observed by the provider. - * Vendor-specific hints that are not recognized by a provider - * must be silently ignored. Portable applications should not - * rely on the standard timeout hint. Depending on the database - * in use and the locking mechanisms used by the provider, - * this hint may or may not be observed. - * @param hintName name of the property or hint - * @param value value for the property or hint - * @return the same query instance - * @throws IllegalArgumentException if the second argument is not - * valid for the implementation - */ - Query setHint(String hintName, Object value); - - /** - * Get the properties and hints and associated values that are - * in effect for the query instance. - * @return query properties and hints - * @since 2.0 - */ - Map getHints(); - - /** - * Bind the value of a Parameter object. - * @param param parameter object - * @param value parameter value - * @return the same query instance - * @throws IllegalArgumentException if the parameter - * does not correspond to a parameter of the - * query - * @since 2.0 - */ - Query setParameter(Parameter param, T value); - - /** - * Bind an instance of java.util.Calendar to a Parameter object. - * @param param parameter object - * @param value parameter value - * @param temporalType temporal type - * @return the same query instance - * @throws IllegalArgumentException if the parameter does not - * correspond to a parameter of the query - * @since 2.0 - * @deprecated Newly-written code should use the date/time types - * defined in {@link java.time}. - */ - @Deprecated(since = "3.2") - Query setParameter(Parameter param, Calendar value, - TemporalType temporalType); - - /** - * Bind an instance of java.util.Date to a Parameter object. - * @param param parameter object - * @param value parameter value - * @param temporalType temporal type - * @return the same query instance - * @throws IllegalArgumentException if the parameter does not - * correspond to a parameter of the query - * @since 2.0 - * @deprecated Newly-written code should use the date/time types - * defined in {@link java.time}. - */ - @Deprecated(since = "3.2") - Query setParameter(Parameter param, Date value, - TemporalType temporalType); - - /** - * Bind an argument value to a named parameter. - * @param name parameter name - * @param value parameter value - * @return the same query instance - * @throws IllegalArgumentException if the parameter name does - * not correspond to a parameter of the query or if - * the argument is of incorrect type - */ - Query setParameter(String name, Object value); - - /** - * Bind an instance of java.util.Calendar to a named parameter. - * @param name parameter name - * @param value parameter value - * @param temporalType temporal type - * @return the same query instance - * @throws IllegalArgumentException if the parameter name does - * not correspond to a parameter of the query or if - * the value argument is of incorrect type - * @deprecated Newly-written code should use the date/time types - * defined in {@link java.time}. - */ - @Deprecated(since = "3.2") - Query setParameter(String name, Calendar value, - TemporalType temporalType); - - /** - * Bind an instance of java.util.Date to a named parameter. - * @param name parameter name - * @param value parameter value - * @param temporalType temporal type - * @return the same query instance - * @throws IllegalArgumentException if the parameter name does - * not correspond to a parameter of the query or if - * the value argument is of incorrect type - * @deprecated Newly-written code should use the date/time types - * defined in {@link java.time}. - */ - @Deprecated(since = "3.2") - Query setParameter(String name, Date value, - TemporalType temporalType); - - /** - * Bind an argument value to a positional parameter. - * @param position position - * @param value parameter value - * @return the same query instance - * @throws IllegalArgumentException if position does not - * correspond to a positional parameter of the - * query or if the argument is of incorrect type - */ - Query setParameter(int position, Object value); - - /** - * Bind an instance of java.util.Calendar to a positional - * parameter. - * @param position position - * @param value parameter value - * @param temporalType temporal type - * @return the same query instance - * @throws IllegalArgumentException if position does not - * correspond to a positional parameter of the query or - * if the value argument is of incorrect type - * @deprecated Newly-written code should use the date/time types - * defined in {@link java.time}. - */ - @Deprecated(since = "3.2") - Query setParameter(int position, Calendar value, - TemporalType temporalType); - - /** - * Bind an instance of java.util.Date to a positional parameter. - * @param position position - * @param value parameter value - * @param temporalType temporal type - * @return the same query instance - * @throws IllegalArgumentException if position does not - * correspond to a positional parameter of the query or - * if the value argument is of incorrect type - * @deprecated Newly-written code should use the date/time types - * defined in {@link java.time}. - */ - @Deprecated(since = "3.2") - Query setParameter(int position, Date value, - TemporalType temporalType); - - /** - * Get the parameter objects corresponding to the declared - * parameters of the query. - * Returns empty set if the query has no parameters. - * This method is not required to be supported for native - * queries. - * @return set of the parameter objects - * @throws IllegalStateException if invoked on a native - * query when the implementation does not support - * this use - * @since 2.0 - */ - Set> getParameters(); - - /** - * Get the parameter object corresponding to the declared - * parameter of the given name. - * This method is not required to be supported for native - * queries. - * @param name parameter name - * @return parameter object - * @throws IllegalArgumentException if the parameter of the - * specified name does not exist - * @throws IllegalStateException if invoked on a native - * query when the implementation does not support - * this use - * @since 2.0 - */ - Parameter getParameter(String name); - - /** - * Get the parameter object corresponding to the declared - * parameter of the given name and type. - * This method is required to be supported for criteria queries - * only. - * @param name parameter name - * @param type type - * @return parameter object - * @throws IllegalArgumentException if the parameter of the - * specified name does not exist or is not assignable - * to the type - * @throws IllegalStateException if invoked on a native - * query or Jakarta Persistence query language query when - * the implementation does not support this use - * @since 2.0 - */ - Parameter getParameter(String name, Class type); - - /** - * Get the parameter object corresponding to the declared - * positional parameter with the given position. - * This method is not required to be supported for native - * queries. - * @param position position - * @return parameter object - * @throws IllegalArgumentException if the parameter with the - * specified position does not exist - * @throws IllegalStateException if invoked on a native - * query when the implementation does not support - * this use - * @since 2.0 - */ - Parameter getParameter(int position); - - /** - * Get the parameter object corresponding to the declared - * positional parameter with the given position and type. - * This method is not required to be supported by the provider. - * @param position position - * @param type type - * @return parameter object - * @throws IllegalArgumentException if the parameter with the - * specified position does not exist or is not assignable - * to the type - * @throws IllegalStateException if invoked on a native - * query or Jakarta Persistence query language query when - * the implementation does not support this use - * @since 2.0 - */ - Parameter getParameter(int position, Class type); - - /** - * Return a boolean indicating whether a value has been bound - * to the parameter. - * @param param parameter object - * @return boolean indicating whether parameter has been bound - * @since 2.0 - */ - boolean isBound(Parameter param); - - /** - * Return the input value bound to the parameter. - * (Note that OUT parameters are unbound.) - * @param param parameter object - * @return parameter value - * @throws IllegalArgumentException if the parameter is not - * a parameter of the query - * @throws IllegalStateException if the parameter has not been - * been bound - * @since 2.0 - */ - T getParameterValue(Parameter param); - - /** - * Return the input value bound to the named parameter. - * (Note that OUT parameters are unbound.) - * @param name parameter name - * @return parameter value - * @throws IllegalStateException if the parameter has not been - * been bound - * @throws IllegalArgumentException if the parameter of the - * specified name does not exist - * @since 2.0 - */ - Object getParameterValue(String name); - - /** - * Return the input value bound to the positional parameter. - * (Note that OUT parameters are unbound.) - * @param position position - * @return parameter value - * @throws IllegalStateException if the parameter has not been - * been bound - * @throws IllegalArgumentException if the parameter with the - * specified position does not exist - * @since 2.0 - */ - Object getParameterValue(int position); - - /** - * Set the flush mode type to be used for the query execution. - * The flush mode type applies to the query regardless of the - * flush mode type in use for the entity manager. - * @param flushMode flush mode - * @return the same query instance - */ - Query setFlushMode(FlushModeType flushMode); - - /** - * Get the flush mode in effect for the query execution. - * If a flush mode has not been set for the query object, - * returns the flush mode in effect for the entity manager. - * @return flush mode - * @since 2.0 - */ - FlushModeType getFlushMode(); - - /** - * Set the lock mode type to be used for the query execution. - * @param lockMode lock mode - * @return the same query instance - * @throws IllegalStateException if the query is found not to be - * a Jakarta Persistence query language SELECT query - * or a CriteriaQuery query - * @since 2.0 - */ - Query setLockMode(LockModeType lockMode); - - /** - * Get the current lock mode for the query. Returns null if a lock - * mode has not been set on the query object. - * @return lock mode - * @throws IllegalStateException if the query is found not to be - * a Jakarta Persistence query language SELECT query or - * a Criteria API query - * @since 2.0 - */ - LockModeType getLockMode(); - - /** - * Set the cache retrieval mode that is in effect during - * query execution. This cache retrieval mode overrides the - * cache retrieve mode in use by the entity manager. - * @param cacheRetrieveMode cache retrieval mode - * @return the same query instance - * @since 3.2 - */ - Query setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode); - - /** - * Set the cache storage mode that is in effect during - * query execution. This cache storage mode overrides the - * cache storage mode in use by the entity manager. - * @param cacheStoreMode cache storage mode - * @return the same query instance - * @since 3.2 - */ - Query setCacheStoreMode(CacheStoreMode cacheStoreMode); - - /** - * The cache retrieval mode that will be in effect during - * query execution. - * @since 3.2 - */ - CacheRetrieveMode getCacheRetrieveMode(); - - /** - * The cache storage mode that will be in effect during - * query execution. - * @since 3.2 - */ - CacheStoreMode getCacheStoreMode(); - - /** - * Set the query timeout, in milliseconds. This is a hint, - * and is an alternative to {@linkplain #setHint setting - * the hint} {@code jakarta.persistence.query.timeout}. - * @param timeout the timeout, in milliseconds, or null to - * indicate no timeout - * @return the same query instance - * @since 3.2 - */ - Query setTimeout(Integer timeout); - - /** - * The query timeout. - * @since 3.2 - */ - Integer getTimeout(); - - /** - * Return an object of the specified type to allow access to - * the provider-specific API. If the provider's query - * implementation does not support the specified class, the - * PersistenceException is thrown. - * @param cls the class of the object to be returned. This is - * normally either the underlying query - * implementation class or an interface that it - * implements. - * @return an instance of the specified class - * @throws PersistenceException if the provider does not support - * the call - * @since 2.0 - */ - T unwrap(Class cls); -} ----- - -==== TypedQuery Interface - -[source,java] ----- -package jakarta.persistence; - -import java.util.List; -import java.util.Date; -import java.util.Calendar; -import java.util.stream.Stream; - -/** - * Interface used to control the execution of typed queries. - * @param query result type - * - * @see Query - * @see Parameter - * - * @since 2.0 - */ -public interface TypedQuery extends Query { - - /** - * Execute a SELECT query and return the query results - * as a typed List. - * @return a list of the results - * @throws IllegalStateException if called for a Jakarta - * Persistence query language UPDATE or DELETE statement - * @throws QueryTimeoutException if the query execution exceeds - * the query timeout value set and only the statement is - * rolled back - * @throws TransactionRequiredException if a lock mode other than - * NONE has been set and there is no transaction - * or the persistence context has not been joined to the - * transaction - * @throws PessimisticLockException if pessimistic locking - * fails and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking - * fails and only the statement is rolled back - * @throws PersistenceException if the query execution exceeds - * the query timeout value set and the transaction - * is rolled back - */ - List getResultList(); - - /** - * Execute a SELECT query and return the query results - * as a typed java.util.stream.Stream. - * By default this method delegates to getResultList().stream(), - * however persistence provider may choose to override this method - * to provide additional capabilities. - * - * @return a stream of the results - * @throws IllegalStateException if called for a Jakarta - * Persistence query language UPDATE or DELETE statement - * @throws QueryTimeoutException if the query execution exceeds - * the query timeout value set and only the statement is - * rolled back - * @throws TransactionRequiredException if a lock mode other than - * NONE has been set and there is no transaction - * or the persistence context has not been joined to the transaction - * @throws PessimisticLockException if pessimistic locking - * fails and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking - * fails and only the statement is rolled back - * @throws PersistenceException if the query execution exceeds - * the query timeout value set and the transaction - * is rolled back - * @see Stream - * @see #getResultList() - * @since 2.2 - */ - default Stream getResultStream() { - return getResultList().stream(); - } - - /** - * Execute a SELECT query that returns a single result. - * @return the result - * @throws NoResultException if there is no result - * @throws NonUniqueResultException if more than one result - * @throws IllegalStateException if called for a Jakarta - * Persistence query language UPDATE or DELETE statement - * @throws QueryTimeoutException if the query execution exceeds - * the query timeout value set and only the statement is - * rolled back - * @throws TransactionRequiredException if a lock mode other than - * NONE has been set and there is no transaction - * or the persistence context has not been joined to the - * transaction - * @throws PessimisticLockException if pessimistic locking - * fails and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking - * fails and only the statement is rolled back - * @throws PersistenceException if the query execution exceeds - * the query timeout value set and the transaction - * is rolled back - */ - X getSingleResult(); - - /** - * Execute a SELECT query that returns a single untyped result. - * @return the result, or null if there is no result - * @throws NonUniqueResultException if more than one result - * @throws IllegalStateException if called for a Jakarta - * Persistence query language UPDATE or DELETE statement - * @throws QueryTimeoutException if the query execution exceeds - * the query timeout value set and only the statement is - * rolled back - * @throws TransactionRequiredException if a lock mode other than - * NONE has been set and there is no transaction - * or the persistence context has not been joined to the transaction - * @throws PessimisticLockException if pessimistic locking - * fails and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking - * fails and only the statement is rolled back - * @throws PersistenceException if the query execution exceeds - * the query timeout value set and the transaction - * is rolled back - */ - X getSingleResultOrNull(); - - /** - * Set the maximum number of results to retrieve. - * @param maxResult maximum number of results to retrieve - * @return the same query instance - * @throws IllegalArgumentException if the argument is negative - */ - TypedQuery setMaxResults(int maxResult); - - /** - * Set the position of the first result to retrieve. - * @param startPosition position of the first result, - * numbered from 0 - * @return the same query instance - * @throws IllegalArgumentException if the argument is negative - */ - TypedQuery setFirstResult(int startPosition); - - /** - * Set a query property or hint. The hints elements may be used - * to specify query properties and hints. Properties defined by - * this specification must be observed by the provider. - * Vendor-specific hints that are not recognized by a provider - * must be silently ignored. Portable applications should not - * rely on the standard timeout hint. Depending on the database - * in use and the locking mechanisms used by the provider, - * this hint may or may not be observed. - * @param hintName name of property or hint - * @param value value for the property or hint - * @return the same query instance - * @throws IllegalArgumentException if the second argument is not - * valid for the implementation - */ - TypedQuery setHint(String hintName, Object value); - - /** - * Bind the value of a Parameter object. - * @param param parameter object - * @param value parameter value - * @return the same query instance - * @throws IllegalArgumentException if the parameter - * does not correspond to a parameter of the - * query - */ - TypedQuery setParameter(Parameter param, T value); - - /** - * Bind an instance of java.util.Calendar to a Parameter object. - * @param param parameter object - * @param value parameter value - * @param temporalType temporal type - * @return the same query instance - * @throws IllegalArgumentException if the parameter does not - * correspond to a parameter of the query - * @deprecated Newly-written code should use the date/time types - * defined in {@link java.time}. - */ - @Deprecated(since = "3.2") - TypedQuery setParameter(Parameter param, - Calendar value, - TemporalType temporalType); - - /** - * Bind an instance of java.util.Date to a Parameter object. - * @param param parameter object - * @param value parameter value - * @param temporalType temporal type - * @return the same query instance - * @throws IllegalArgumentException if the parameter does not - * correspond to a parameter of the query - * @deprecated Newly-written code should use the date/time types - * defined in {@link java.time}. - */ - @Deprecated(since = "3.2") - TypedQuery setParameter(Parameter param, Date value, - TemporalType temporalType); - - /** - * Bind an argument value to a named parameter. - * @param name parameter name - * @param value parameter value - * @return the same query instance - * @throws IllegalArgumentException if the parameter name does - * not correspond to a parameter of the query or if - * the argument is of incorrect type - */ - TypedQuery setParameter(String name, Object value); - - /** - * Bind an instance of java.util.Calendar to a named parameter. - * @param name parameter name - * @param value parameter value - * @param temporalType temporal type - * @return the same query instance - * @throws IllegalArgumentException if the parameter name does - * not correspond to a parameter of the query or if - * the value argument is of incorrect type - * @deprecated Newly-written code should use the date/time types - * defined in {@link java.time}. - */ - @Deprecated(since = "3.2") - TypedQuery setParameter(String name, Calendar value, - TemporalType temporalType); - - /** - * Bind an instance of java.util.Date to a named parameter. - * @param name parameter name - * @param value parameter value - * @param temporalType temporal type - * @return the same query instance - * @throws IllegalArgumentException if the parameter name does - * not correspond to a parameter of the query or if - * the value argument is of incorrect type - * @deprecated Newly-written code should use the date/time types - * defined in {@link java.time}. - */ - @Deprecated(since = "3.2") - TypedQuery setParameter(String name, Date value, - TemporalType temporalType); - - /** - * Bind an argument value to a positional parameter. - * @param position position - * @param value parameter value - * @return the same query instance - * @throws IllegalArgumentException if position does not - * correspond to a positional parameter of the - * query or if the argument is of incorrect type - */ - TypedQuery setParameter(int position, Object value); - - /** - * Bind an instance of java.util.Calendar to a positional - * parameter. - * @param position position - * @param value parameter value - * @param temporalType temporal type - * @return the same query instance - * @throws IllegalArgumentException if position does not - * correspond to a positional parameter of the query - * or if the value argument is of incorrect type - * @deprecated Newly-written code should use the date/time types - * defined in {@link java.time}. - */ - @Deprecated(since = "3.2") - TypedQuery setParameter(int position, Calendar value, - TemporalType temporalType); - - /** - * Bind an instance of java.util.Date to a positional parameter. - * @param position position - * @param value parameter value - * @param temporalType temporal type - * @return the same query instance - * @throws IllegalArgumentException if position does not - * correspond to a positional parameter of the query - * or if the value argument is of incorrect type - * @deprecated Newly-written code should use the date/time types - * defined in {@link java.time}. - */ - @Deprecated(since = "3.2") - TypedQuery setParameter(int position, Date value, - TemporalType temporalType); - - /** - * Set the flush mode type to be used for the query execution. - * The flush mode type applies to the query regardless of the - * flush mode type in use for the entity manager. - * @param flushMode flush mode - * @return the same query instance - */ - TypedQuery setFlushMode(FlushModeType flushMode); - - /** - * Set the lock mode type to be used for the query execution. - * @param lockMode lock mode - * @return the same query instance - * @throws IllegalStateException if the query is found not to - * be a Jakarta Persistence query language SELECT query - * or a CriteriaQuery query - */ - TypedQuery setLockMode(LockModeType lockMode); - - /** - * Set the cache retrieval mode that is in effect during - * query execution. This cache retrieval mode overrides the - * cache retrieve mode in use by the entity manager. - * @param cacheRetrieveMode cache retrieval mode - * @return the same query instance - * @since 3.2 - */ - TypedQuery setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode); - - /** - * Set the cache storage mode that is in effect during - * query execution. This cache storage mode overrides the - * cache storage mode in use by the entity manager. - * @param cacheStoreMode cache storage mode - * @return the same query instance - * @since 3.2 - */ - TypedQuery setCacheStoreMode(CacheStoreMode cacheStoreMode); - - /** - * Set the query timeout, in milliseconds. This is a hint, - * and is an alternative to {@linkplain #setHint setting - * the hint} {@code jakarta.persistence.query.timeout}. - * @param timeout the timeout, in milliseconds, or null to - * indicate no timeout - * @return the same query instance - * @since 3.2 - */ - TypedQuery setTimeout(Integer timeout); -} ----- - -==== Tuple Interface [[a3868]] - -[source,java] ----- -package jakarta.persistence; - -import java.util.List; - -/** - * Interface for extracting the elements of a query result tuple. - * - * @see TupleElement - * - * @since 2.0 - */ -public interface Tuple { - - /** - * Get the value of the specified tuple element. - * @param tupleElement tuple element - * @return value of tuple element - * @throws IllegalArgumentException if tuple element - * does not correspond to an element in the - * query result tuple - */ - X get(TupleElement tupleElement); - - /** - * Get the value of the tuple element to which the - * specified alias has been assigned. - * @param alias alias assigned to tuple element - * @param type of the tuple element - * @return value of the tuple element - * @throws IllegalArgumentException if alias - * does not correspond to an element in the - * query result tuple or element cannot be - * assigned to the specified type - */ - X get(String alias, Class type); - - /** - * Get the value of the tuple element to which the - * specified alias has been assigned. - * @param alias alias assigned to tuple element - * @return value of the tuple element - * @throws IllegalArgumentException if alias - * does not correspond to an element in the - * query result tuple - */ - Object get(String alias); - - /** - * Get the value of the element at the specified - * position in the result tuple. The first position is 0. - * @param i position in result tuple - * @param type type of the tuple element - * @return value of the tuple element - * @throws IllegalArgumentException if i exceeds - * length of result tuple or element cannot be - * assigned to the specified type - */ - X get(int i, Class type); - - /** - * Get the value of the element at the specified - * position in the result tuple. The first position is 0. - * @param i position in result tuple - * @return value of the tuple element - * @throws IllegalArgumentException if i exceeds - * length of result tuple - */ - Object get(int i); - - /** - * Return the values of the result tuple elements as an array. - * @return tuple element values - */ - Object[] toArray(); - - /** - * Return the tuple elements. - * @return tuple elements - */ - List> getElements(); -} ----- - -==== TupleElement Interface [[a3949]] - -[source,java] ----- -package jakarta.persistence; - -/** - * The TupleElement interface defines an element that is returned in - * a query result tuple. - * @param the type of the element - * - * @see Tuple - * - * @since 2.0 - */ -public interface TupleElement { - - /** - * Return the Java type of the tuple element. - * @return the Java type of the tuple element - */ - Class getJavaType(); - - /** - * Return the alias assigned to the tuple element or null, - * if no alias has been assigned. - * @return alias - */ - String getAlias(); -} ----- - -==== Parameter Interface - -[source,java] ----- -package jakarta.persistence; - -/** - * Type for query parameter objects. - * @param the type of the parameter - * - * @see Query - * @see TypedQuery - * - * @since 2.0 - */ -public interface Parameter { - - /** - * Return the parameter name, or null if the parameter is - * not a named parameter or no name has been assigned. - * @return parameter name - */ - String getName(); - - /** - * Return the parameter position, or null if the parameter - * is not a positional parameter. - * @return position of parameter - */ - Integer getPosition(); - - /** - * Return the Java type of the parameter. Values bound to the - * parameter must be assignable to this type. - * This method is required to be supported for criteria queries - * only. Applications that use this method for Jakarta - * Persistence query language queries and native queries will - * not be portable. - * @return the Java type of the parameter - * @throws IllegalStateException if invoked on a parameter - * obtained from a query language - * query or native query when the implementation does - * not support this use - */ - Class getParameterType(); -} ----- - -==== StoredProcedureQuery Interface - -[source,java] ----- -package jakarta.persistence; - -import java.util.Calendar; -import java.util.Date; -import java.util.List; - -/** - * Interface used to control stored procedure query execution. - * - *

- * Stored procedure query execution may be controlled in accordance with - * the following: - *

    - *
  • The setParameter methods are used to set the values of - * all required IN and INOUT parameters. - * It is not required to set the values of stored procedure parameters - * for which default values have been defined by the stored procedure.
    • - *
  • - * When getResultList and getSingleResult are - * called on a StoredProcedureQuery object, the provider - * will call execute on an unexecuted stored procedure - * query before processing getResultList or - * getSingleResult.
    • - *
  • - * When executeUpdate is called on a - * StoredProcedureQuery object, the provider will call - * execute on an unexecuted stored procedure query - * followed by getUpdateCount. The results of - * executeUpdate will be those of getUpdateCount.
    • - *
  • - * The execute method supports both the simple case where - * scalar results are passed back only via INOUT and - * OUT parameters as well as the most general case - * (multiple result sets and/or update counts, possibly also in - * combination with output parameter values).
    • - *
  • - * The execute method returns true if the first result is a - * result set, and false if it is an update count or there are no results - * other than through INOUT and OUT parameters, - * if any.
    • - *
  • - * If the execute method returns true, the pending result set - * can be obtained by calling getResultList or - * getSingleResult.
    • - *
  • - * The hasMoreResults method can then be used to test - * for further results.
    • - *
  • - * If execute or hasMoreResults returns false, - * the getUpdateCount method can be called to obtain the - * pending result if it is an update count. The getUpdateCount - * method will return either the update count (zero or greater) or -1 - * if there is no update count (i.e., either the next result is a result set - * or there is no next update count).
    • - *
  • - * For portability, results that correspond to JDBC result sets and - * update counts need to be processed before the values of any - * INOUT or OUT parameters are extracted.
    • - *
  • - * After results returned through getResultList and - * getUpdateCount have been exhausted, results returned through - * INOUT and OUT parameters can be retrieved.
    • - *
  • - * The getOutputParameterValue methods are used to retrieve - * the values passed back from the procedure through INOUT - * and OUT parameters.
    • - *
  • - * When using REF_CURSOR parameters for result sets the - * update counts should be exhausted before calling getResultList - * to retrieve the result set. Alternatively, the REF_CURSOR - * result set can be retrieved through getOutputParameterValue. - * Result set mappings will be applied to results corresponding to - * REF_CURSOR parameters in the order the REF_CURSOR - * parameters were registered with the query.
    • - *
  • - * In the simplest case, where results are returned only via - * INOUT and OUT parameters, execute - * can be followed immediately by calls to - * getOutputParameterValue.
    • - *
- * - * @see Query - * @see Parameter - * - * @since 2.1 - */ -public interface StoredProcedureQuery extends Query { - - /** - * Set a query property or hint. The hints elements may be used - * to specify query properties and hints. Properties defined by - * this specification must be observed by the provider. - * Vendor-specific hints that are not recognized by a provider - * must be silently ignored. Portable applications should not - * rely on the standard timeout hint. Depending on the database - * in use, this hint may or may not be observed. - * @param hintName name of the property or hint - * @param value value for the property or hint - * @return the same query instance - * @throws IllegalArgumentException if the second argument is not - * valid for the implementation - */ - StoredProcedureQuery setHint(String hintName, Object value); - - /** - * Bind the value of a Parameter object. - * @param param parameter object - * @param value parameter value - * @return the same query instance - * @throws IllegalArgumentException if the parameter does not - * correspond to a parameter of the query - */ - StoredProcedureQuery setParameter(Parameter param, - T value); - - /** - * Bind an instance of java.util.Calendar to a Parameter object. - * @param param parameter object - * @param value parameter value - * @param temporalType temporal type - * @return the same query instance - * @throws IllegalArgumentException if the parameter does not - * correspond to a parameter of the query - * @deprecated Newly-written code should use the date/time types - * defined in {@link java.time}. - */ - @Deprecated(since = "3.2") - StoredProcedureQuery setParameter(Parameter param, - Calendar value, - TemporalType temporalType); - - /** - * Bind an instance of java.util.Date to a Parameter object. - * @param param parameter object - * @param value parameter value - * @param temporalType temporal type - * @return the same query instance - * @throws IllegalArgumentException if the parameter does not - * correspond to a parameter of the query - * @deprecated Newly-written code should use the date/time types - * defined in {@link java.time}. - */ - @Deprecated(since = "3.2") - StoredProcedureQuery setParameter(Parameter param, - Date value, - TemporalType temporalType); - - /** - * Bind an argument value to a named parameter. - * @param name parameter name - * @param value parameter value - * @return the same query instance - * @throws IllegalArgumentException if the parameter name does - * not correspond to a parameter of the query or if the - * argument is of incorrect type - */ - StoredProcedureQuery setParameter(String name, Object value); - - /** - * Bind an instance of java.util.Calendar to a named parameter. - * @param name parameter name - * @param value parameter value - * @param temporalType temporal type - * @return the same query instance - * @throws IllegalArgumentException if the parameter name does - * not correspond to a parameter of the query or if the - * value argument is of incorrect type - * @deprecated Newly-written code should use the date/time types - * defined in {@link java.time}. - */ - @Deprecated(since = "3.2") - StoredProcedureQuery setParameter(String name, - Calendar value, - TemporalType temporalType); - - /** - * Bind an instance of java.util.Date to a named parameter. - * @param name parameter name - * @param value parameter value - * @param temporalType temporal type - * @return the same query instance - * @throws IllegalArgumentException if the parameter name does - * not correspond to a parameter of the query or if the - * value argument is of incorrect type - * @deprecated Newly-written code should use the date/time types - * defined in {@link java.time}. - */ - @Deprecated(since = "3.2") - StoredProcedureQuery setParameter(String name, - Date value, - TemporalType temporalType); - - /** - * Bind an argument value to a positional parameter. - * @param position position - * @param value parameter value - * @return the same query instance - * @throws IllegalArgumentException if position does not - * correspond to a positional parameter of the query - * or if the argument is of incorrect type - */ - StoredProcedureQuery setParameter(int position, Object value); - - /** - * Bind an instance of java.util.Calendar to a positional - * parameter. - * @param position position - * @param value parameter value - * @param temporalType temporal type - * @return the same query instance - * @throws IllegalArgumentException if position does not - * correspond to a positional parameter of the query or - * if the value argument is of incorrect type - * @deprecated Newly-written code should use the date/time types - * defined in {@link java.time}. - */ - @Deprecated(since = "3.2") - StoredProcedureQuery setParameter(int position, - Calendar value, - TemporalType temporalType); - - /** - * Bind an instance of java.util.Date to a positional parameter. - * @param position position - * @param value parameter value - * @param temporalType temporal type - * @return the same query instance - * @throws IllegalArgumentException if position does not - * correspond to a positional parameter of the query or - * if the value argument is of incorrect type - * @deprecated Newly-written code should use the date/time types - * defined in {@link java.time}. - */ - @Deprecated(since = "3.2") - StoredProcedureQuery setParameter(int position, - Date value, - TemporalType temporalType); - - /** - * Set the flush mode type to be used for the query execution. - * The flush mode type applies to the query regardless of the - * flush mode type in use for the entity manager. - * @param flushMode flush mode - * @return the same query instance - */ - StoredProcedureQuery setFlushMode(FlushModeType flushMode); - - /** - * Set the cache retrieval mode that is in effect during - * query execution. This cache retrieval mode overrides the - * cache retrieve mode in use by the entity manager. - * @param cacheRetrieveMode cache retrieval mode - * @return the same query instance - * @since 3.2 - */ - StoredProcedureQuery setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode); - - /** - * Set the cache storage mode that is in effect during - * query execution. This cache storage mode overrides the - * cache storage mode in use by the entity manager. - * @param cacheStoreMode cache storage mode - * @return the same query instance - * @since 3.2 - */ - StoredProcedureQuery setCacheStoreMode(CacheStoreMode cacheStoreMode); - - /** - * Set the query timeout, in milliseconds. This is a hint, - * and is an alternative to {@linkplain #setHint setting - * the hint} {@code jakarta.persistence.query.timeout}. - * @param timeout the timeout, in milliseconds, or null to - * indicate no timeout - * @return the same query instance - * @since 3.2 - */ - StoredProcedureQuery setTimeout(Integer timeout); - - /** - * Register a positional parameter. - * All parameters must be registered. - * @param position parameter position - * @param type type of the parameter - * @param mode parameter mode - * @return the same query instance - */ - StoredProcedureQuery registerStoredProcedureParameter( - int position, - Class type, - ParameterMode mode); - - /** - * Register a named parameter. - * @param parameterName name of the parameter as registered or - * specified in metadata - * @param type type of the parameter - * @param mode parameter mode - * @return the same query instance - */ - StoredProcedureQuery registerStoredProcedureParameter( - String parameterName, - Class type, - ParameterMode mode); - - /** - * Retrieve a value passed back from the procedure - * through an INOUT or OUT parameter. - * For portability, all results corresponding to result sets - * and update counts must be retrieved before the values of - * output parameters. - * @param position parameter position - * @return the result that is passed back through the parameter - * @throws IllegalArgumentException if the position does - * not correspond to a parameter of the query or is - * not an INOUT or OUT parameter - */ - Object getOutputParameterValue(int position); - - /** - * Retrieve a value passed back from the procedure - * through an INOUT or OUT parameter. - * For portability, all results corresponding to result sets - * and update counts must be retrieved before the values of - * output parameters. - * @param parameterName name of the parameter as registered or - * specified in metadata - * @return the result that is passed back through the parameter - * @throws IllegalArgumentException if the parameter name does - * not correspond to a parameter of the query or is - * not an INOUT or OUT parameter - */ - Object getOutputParameterValue(String parameterName); - - /** - * Return true if the first result corresponds to a result set, - * and false if it is an update count or if there are no results - * other than through INOUT and OUT parameters, if any. - * @return true if first result corresponds to result set - * @throws QueryTimeoutException if the query execution exceeds - * the query timeout value set and only the statement is - * rolled back - * @throws PersistenceException if the query execution exceeds - * the query timeout value set and the transaction - * is rolled back - */ - boolean execute(); - - /** - * Return the update count of -1 if there is no pending result or - * if the first result is not an update count. The provider will - * call execute on the query if needed. - * @return the update count or -1 if there is no pending result - * or if the next result is not an update count. - * @throws TransactionRequiredException if there is - * no transaction or the persistence context has not - * been joined to the transaction - * @throws QueryTimeoutException if the statement execution - * exceeds the query timeout value set and only - * the statement is rolled back - * @throws PersistenceException if the query execution exceeds - * the query timeout value set and the transaction - * is rolled back - */ - int executeUpdate(); - - /** - * Retrieve the list of results from the next result set. - * The provider will call execute on the query - * if needed. - * A REF_CURSOR result set, if any, will be retrieved - * in the order the REF_CURSOR parameter was - * registered with the query. - * @return a list of the results or null is the next item is not - * a result set - * @throws QueryTimeoutException if the query execution exceeds - * the query timeout value set and only the statement is - * rolled back - * @throws PersistenceException if the query execution exceeds - * the query timeout value set and the transaction - * is rolled back - */ - List getResultList(); - - /** - * Retrieve a single result from the next result set. - * The provider will call execute on the query - * if needed. - * A REF_CURSOR result set, if any, will be retrieved - * in the order the REF_CURSOR parameter was - * registered with the query. - * @return the result or null if the next item is not a result set - * @throws NoResultException if there is no result in the next - * result set - * @throws NonUniqueResultException if more than one result - * @throws QueryTimeoutException if the query execution exceeds - * the query timeout value set and only the statement is - * rolled back - * @throws PersistenceException if the query execution exceeds - * the query timeout value set and the transaction - * is rolled back - */ - Object getSingleResult(); - - /** - * Retrieve a single result from the next result set. - * The provider will call execute on the query - * if needed. - * A REF_CURSOR result set, if any, will be retrieved - * in the order the REF_CURSOR parameter was - * registered with the query. - * @return the result or null if the next item is not a result set - * or if there is no result in the next result set - * @throws NonUniqueResultException if more than one result - * @throws QueryTimeoutException if the query execution exceeds - * the query timeout value set and only the statement is - * rolled back - * @throws PersistenceException if the query execution exceeds - * the query timeout value set and the transaction - * is rolled back - */ - Object getSingleResultOrNull(); - - /** - * Return true if the next result corresponds to a result set, - * and false if it is an update count or if there are no results - * other than through INOUT and OUT parameters, if any. - * @return true if next result corresponds to result set - * @throws QueryTimeoutException if the query execution exceeds - * the query timeout value set and only the statement is - * rolled back - * @throws PersistenceException if the query execution exceeds - * the query timeout value set and the transaction - * is rolled back - */ - boolean hasMoreResults(); - - /** - * Return the update count or -1 if there is no pending result - * or if the next result is not an update count. - * @return update count or -1 if there is no pending result or if - * the next result is not an update count - * @throws QueryTimeoutException if the query execution exceeds - * the query timeout value set and only the statement is - * rolled back - * @throws PersistenceException if the query execution exceeds - * the query timeout value set and the transaction - * is rolled back - */ - int getUpdateCount(); - -} ----- +These interfaces may be found in <>. ==== Query Execution @@ -6030,23 +2636,10 @@ flush to the database regardless of the flush mode setting. [source,java] ---- -package jakarta.persistence; - -public enum FlushModeType { - - /** - * Flushing to occur at transaction commit. The provider may flush - * at other times, but is not required to. - */ - COMMIT, - - /** - * (Default) Flushing to occur at query execution. - */ - AUTO -} +include::../../../../api/src/main/java/jakarta/persistence/FlushModeType.java[lines=18..-1] ---- + If there is no transaction active, the persistence provider must not flush to the database. diff --git a/spec/src/main/asciidoc/ch05-metamodel-api.adoc b/spec/src/main/asciidoc/ch05-metamodel-api.adoc index be94a976..b2642340 100644 --- a/spec/src/main/asciidoc/ch05-metamodel-api.adoc +++ b/spec/src/main/asciidoc/ch05-metamodel-api.adoc @@ -254,1014 +254,13 @@ Persistence providers may, but are not required to, support the use of non-canonical metamodel classes. -=== Metamodel API Interfaces +=== Runtime Access to Metamodel -The `jakarta.persistence.metamodel` interfaces -provide for dynamically accessing the metamodel of the persistent -state and relationships of the managed classes of a persistence unit. +The interfaces defined in `jakarta.persistence.metamodel` provide for +dynamic access to a metamodel of the persistent state and relationships +of the managed classes of a persistence unit. -The metamodel can be accessed through the -`EntityManagerFactory` or `EntityManager.getMetamodel` methods. +An instance of `Metamodel` may be obtained by calling the `getMetamodel()` +method of `EntityManagerFactory` or `EntityManager`. -The metamodel API may be extended to cover -object/relational mapping information in a future release of this -specification. - - -==== Metamodel Interface - -[source,java] ----- -package jakarta.persistence.metamodel; - -import java.util.Set; - -/** - * Provides access to the metamodel of persistent - * entities in the persistence unit. - * - * @since 2.0 - */ -public interface Metamodel { - - /** - * Return the metamodel entity type representing the entity. - * @param entityName the name of the represented entity - * @return the metamodel entity type - * @throws IllegalArgumentException if not an entity - * @see jakarta.persistence.Entity#name - * @since 3.2 - */ - EntityType entity(String entityName); - - /** - * Return the metamodel entity type representing the entity. - * @param cls the type of the represented entity - * @return the metamodel entity type - * @throws IllegalArgumentException if not an entity - */ - EntityType entity(Class cls); - - /** - * Return the metamodel managed type representing the - * entity, mapped superclass, or embeddable class. - * @param cls the type of the represented managed class - * @return the metamodel managed type - * @throws IllegalArgumentException if not a managed class - */ - ManagedType managedType(Class cls); - - /** - * Return the metamodel embeddable type representing the - * embeddable class. - * @param cls the type of the represented embeddable class - * @return the metamodel embeddable type - * @throws IllegalArgumentException if not an embeddable class - */ - EmbeddableType embeddable(Class cls); - - /** - * Return the metamodel managed types. - * @return the metamodel managed types - */ - Set> getManagedTypes(); - - /** - * Return the metamodel entity types. - * @return the metamodel entity types - */ - Set> getEntities(); - - /** - * Return the metamodel embeddable types. Returns empty set - * if there are no embeddable types. - * @return the metamodel embeddable types - */ - Set> getEmbeddables(); -} ----- - -==== Type Interface - -[source,java] ----- -package jakarta.persistence.metamodel; - -/** - * Instances of the type Type represent persistent object - * or attribute types. - * - * @param The type of the represented object or attribute - * - * @since 2.0 - */ -public interface Type { - - public static enum PersistenceType { - - /** Entity */ - ENTITY, - - /** Embeddable class */ - EMBEDDABLE, - - /** Mapped superclass */ - MAPPED_SUPERCLASS, - - /** Basic type */ - BASIC - } - - /** - * Return the persistence type. - * @return persistence type - */ - PersistenceType getPersistenceType(); - - /** - * Return the represented Java type. - * @return Java type - */ - Class getJavaType(); -} ----- - -==== ManagedType Interface - -[source,java] ----- -package jakarta.persistence.metamodel; - -import java.util.Set; - -/** - * Instances of the type ManagedType represent entity, mapped - * superclass, and embeddable types. - * - * @param The represented type. - * - * @since 2.0 - * - */ -public interface ManagedType extends Type { - - /** - * Return the attributes of the managed type. - * @return attributes of the managed type - */ - Set> getAttributes(); - - /** - * Return the attributes declared by the managed type. - * Returns empty set if the managed type has no declared - * attributes. - * @return declared attributes of the managed type - */ - Set> getDeclaredAttributes(); - - /** - * Return the single-valued attribute of the managed - * type that corresponds to the specified name and Java type. - * @param name the name of the represented attribute - * @param type the type of the represented attribute - * @return single-valued attribute with given name and type - * @throws IllegalArgumentException if attribute of the given - * name and type is not present in the managed type - */ - SingularAttribute getSingularAttribute(String name, Class type); - - /** - * Return the single-valued attribute declared by the - * managed type that corresponds to the specified name and - * Java type. - * @param name the name of the represented attribute - * @param type the type of the represented attribute - * @return declared single-valued attribute of the given - * name and type - * @throws IllegalArgumentException if attribute of the given - * name and type is not declared in the managed type - */ - SingularAttribute getDeclaredSingularAttribute(String name, Class type); - - /** - * Return the single-valued attributes of the managed type. - * Returns empty set if the managed type has no single-valued - * attributes. - * @return single-valued attributes - */ - Set> getSingularAttributes(); - - /** - * Return the single-valued attributes declared by the managed - * type. - * Returns empty set if the managed type has no declared - * single-valued attributes. - * @return declared single-valued attributes - */ - Set> getDeclaredSingularAttributes(); - - /** - * Return the Collection-valued attribute of the managed type - * that corresponds to the specified name and Java element type. - * @param name the name of the represented attribute - * @param elementType the element type of the represented - * attribute - * @return CollectionAttribute of the given name and element - * type - * @throws IllegalArgumentException if attribute of the given - * name and type is not present in the managed type - */ - CollectionAttribute getCollection(String name, Class elementType); - - /** - * Return the Collection-valued attribute declared by the - * managed type that corresponds to the specified name and Java - * element type. - * @param name the name of the represented attribute - * @param elementType the element type of the represented - * attribute - * @return declared CollectionAttribute of the given name and - * element type - * @throws IllegalArgumentException if attribute of the given - * name and type is not declared in the managed type - */ - CollectionAttribute getDeclaredCollection(String name, Class elementType); - - /** - * Return the Set-valued attribute of the managed type that - * corresponds to the specified name and Java element type. - * @param name the name of the represented attribute - * @param elementType the element type of the represented - * attribute - * @return SetAttribute of the given name and element type - * @throws IllegalArgumentException if attribute of the given - * name and type is not present in the managed type - */ - SetAttribute getSet(String name, Class elementType); - - /** - * Return the Set-valued attribute declared by the managed type - * that corresponds to the specified name and Java element type. - * @param name the name of the represented attribute - * @param elementType the element type of the represented - * attribute - * @return declared SetAttribute of the given name and - * element type - * @throws IllegalArgumentException if attribute of the given - * name and type is not declared in the managed type - */ - SetAttribute getDeclaredSet(String name, Class elementType); - - /** - * Return the List-valued attribute of the managed type that - * corresponds to the specified name and Java element type. - * @param name the name of the represented attribute - * @param elementType the element type of the represented - * attribute - * @return ListAttribute of the given name and element type - * @throws IllegalArgumentException if attribute of the given - * name and type is not present in the managed type - */ - ListAttribute getList(String name, Class elementType); - - /** - * Return the List-valued attribute declared by the managed - * type that corresponds to the specified name and Java - * element type. - * @param name the name of the represented attribute - * @param elementType the element type of the represented - * attribute - * @return declared ListAttribute of the given name and - * element type - * @throws IllegalArgumentException if attribute of the given - * name and type is not declared in the managed type - */ - ListAttribute getDeclaredList(String name, Class elementType); - - /** - * Return the Map-valued attribute of the managed type that - * corresponds to the specified name and Java key and value - * types. - * @param name the name of the represented attribute - * @param keyType the key type of the represented attribute - * @param valueType the value type of the represented attribute - * @return MapAttribute of the given name and key and value - * types - * @throws IllegalArgumentException if attribute of the given - * name and type is not present in the managed type - */ - MapAttribute getMap(String name, - Class keyType, - Class valueType); - - /** - * Return the Map-valued attribute declared by the managed - * type that corresponds to the specified name and Java key - * and value types. - * @param name the name of the represented attribute - * @param keyType the key type of the represented attribute - * @param valueType the value type of the represented attribute - * @return declared MapAttribute of the given name and key - * and value types - * @throws IllegalArgumentException if attribute of the given - * name and type is not declared in the managed type - */ - MapAttribute getDeclaredMap(String name, - Class keyType, - Class valueType); - - /** - * Return all multi-valued attributes (Collection-, Set-, - * List-, and Map-valued attributes) of the managed type. - * Returns empty set if the managed type has no multi-valued - * attributes. - * @return Collection-, Set-, List-, and Map-valued attributes - */ - Set> getPluralAttributes(); - - /** - * Return all multi-valued attributes (Collection-, Set-, - * List-, and Map-valued attributes) declared by the - * managed type. - * Returns empty set if the managed type has no declared - * multi-valued attributes. - * @return declared Collection-, Set-, List-, and Map-valued - * attributes - */ - Set> getDeclaredPluralAttributes(); - - -//String-based: - - /** - * Return the attribute of the managed - * type that corresponds to the specified name. - * @param name the name of the represented attribute - * @return attribute with given name - * @throws IllegalArgumentException if attribute of the given - * name is not present in the managed type - */ - Attribute getAttribute(String name); - - /** - * Return the attribute declared by the managed - * type that corresponds to the specified name. - * @param name the name of the represented attribute - * @return attribute with given name - * @throws IllegalArgumentException if attribute of the given - * name is not declared in the managed type - */ - Attribute getDeclaredAttribute(String name); - - /** - * Return the single-valued attribute of the managed type that - * corresponds to the specified name. - * @param name the name of the represented attribute - * @return single-valued attribute with the given name - * @throws IllegalArgumentException if attribute of the given - * name is not present in the managed type - */ - SingularAttribute getSingularAttribute(String name); - - /** - * Return the single-valued attribute declared by the managed - * type that corresponds to the specified name. - * @param name the name of the represented attribute - * @return declared single-valued attribute of the given - * name - * @throws IllegalArgumentException if attribute of the given - * name is not declared in the managed type - */ - SingularAttribute getDeclaredSingularAttribute(String name); - - /** - * Return the Collection-valued attribute of the managed type - * that corresponds to the specified name. - * @param name the name of the represented attribute - * @return CollectionAttribute of the given name - * @throws IllegalArgumentException if attribute of the given - * name is not present in the managed type - */ - CollectionAttribute getCollection(String name); - - /** - * Return the Collection-valued attribute declared by the - * managed type that corresponds to the specified name. - * @param name the name of the represented attribute - * @return declared CollectionAttribute of the given name - * @throws IllegalArgumentException if attribute of the given - * name is not declared in the managed type - */ - CollectionAttribute getDeclaredCollection(String name); - - /** - * Return the Set-valued attribute of the managed type that - * corresponds to the specified name. - * @param name the name of the represented attribute - * @return SetAttribute of the given name - * @throws IllegalArgumentException if attribute of the given - * name is not present in the managed type - */ - SetAttribute getSet(String name); - - /** - * Return the Set-valued attribute declared by the managed type - * that corresponds to the specified name. - * @param name the name of the represented attribute - * @return declared SetAttribute of the given name - * @throws IllegalArgumentException if attribute of the given - * name is not declared in the managed type - */ - SetAttribute getDeclaredSet(String name); - - /** - * Return the List-valued attribute of the managed type that - * corresponds to the specified name. - * @param name the name of the represented attribute - * @return ListAttribute of the given name - * @throws IllegalArgumentException if attribute of the given - * name is not present in the managed type - */ - ListAttribute getList(String name); - - /** - * Return the List-valued attribute declared by the managed - * type that corresponds to the specified name. - * @param name the name of the represented attribute - * @return declared ListAttribute of the given name - * @throws IllegalArgumentException if attribute of the given - * name is not declared in the managed type - */ - ListAttribute getDeclaredList(String name); - - /** - * Return the Map-valued attribute of the managed type that - * corresponds to the specified name. - * @param name the name of the represented attribute - * @return MapAttribute of the given name - * @throws IllegalArgumentException if attribute of the given - * name is not present in the managed type - */ - MapAttribute getMap(String name); - - /** - * Return the Map-valued attribute declared by the managed - * type that corresponds to the specified name. - * @param name the name of the represented attribute - * @return declared MapAttribute of the given name - * @throws IllegalArgumentException if attribute of the given - * name is not declared in the managed type - */ - MapAttribute getDeclaredMap(String name); -} ----- - -==== IdentifiableType Interface - -[source,java] ----- -package jakarta.persistence.metamodel; - -import java.util.Set; - -/** - * Instances of the type IdentifiableType represent entity or - * mapped superclass types. - * - * @param The represented entity or mapped superclass type. - * - * @since 2.0 - * - */ -public interface IdentifiableType extends ManagedType { - - /** - * Return the attribute that corresponds to the id attribute of - * the entity or mapped superclass. - * @param type the type of the represented id attribute - * @return id attribute - * @throws IllegalArgumentException if id attribute of the given - * type is not present in the identifiable type or if - * the identifiable type has an id class - */ - SingularAttribute getId(Class type); - - /** - * Return the attribute that corresponds to the id attribute - * declared by the entity or mapped superclass. - * @param type the type of the represented declared - * id attribute - * @return declared id attribute - * @throws IllegalArgumentException if id attribute of the given - * type is not declared in the identifiable type or if - * the identifiable type has an id class - */ - SingularAttribute getDeclaredId(Class type); - - /** - * Return the attribute that corresponds to the version - * attribute of the entity or mapped superclass. - * @param type the type of the represented version attribute - * @return version attribute - * @throws IllegalArgumentException if version attribute of the - * given type is not present in the identifiable type - */ - SingularAttribute getVersion(Class type); - - /** - * Return the attribute that corresponds to the version - * attribute declared by the entity or mapped superclass. - * @param type the type of the represented declared version - * attribute - * @return declared version attribute - * @throws IllegalArgumentException if version attribute of the - * type is not declared in the identifiable type - */ - SingularAttribute getDeclaredVersion(Class type); - - /** - * Return the identifiable type that corresponds to the most - * specific mapped superclass or entity extended by the entity - * or mapped superclass. - * @return supertype of identifiable type or null if no - * such supertype - */ - IdentifiableType getSupertype(); - - /** - * Whether the identifiable type has a single id attribute. - * Returns true for a simple id or embedded id; returns false - * for an idclass. - * @return boolean indicating whether the identifiable - * type has a single id attribute - */ - boolean hasSingleIdAttribute(); - - /** - * Whether the identifiable type has a version attribute. - * @return boolean indicating whether the identifiable - * type has a version attribute - */ - boolean hasVersionAttribute(); - - /** - * Return the attributes corresponding to the id class of the - * identifiable type. - * @return id attributes - * @throws IllegalArgumentException if the identifiable type - * does not have an id class - */ - Set> getIdClassAttributes(); - - /** - * Return the type that represents the type of the id. - * @return type of id - */ - Type getIdType(); -} ----- - -==== EntityType Interface - -[source,java] ----- -package jakarta.persistence.metamodel; - -/** - * Instances of the type EntityType represent entity types. - * - * @param The represented entity type. - * - * @since 2.0 - * - */ -public interface EntityType - extends IdentifiableType, Bindable{ - - /** - * Return the entity name. - * @return entity name - */ - String getName(); -} ----- - -==== EmbeddableType Interface - -[source,java] ----- -package jakarta.persistence.metamodel; - -/** - * Instances of the type EmbeddableType represent embeddable types. - * - * @param The represented type. - * - * @since 2.0 - * - */ -public interface EmbeddableType extends ManagedType {} ----- - -==== MappedSuperclassType Interface - -[source,java] ----- -package jakarta.persistence.metamodel; - -/** - * Instances of the type MappedSuperclassType represent mapped - * superclass types. - * - * @param The represented entity type - * @since 2.0 - */ -public interface MappedSuperclassType extends IdentifiableType {} ----- - -==== BasicType Interface - -[source,java] ----- -package jakarta.persistence.metamodel; - -/** - * Instances of the type BasicType represent basic types (including - * temporal and enumerated types). - * - * @param The type of the represented basic type - * - * @since 2.0 - */ -public interface BasicType extends Type {} ----- - -==== Bindable Interface - -[source,java] ----- -package jakarta.persistence.metamodel; - -import jakarta.persistence.criteria.Path; - -/** - * Instances of the type Bindable represent object or attribute types - * that can be bound into a {@link Path Path}. - * - * @param The type of the represented object or attribute - * - * @since 2.0 - * - */ -public interface Bindable { - - public static enum BindableType { - /** - * Single-valued attribute type. - * - * @see SingularAttribute - */ - SINGULAR_ATTRIBUTE, - - /** - * Multivalued attribute type, that is, a collection. - * - * @see PluralAttribute - */ - PLURAL_ATTRIBUTE, - - /** - * Entity type. - * - * @see EntityType - */ - ENTITY_TYPE - } - - /** - * Return the bindable type of the represented object. - * @return bindable type - */ - BindableType getBindableType(); - - /** - * Return the Java type of the represented object. - * If the bindable type of the object is PLURAL_ATTRIBUTE, - * the Java element type is returned. If the bindable type is - * SINGULAR_ATTRIBUTE or ENTITY_TYPE, - * the Java type of the - * represented entity or attribute is returned. - * @return Java type - */ - Class getBindableJavaType(); -} ----- - -==== Attribute Interface - -[source,java] ----- -package jakarta.persistence.metamodel; - -/** - * Represents an attribute of a Java type. - * - * @param The represented type that contains the attribute - * @param The type of the represented attribute - * - * @since 2.0 - */ -public interface Attribute { - - public static enum PersistentAttributeType { - - /** Many-to-one association */ - MANY_TO_ONE, - - /** One-to-one association */ - ONE_TO_ONE, - - /** Basic attribute */ - BASIC, - - /** Embeddable class attribute */ - EMBEDDED, - - /** Many-to-many association */ - MANY_TO_MANY, - - /** One-to-many association */ - ONE_TO_MANY, - - /** Element collection */ - ELEMENT_COLLECTION - } - - /** - * Return the name of the attribute. - * @return name - */ - String getName(); - - /** - * Return the persistent attribute type for the attribute. - * @return persistent attribute type - */ - PersistentAttributeType getPersistentAttributeType(); - - /** - * Return the managed type representing the type in which - * the attribute was declared. - * @return declaring type - */ - ManagedType getDeclaringType(); - - /** - * Return the Java type of the represented attribute. - * @return Java type - */ - Class getJavaType(); - - /** - * Return the java.lang.reflect.Member for the represented - * attribute. - * @return corresponding java.lang.reflect.Member - */ - java.lang.reflect.Member getJavaMember(); - - /** - * Is the attribute an association. - * @return boolean indicating whether the attribute - * corresponds to an association - */ - boolean isAssociation(); - - /** - * Is the attribute collection-valued (represents a Collection, - * Set, List, or Map). - * @return boolean indicating whether the attribute is - * collection-valued - */ - boolean isCollection(); -} ----- - -==== SingularAttribute Interface - -[source,java] ----- -package jakarta.persistence.metamodel; - -/** - * Instances of the type SingularAttribute represents persistent - * single-valued properties or fields. - * - * @param The type containing the represented attribute - * @param The type of the represented attribute - * - * @since 2.0 - */ -public interface SingularAttribute - extends Attribute, Bindable { - - /** - * Is the attribute an id attribute. This method will return - * true if the attribute is an attribute that corresponds to - * a simple id, an embedded id, or an attribute of an id class. - * @return boolean indicating whether the attribute is an id - */ - boolean isId(); - - /** - * Is the attribute a version attribute. - * @return boolean indicating whether the attribute is - * a version attribute - */ - boolean isVersion(); - - /** - * Can the attribute be null. - * @return boolean indicating whether the attribute can - * be null - */ - boolean isOptional(); - - /** - * Return the type that represents the type of the attribute. - * @return type of attribute - */ - Type getType(); -} ----- - -==== PluralAttribute Interface - -[source,java] ----- -package jakarta.persistence.metamodel; - -/** - * Instances of the type PluralAttribute represent - * persistent collection-valued attributes. - * - * @param The type the represented collection belongs to - * @param The type of the represented collection - * @param The element type of the represented collection - * - * @since 2.0 - */ -public interface PluralAttribute - extends Attribute, Bindable { - - public static enum CollectionType { - - /** Collection-valued attribute */ - COLLECTION, - - /** Set-valued attribute */ - SET, - - /** List-valued attribute */ - LIST, - - /** Map-valued attribute */ - MAP - } - - /** - * Return the collection type. - * @return collection type - */ - CollectionType getCollectionType(); - - /** - * Return the type representing the element type of the - * collection. - * @return element type - */ - Type getElementType(); -} ----- - -==== CollectionAttribute Interface - -[source,java] ----- -package jakarta.persistence.metamodel; - -/** - * Instances of the type CollectionAttribute represent persistent - * java.util.Collection-valued attributes. - * - * @param The type the represented Collection belongs to - * @param The element type of the represented Collection - * - * @since 2.0 - * - */ -public interface CollectionAttribute - extends PluralAttribute, E> {} ----- - -==== SetAttribute Interface - -[source,java] ----- -package jakarta.persistence.metamodel; - -/** - * Instances of the type SetAttribute represent - * persistent java.util.Set-valued attributes. - * - * @param The type the represented Set belongs to - * @param The element type of the represented Set - * - * @since 2.0 - */ -public interface SetAttribute - extends PluralAttribute, E> {} ----- - -==== ListAttribute Interface - -[source,java] ----- -package jakarta.persistence.metamodel; - -/** - * Instances of the type ListAttribute represent persistent - * java.util.List-valued attributes. - * - * @param The type the represented List belongs to - * @param The element type of the represented List - * - * @since 2.0 - * - */ -public interface ListAttribute - extends PluralAttribute, E> {} ----- - -==== MapAttribute Interface - -[source,java] ----- -package jakarta.persistence.metamodel; - -/** - * Instances of the type MapAttribute represent - * persistent java.util.Map-valued attributes. - * - * @param The type the represented Map belongs to - * @param The type of the key of the represented Map - * @param The type of the value of the represented Map - * - * @since 2.0 - * - */ -public interface MapAttribute - extends PluralAttribute, V> { - - /** - * Return the Java type of the map key. - * @return Java key type - */ - Class getKeyJavaType(); - - /** - * Return the type representing the key type of the map. - * @return type representing key type - */ - Type getKeyType(); -} ----- - -==== StaticMetamodel Annotation - -[source,java] ----- -package jakarta.persistence.metamodel; - -import java.lang.annotation.ElementType; -import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Target; - -/** - * The StaticMetamodel annotation specifies that the class - * is a metamodel class that represents the entity, mapped - * superclass, or embeddable class designated by the value - * element. - * - * @since 2.0 - */ -@Target(ElementType.TYPE) -@Retention(RetentionPolicy.RUNTIME) -public @interface StaticMetamodel { - - /** - * Class being modelled by the annotated class. - */ - Class value(); -} ----- \ No newline at end of file +The complete metamodel API may be found in <>. \ No newline at end of file diff --git a/spec/src/main/asciidoc/ch06-criteria-api.adoc b/spec/src/main/asciidoc/ch06-criteria-api.adoc index dbb71937..d759e082 100644 --- a/spec/src/main/asciidoc/ch06-criteria-api.adoc +++ b/spec/src/main/asciidoc/ch06-criteria-api.adoc @@ -42,3768 +42,7 @@ The metamodel on which criteria queries are based was already presented in <>. The static metamodel classes which are used to construct strongly-typed criteria queries are described in <>. -=== Criteria API Interfaces [[a6997]] - -==== CriteriaBuilder Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -import java.math.BigDecimal; -import java.math.BigInteger; -import java.util.Collection; -import java.util.Map; -import java.util.Set; -import jakarta.persistence.Tuple; - -/** - * Used to construct criteria queries, compound selections, - * expressions, predicates, orderings. - * - *

Note that Predicate is used instead of Expression<Boolean> - * in this API in order to work around the fact that Java - * generics are not compatible with varags. - * - * @since 2.0 - */ -public interface CriteriaBuilder { - - /** - * Create a CriteriaQuery object. - * @return criteria query object - */ - CriteriaQuery createQuery(); - - /** - * Create a CriteriaQuery object with the specified result - * type. - * @param resultClass type of the query result - * @return criteria query object - */ - CriteriaQuery createQuery(Class resultClass); - - /** - * Create a CriteriaQuery object that returns a tuple of - * objects as its result. - * @return criteria query object - */ - CriteriaQuery createTupleQuery(); - - // methods to construct queries for bulk updates and deletes: - - /** - * Create a CriteriaUpdate query object to perform a bulk update operation. - * @param targetEntity target type for update operation - * @return the query object - * @since 2.1 - */ - CriteriaUpdate createCriteriaUpdate(Class targetEntity); - - /** - * Create a CriteriaDelete query object to perform a bulk delete operation. - * @param targetEntity target type for delete operation - * @return the query object - * @since 2.1 - */ - CriteriaDelete createCriteriaDelete(Class targetEntity); - - - // selection construction methods: - - /** - * Create a selection item corresponding to a constructor. - * This method is used to specify a constructor that will be - * applied to the results of the query execution. If the - * constructor is for an entity class, the resulting entities - * will be in the new state after the query is executed. - * @param resultClass class whose instance is to be constructed - * @param selections arguments to the constructor - * @return compound selection item - * @throws IllegalArgumentException if an argument is a - * tuple- or array-valued selection item - */ - CompoundSelection construct(Class resultClass, Selection... selections); - - /** - * Create a tuple-valued selection item. - * @param selections selection items - * @return tuple-valued compound selection - * @throws IllegalArgumentException if an argument is a - * tuple- or array-valued selection item - */ - CompoundSelection tuple(Selection... selections); - - /** - * Create a tuple-valued selection item. - * @param selections list of selection items - * @return tuple-valued compound selection - * @throws IllegalArgumentException if an argument is a - * tuple- or array-valued selection item - */ - CompoundSelection tuple(List> selections); - - /** - * Create an array-valued selection item. - * @param selections selection items - * @return array-valued compound selection - * @throws IllegalArgumentException if an argument is a - * tuple- or array-valued selection item - */ - CompoundSelection array(Selection... selections); - - /** - * Create an array-valued selection item. - * @param selections list of selection items - * @return array-valued compound selection - * @throws IllegalArgumentException if an argument is a - * tuple- or array-valued selection item - */ - CompoundSelection array(List> selections); - - - //ordering: - - /** - * Create an ordering by the ascending value of the expression. - * @param x expression used to define the ordering - * @return ascending ordering corresponding to the expression - */ - Order asc(Expression x); - - /** - * Create an ordering by the descending value of the expression. - * @param x expression used to define the ordering - * @return descending ordering corresponding to the expression - */ - Order desc(Expression x); - - - //aggregate functions: - - /** - * Create an aggregate expression applying the avg operation. - * @param x expression representing input value to avg operation - * @return avg expression - */ - Expression avg(Expression x); - - /** - * Create an aggregate expression applying the sum operation. - * @param x expression representing input value to sum operation - * @return sum expression - */ - Expression sum(Expression x); - - /** - * Create an aggregate expression applying the sum operation to an - * Integer-valued expression, returning a Long result. - * @param x expression representing input value to sum operation - * @return sum expression - */ - Expression sumAsLong(Expression x); - - /** - * Create an aggregate expression applying the sum operation to a - * Float-valued expression, returning a Double result. - * @param x expression representing input value to sum operation - * @return sum expression - */ - Expression sumAsDouble(Expression x); - - /** - * Create an aggregate expression applying the numerical max - * operation. - * @param x expression representing input value to max operation - * @return max expression - */ - Expression max(Expression x); - - /** - * Create an aggregate expression applying the numerical min - * operation. - * @param x expression representing input value to min operation - * @return min expression - */ - Expression min(Expression x); - - /** - * Create an aggregate expression for finding the greatest of - * the values (strings, dates, etc). - * @param x expression representing input value to greatest - * operation - * @return greatest expression - */ - > Expression greatest(Expression x); - - /** - * Create an aggregate expression for finding the least of - * the values (strings, dates, etc). - * @param x expression representing input value to least - * operation - * @return least expression - */ - > Expression least(Expression x); - - /** - * Create an aggregate expression applying the count operation. - * @param x expression representing input value to count - * operation - * @return count expression - */ - Expression count(Expression x); - - /** - * Create an aggregate expression applying the count distinct - * operation. - * @param x expression representing input value to - * count distinct operation - * @return count distinct expression - */ - Expression countDistinct(Expression x); - - - - //subqueries: - - /** - * Create a predicate testing the existence of a subquery result. - * @param subquery subquery whose result is to be tested - * @return exists predicate - */ - Predicate exists(Subquery subquery); - - /** - * Create an all expression over the subquery results. - * @param subquery subquery - * @return all expression - */ - Expression all(Subquery subquery); - - /** - * Create a some expression over the subquery results. - * This expression is equivalent to an any expression. - * @param subquery subquery - * @return some expression - */ - Expression some(Subquery subquery); - - /** - * Create an any expression over the subquery results. - * This expression is equivalent to a some expression. - * @param subquery subquery - * @return any expression - */ - Expression any(Subquery subquery); - - - //boolean functions: - - /** - * Create a conjunction of the given boolean expressions. - * @param x boolean expression - * @param y boolean expression - * @return and predicate - */ - Predicate and(Expression x, Expression y); - - /** - * Create a conjunction of the given restriction predicates. - * A conjunction of zero predicates is true. - * @param restrictions zero or more restriction predicates - * @return and predicate - */ - Predicate and(Predicate... restrictions); - - /** - * Create a disjunction of the given boolean expressions. - * @param x boolean expression - * @param y boolean expression - * @return or predicate - */ - Predicate or(Expression x, Expression y); - - /** - * Create a disjunction of the given restriction predicates. - * A disjunction of zero predicates is false. - * @param restrictions zero or more restriction predicates - * @return or predicate - */ - Predicate or(Predicate... restrictions); - - /** - * Create a negation of the given restriction. - * @param restriction restriction expression - * @return not predicate - */ - Predicate not(Expression restriction); - - /** - * Create a conjunction (with zero conjuncts). - * A conjunction with zero conjuncts is true. - * @return and predicate - */ - Predicate conjunction(); - - /** - * Create a disjunction (with zero disjuncts). - * A disjunction with zero disjuncts is false. - * @return or predicate - */ - Predicate disjunction(); - - - //turn Expression into a Predicate - //useful for use with varargs methods - - /** - * Create a predicate testing for a true value. - * @param x expression to be tested - * @return predicate - */ - Predicate isTrue(Expression x); - - /** - * Create a predicate testing for a false value. - * @param x expression to be tested - * @return predicate - */ - Predicate isFalse(Expression x); - - - //null tests: - - /** - * Create a predicate to test whether the expression is null. - * @param x expression - * @return is-null predicate - */ - Predicate isNull(Expression x); - - /** - * Create a predicate to test whether the expression is not null. - * @param x expression - * @return is-not-null predicate - */ - Predicate isNotNull(Expression x); - - //equality: - - /** - * Create a predicate for testing the arguments for equality. - * @param x expression - * @param y expression - * @return equality predicate - */ - Predicate equal(Expression x, Expression y); - - /** - * Create a predicate for testing the arguments for equality. - * @param x expression - * @param y object - * @return equality predicate - */ - Predicate equal(Expression x, Object y); - - /** - * Create a predicate for testing the arguments for inequality. - * @param x expression - * @param y expression - * @return inequality predicate - */ - Predicate notEqual(Expression x, Expression y); - - /** - * Create a predicate for testing the arguments for inequality. - * @param x expression - * @param y object - * @return inequality predicate - */ - Predicate notEqual(Expression x, Object y); - - - //comparisons for generic (non-numeric) operands: - - /** - * Create a predicate for testing whether the first argument is - * greater than the second. - * @param x expression - * @param y expression - * @return greater-than predicate - */ - > Predicate greaterThan(Expression x, Expression y); - - /** - * Create a predicate for testing whether the first argument is - * greater than the second. - * @param x expression - * @param y value - * @return greater-than predicate - */ - > Predicate greaterThan(Expression x, Y y); - - /** - * Create a predicate for testing whether the first argument is - * greater than or equal to the second. - * @param x expression - * @param y expression - * @return greater-than-or-equal predicate - */ - > Predicate greaterThanOrEqualTo(Expression x, Expression y); - - /** - * Create a predicate for testing whether the first argument is - * greater than or equal to the second. - * @param x expression - * @param y value - * @return greater-than-or-equal predicate - */ - > Predicate greaterThanOrEqualTo(Expression x, Y y); - - /** - * Create a predicate for testing whether the first argument is - * less than the second. - * @param x expression - * @param y expression - * @return less-than predicate - */ - > Predicate lessThan(Expression x, Expression y); - - /** - * Create a predicate for testing whether the first argument is - * less than the second. - * @param x expression - * @param y value - * @return less-than predicate - */ - > Predicate lessThan(Expression x, Y y); - - /** - * Create a predicate for testing whether the first argument is - * less than or equal to the second. - * @param x expression - * @param y expression - * @return less-than-or-equal predicate - */ - > Predicate lessThanOrEqualTo(Expression x, Expression y); - - /** - * Create a predicate for testing whether the first argument is - * less than or equal to the second. - * @param x expression - * @param y value - * @return less-than-or-equal predicate - */ - > Predicate lessThanOrEqualTo(Expression x, Y y); - - /** - * Create a predicate for testing whether the first argument is - * between the second and third arguments in value. - * @param v expression - * @param x expression - * @param y expression - * @return between predicate - */ - > Predicate between(Expression v, Expression x, Expression y); - - /** - * Create a predicate for testing whether the first argument is - * between the second and third arguments in value. - * @param v expression - * @param x value - * @param y value - * @return between predicate - */ - > Predicate between(Expression v, Y x, Y y); - - - //comparisons for numeric operands: - - /** - * Create a predicate for testing whether the first argument is - * greater than the second. - * @param x expression - * @param y expression - * @return greater-than predicate - */ - Predicate gt(Expression x, Expression y); - - /** - * Create a predicate for testing whether the first argument is - * greater than the second. - * @param x expression - * @param y value - * @return greater-than predicate - */ - Predicate gt(Expression x, Number y); - - /** - * Create a predicate for testing whether the first argument is - * greater than or equal to the second. - * @param x expression - * @param y expression - * @return greater-than-or-equal predicate - */ - Predicate ge(Expression x, Expression y); - - /** - * Create a predicate for testing whether the first argument is - * greater than or equal to the second. - * @param x expression - * @param y value - * @return greater-than-or-equal predicate - */ - Predicate ge(Expression x, Number y); - - /** - * Create a predicate for testing whether the first argument is - * less than the second. - * @param x expression - * @param y expression - * @return less-than predicate - */ - Predicate lt(Expression x, Expression y); - - /** - * Create a predicate for testing whether the first argument is - * less than the second. - * @param x expression - * @param y value - * @return less-than predicate - */ - Predicate lt(Expression x, Number y); - - /** - * Create a predicate for testing whether the first argument is - * less than or equal to the second. - * @param x expression - * @param y expression - * @return less-than-or-equal predicate - */ - Predicate le(Expression x, Expression y); - - /** - * Create a predicate for testing whether the first argument is - * less than or equal to the second. - * @param x expression - * @param y value - * @return less-than-or-equal predicate - */ - Predicate le(Expression x, Number y); - - - //numerical operations: - - /** - * Create an expression that returns the arithmetic negation - * of its argument. - * @param x expression - * @return arithmetic negation - */ - Expression neg(Expression x); - - /** - * Create an expression that returns the absolute value - * of its argument. - * @param x expression - * @return absolute value - */ - Expression abs(Expression x); - - /** - * Create an expression that returns the sum - * of its arguments. - * @param x expression - * @param y expression - * @return sum - */ - Expression sum(Expression x, Expression y); - - /** - * Create an expression that returns the sum - * of its arguments. - * @param x expression - * @param y value - * @return sum - */ - Expression sum(Expression x, N y); - - /** - * Create an expression that returns the sum - * of its arguments. - * @param x value - * @param y expression - * @return sum - */ - Expression sum(N x, Expression y); - - /** - * Create an expression that returns the product - * of its arguments. - * @param x expression - * @param y expression - * @return product - */ - Expression prod(Expression x, Expression y); - - /** - * Create an expression that returns the product - * of its arguments. - * @param x expression - * @param y value - * @return product - */ - Expression prod(Expression x, N y); - - /** - * Create an expression that returns the product - * of its arguments. - * @param x value - * @param y expression - * @return product - */ - Expression prod(N x, Expression y); - - /** - * Create an expression that returns the difference - * between its arguments. - * @param x expression - * @param y expression - * @return difference - */ - Expression diff(Expression x, Expression y); - - /** - * Create an expression that returns the difference - * between its arguments. - * @param x expression - * @param y value - * @return difference - */ - Expression diff(Expression x, N y); - - /** - * Create an expression that returns the difference - * between its arguments. - * @param x value - * @param y expression - * @return difference - */ - Expression diff(N x, Expression y); - - /** - * Create an expression that returns the quotient - * of its arguments. - * @param x expression - * @param y expression - * @return quotient - */ - Expression quot(Expression x, Expression y); - - /** - * Create an expression that returns the quotient - * of its arguments. - * @param x expression - * @param y value - * @return quotient - */ - Expression quot(Expression x, Number y); - - /** - * Create an expression that returns the quotient - * of its arguments. - * @param x value - * @param y expression - * @return quotient - */ - Expression quot(Number x, Expression y); - - /** - * Create an expression that returns the modulus - * of its arguments. - * @param x expression - * @param y expression - * @return modulus - */ - Expression mod(Expression x, Expression y); - - /** - * Create an expression that returns the modulus - * of its arguments. - * @param x expression - * @param y value - * @return modulus - */ - Expression mod(Expression x, Integer y); - - /** - * Create an expression that returns the modulus - * of its arguments. - * @param x value - * @param y expression - * @return modulus - */ - Expression mod(Integer x, Expression y); - - /** - * Create an expression that returns the square root - * of its argument. - * @param x expression - * @return square root - */ - Expression sqrt(Expression x); - - - //typecasts: - - /** - * Typecast. Returns same expression object. - * @param number numeric expression - * @return Expression<Long> - */ - Expression toLong(Expression number); - - /** - * Typecast. Returns same expression object. - * @param number numeric expression - * @return Expression<Integer> - */ - Expression toInteger(Expression number); - - /** - * Typecast. Returns same expression object. - * @param number numeric expression - * @return Expression<Float> - */ - Expression toFloat(Expression number); - - /** - * Typecast. Returns same expression object. - * @param number numeric expression - * @return Expression<Double> - */ - Expression toDouble(Expression number); - - /** - * Typecast. Returns same expression object. - * @param number numeric expression - * @return Expression<BigDecimal> - */ - Expression toBigDecimal(Expression number); - - /** - * Typecast. Returns same expression object. - * @param number numeric expression - * @return Expression<BigInteger> - */ - Expression toBigInteger(Expression number); - - /** - * Typecast. Returns same expression object. - * @param character expression - * @return Expression<String> - */ - Expression toString(Expression character); - - - //literals: - - /** - * Create an expression for a literal. - * @param value value represented by the expression - * @return expression literal - * @throws IllegalArgumentException if value is null - */ - Expression literal(T value); - - /** - * Create an expression for a null literal with the given type. - * @param resultClass type of the null literal - * @return null expression literal - */ - Expression nullLiteral(Class resultClass); - - //parameters: - - /** - * Create a parameter expression. - * @param paramClass parameter class - * @return parameter expression - */ - ParameterExpression parameter(Class paramClass); - - /** - * Create a parameter expression with the given name. - * @param paramClass parameter class - * @param name name that can be used to refer to - * the parameter - * @return parameter expression - */ - ParameterExpression parameter(Class paramClass, String name); - - - //collection operations: - - /** - * Create a predicate that tests whether a collection is empty. - * @param collection expression - * @return is-empty predicate - */ - > Predicate isEmpty(Expression collection); - - /** - * Create a predicate that tests whether a collection is - * not empty. - * @param collection expression - * @return is-not-empty predicate - */ - > Predicate isNotEmpty(Expression collection); - - /** - * Create an expression that tests the size of a collection. - * @param collection expression - * @return size expression - */ - > Expression size(Expression collection); - - /** - * Create an expression that tests the size of a collection. - * @param collection collection - * @return size expression - */ - > Expression size(C collection); - - /** - * Create a predicate that tests whether an element is - * a member of a collection. - * If the collection is empty, the predicate will be false. - * @param elem element expression - * @param collection expression - * @return is-member predicate - */ - > Predicate isMember(Expression elem, Expression collection); - - /** - * Create a predicate that tests whether an element is - * a member of a collection. - * If the collection is empty, the predicate will be false. - * @param elem element - * @param collection expression - * @return is-member predicate - */ - > Predicate isMember(E elem, Expression collection); - - /** - * Create a predicate that tests whether an element is - * not a member of a collection. - * If the collection is empty, the predicate will be true. - * @param elem element expression - * @param collection expression - * @return is-not-member predicate - */ - > Predicate isNotMember(Expression elem, Expression collection); - - /** - * Create a predicate that tests whether an element is - * not a member of a collection. - * If the collection is empty, the predicate will be true. - * @param elem element - * @param collection expression - * @return is-not-member predicate - */ - > Predicate isNotMember(E elem, Expression collection); - - - //get the values and keys collections of the Map, which may then - //be passed to size(), isMember(), isEmpty(), etc - - /** - * Create an expression that returns the values of a map. - * @param map map - * @return collection expression - */ - > Expression> values(M map); - - /** - * Create an expression that returns the keys of a map. - * @param map map - * @return set expression - */ - > Expression> keys(M map); - - - //string functions: - - /** - * Create a predicate for testing whether the expression - * satisfies the given pattern. - * @param x string expression - * @param pattern string expression - * @return like predicate - */ - Predicate like(Expression x, Expression pattern); - - /** - * Create a predicate for testing whether the expression - * satisfies the given pattern. - * @param x string expression - * @param pattern string - * @return like predicate - */ - Predicate like(Expression x, String pattern); - - /** - * Create a predicate for testing whether the expression - * satisfies the given pattern. - * @param x string expression - * @param pattern string expression - * @param escapeChar escape character expression - * @return like predicate - */ - Predicate like(Expression x, Expression pattern, Expression escapeChar); - - /** - * Create a predicate for testing whether the expression - * satisfies the given pattern. - * @param x string expression - * @param pattern string expression - * @param escapeChar escape character - * @return like predicate - */ - Predicate like(Expression x, Expression pattern, char escapeChar); - - /** - * Create a predicate for testing whether the expression - * satisfies the given pattern. - * @param x string expression - * @param pattern string - * @param escapeChar escape character expression - * @return like predicate - */ - Predicate like(Expression x, String pattern, Expression escapeChar); - - /** - * Create a predicate for testing whether the expression - * satisfies the given pattern. - * @param x string expression - * @param pattern string - * @param escapeChar escape character - * @return like predicate - */ - Predicate like(Expression x, String pattern, char escapeChar); - - /** - * Create a predicate for testing whether the expression - * does not satisfy the given pattern. - * @param x string expression - * @param pattern string expression - * @return not-like predicate - */ - Predicate notLike(Expression x, Expression pattern); - - /** - * Create a predicate for testing whether the expression - * does not satisfy the given pattern. - * @param x string expression - * @param pattern string - * @return not-like predicate - */ - Predicate notLike(Expression x, String pattern); - - /** - * Create a predicate for testing whether the expression - * does not satisfy the given pattern. - * @param x string expression - * @param pattern string expression - * @param escapeChar escape character expression - * @return not-like predicate - */ - Predicate notLike(Expression x, Expression pattern, Expression escapeChar); - - /** - * Create a predicate for testing whether the expression - * does not satisfy the given pattern. - * @param x string expression - * @param pattern string expression - * @param escapeChar escape character - * @return not-like predicate - */ - Predicate notLike(Expression x, Expression pattern, char escapeChar); - - /** - * Create a predicate for testing whether the expression - * does not satisfy the given pattern. - * @param x string expression - * @param pattern string - * @param escapeChar escape character expression - * @return not-like predicate - */ - Predicate notLike(Expression x, String pattern, Expression escapeChar); - - /** - * Create a predicate for testing whether the expression - * does not satisfy the given pattern. - * @param x string expression - * @param pattern string - * @param escapeChar escape character - * @return not-like predicate - */ - Predicate notLike(Expression x, String pattern, char escapeChar); - - /** - * Create an expression for string concatenation. - * If the given list of expressions is empty, returns - * an expression equivalent to {@code literal("")}. - * @param expressions string expressions - * @return expression corresponding to concatenation - */ - Expression concat(List> expressions); - - /** - * Create an expression for string concatenation. - * @param x string expression - * @param y string expression - * @return expression corresponding to concatenation - */ - Expression concat(Expression x, Expression y); - - /** - * Create an expression for string concatenation. - * @param x string expression - * @param y string - * @return expression corresponding to concatenation - */ - Expression concat(Expression x, String y); - - /** - * Create an expression for string concatenation. - * @param x string - * @param y string expression - * @return expression corresponding to concatenation - */ - Expression concat(String x, Expression y); - - /** - * Create an expression for substring extraction. - * Extracts a substring starting at the specified position - * through to end of the string. - * First position is 1. - * @param x string expression - * @param from start position expression - * @return expression corresponding to substring extraction - */ - Expression substring(Expression x, Expression from); - - /** - * Create an expression for substring extraction. - * Extracts a substring starting at the specified position - * through to end of the string. - * First position is 1. - * @param x string expression - * @param from start position - * @return expression corresponding to substring extraction - */ - Expression substring(Expression x, int from); - - /** - * Create an expression for substring extraction. - * Extracts a substring of given length starting at the - * specified position. - * First position is 1. - * @param x string expression - * @param from start position expression - * @param len length expression - * @return expression corresponding to substring extraction - */ - Expression substring(Expression x, Expression from, Expression len); - - /** - * Create an expression for substring extraction. - * Extracts a substring of given length starting at the - * specified position. - * First position is 1. - * @param x string expression - * @param from start position - * @param len length - * @return expression corresponding to substring extraction - */ - Expression substring(Expression x, int from, int len); - - /** - * Used to specify how strings are trimmed. - */ - public static enum Trimspec { - - /** - * Trim from leading end. - */ - LEADING, - - /** - * Trim from trailing end. - */ - TRAILING, - - /** - * Trim from both ends. - */ - BOTH - } - - /** - * Create expression to trim blanks from both ends of - * a string. - * @param x expression for string to trim - * @return trim expression - */ - Expression trim(Expression x); - - /** - * Create expression to trim blanks from a string. - * @param ts trim specification - * @param x expression for string to trim - * @return trim expression - */ - Expression trim(Trimspec ts, Expression x); - - /** - * Create expression to trim character from both ends of - * a string. - * @param t expression for character to be trimmed - * @param x expression for string to trim - * @return trim expression - */ - Expression trim(Expression t, Expression x); - - /** - * Create expression to trim character from a string. - * @param ts trim specification - * @param t expression for character to be trimmed - * @param x expression for string to trim - * @return trim expression - */ - Expression trim(Trimspec ts, Expression t, Expression x); - - /** - * Create expression to trim character from both ends of - * a string. - * @param t character to be trimmed - * @param x expression for string to trim - * @return trim expression - */ - Expression trim(char t, Expression x); - - /** - * Create expression to trim character from a string. - * @param ts trim specification - * @param t character to be trimmed - * @param x expression for string to trim - * @return trim expression - */ - Expression trim(Trimspec ts, char t, Expression x); - - /** - * Create expression for converting a string to lowercase. - * @param x string expression - * @return expression to convert to lowercase - */ - Expression lower(Expression x); - - /** - * Create expression for converting a string to uppercase. - * @param x string expression - * @return expression to convert to uppercase - */ - Expression upper(Expression x); - - /** - * Create expression to return length of a string. - * @param x string expression - * @return length expression - */ - Expression length(Expression x); - - /** - * Create an expression for the leftmost substring of a string, - * @param x string expression - * @param len length of the substring to return - * @return expression for the leftmost substring - */ - Expression left(Expression x, int len); - - /** - * Create an expression for the rightmost substring of a string, - * @param x string expression - * @param len length of the substring to return - * @return expression for the rightmost substring - */ - Expression right(Expression x, int len); - - /** - * Create an expression for the leftmost substring of a string, - * @param x string expression - * @param len length of the substring to return - * @return expression for the leftmost substring - */ - Expression left(Expression x, Expression len); - - /** - * Create an expression for the rightmost substring of a string, - * @param x string expression - * @param len length of the substring to return - * @return expression for the rightmost substring - */ - Expression right(Expression x, Expression len); - - /** - * Create an expression replacing every occurrence of a substring - * within a string. - * @param x string expression - * @param substring the literal substring to replace - * @param replacement the replacement string - * @return expression for the resulting string - */ - Expression replace(Expression x, Expression substring, Expression replacement); - - /** - * Create an expression replacing every occurrence of a substring - * within a string. - * @param x string expression - * @param substring the literal substring to replace - * @param replacement the replacement string - * @return expression for the resulting string - */ - Expression replace(Expression x, String substring, Expression replacement); - - /** - * Create an expression replacing every occurrence of a substring - * within a string. - * @param x string expression - * @param substring the literal substring to replace - * @param replacement the replacement string - * @return expression for the resulting string - */ - Expression replace(Expression x, Expression substring, String replacement); - - /** - * Create an expression replacing every occurrence of a substring - * within a string. - * @param x string expression - * @param substring the literal substring to replace - * @param replacement the replacement string - * @return expression for the resulting string - */ - Expression replace(Expression x, String substring, String replacement); - - /** - * Create expression to locate the position of one string - * within another, returning position of first character - * if found. - * The first position in a string is denoted by 1. If the - * string to be located is not found, 0 is returned. - *

Warning: the order of the parameters - * of this method is reversed compared to the corresponding - * function in JPQL. - * @param x expression for string to be searched - * @param pattern expression for string to be located - * @return expression corresponding to position - */ - Expression locate(Expression x, Expression pattern); - - /** - * Create expression to locate the position of one string - * within another, returning position of first character - * if found. - * The first position in a string is denoted by 1. If the - * string to be located is not found, 0 is returned. - *

Warning: the order of the parameters - * of this method is reversed compared to the corresponding - * function in JPQL. - * @param x expression for string to be searched - * @param pattern string to be located - * @return expression corresponding to position - */ - Expression locate(Expression x, String pattern); - - /** - * Create expression to locate the position of one string - * within another, returning position of first character - * if found. - * The first position in a string is denoted by 1. If the - * string to be located is not found, 0 is returned. - *

Warning: the order of the first two - * parameters of this method is reversed compared to the - * corresponding function in JPQL. - * @param x expression for string to be searched - * @param pattern expression for string to be located - * @param from expression for position at which to start search - * @return expression corresponding to position - */ - Expression locate(Expression x, Expression pattern, Expression from); - - /** - * Create expression to locate the position of one string - * within another, returning position of first character - * if found. - * The first position in a string is denoted by 1. If the - * string to be located is not found, 0 is returned. - *

Warning: the order of the first two - * parameters of this method is reversed compared to the - * corresponding function in JPQL. - * @param x expression for string to be searched - * @param pattern string to be located - * @param from position at which to start search - * @return expression corresponding to position - */ - Expression locate(Expression x, String pattern, int from); - - - // Date/time/timestamp functions: - - /** - * Create expression to return current date. - * @return expression for current date - */ - Expression currentDate(); - - /** - * Create expression to return current timestamp. - * @return expression for current timestamp - */ - Expression currentTimestamp(); - - /** - * Create expression to return current time. - * @return expression for current time - */ - Expression currentTime(); - - - //in builders: - - /** - * Interface used to build in predicates. - */ - public static interface In extends Predicate { - - /** - * Return the expression to be tested against the - * list of values. - * @return expression - */ - Expression getExpression(); - - /** - * Add to list of values to be tested against. - * @param value value - * @return in predicate - */ - In value(T value); - - /** - * Add to list of values to be tested against. - * @param value expression - * @return in predicate - */ - In value(Expression value); - } - - /** - * Create predicate to test whether given expression - * is contained in a list of values. - * @param expression to be tested against list of values - * @return in predicate - */ - In in(Expression expression); - - - // coalesce, nullif: - - /** - * Create an expression that returns null if all its arguments - * evaluate to null, and the value of the first non-null argument - * otherwise. - * @param x expression - * @param y expression - * @return coalesce expression - */ - Expression coalesce(Expression x, Expression y); - - /** - * Create an expression that returns null if all its arguments - * evaluate to null, and the value of the first non-null argument - * otherwise. - * @param x expression - * @param y value - * @return coalesce expression - */ - Expression coalesce(Expression x, Y y); - - /** - * Create an expression that tests whether its argument are - * equal, returning null if they are and the value of the - * first expression if they are not. - * @param x expression - * @param y expression - * @return nullif expression - */ - Expression nullif(Expression x, Expression y); - - /** - * Create an expression that tests whether its argument are - * equal, returning null if they are and the value of the - * first expression if they are not. - * @param x expression - * @param y value - * @return nullif expression - */ - Expression nullif(Expression x, Y y); - - - // coalesce builder: - - /** - * Interface used to build coalesce expressions. - * - * A coalesce expression is equivalent to a case expression - * that returns null if all its arguments evaluate to null, - * and the value of its first non-null argument otherwise. - */ - public static interface Coalesce extends Expression { - - /** - * Add an argument to the coalesce expression. - * @param value value - * @return coalesce expression - */ - Coalesce value(T value); - - /** - * Add an argument to the coalesce expression. - * @param value expression - * @return coalesce expression - */ - Coalesce value(Expression value); - } - - /** - * Create a coalesce expression. - * @return coalesce expression - */ - Coalesce coalesce(); - - - //case builders: - - /** - * Interface used to build simple case expressions. - * Case conditions are evaluated in the order in which - * they are specified. - */ - public static interface SimpleCase extends Expression { - - /** - * Return the expression to be tested against the - * conditions. - * @return expression - */ - Expression getExpression(); - - /** - * Add a when/then clause to the case expression. - * @param condition "when" condition - * @param result "then" result value - * @return simple case expression - */ - SimpleCase when(C condition, R result); - - /** - * Add a when/then clause to the case expression. - * @param condition "when" condition - * @param result "then" result expression - * @return simple case expression - */ - SimpleCase when(C condition, Expression result); - - /** - * Add an "else" clause to the case expression. - * @param result "else" result - * @return expression - */ - Expression otherwise(R result); - - /** - * Add an "else" clause to the case expression. - * @param result "else" result expression - * @return expression - */ - Expression otherwise(Expression result); - } - - /** - * Create a simple case expression. - * @param expression to be tested against the case conditions - * @return simple case expression - */ - SimpleCase selectCase(Expression expression); - - - /** - * Interface used to build general case expressions. - * Case conditions are evaluated in the order in which - * they are specified. - */ - public static interface Case extends Expression { - - /** - * Add a when/then clause to the case expression. - * @param condition "when" condition - * @param result "then" result value - * @return general case expression - */ - Case when(Expression condition, R result); - - /** - * Add a when/then clause to the case expression. - * @param condition "when" condition - * @param result "then" result expression - * @return general case expression - */ - Case when(Expression condition, Expression result); - - /** - * Add an "else" clause to the case expression. - * @param result "else" result - * @return expression - */ - Expression otherwise(R result); - - /** - * Add an "else" clause to the case expression. - * @param result "else" result expression - * @return expression - */ - Expression otherwise(Expression result); - } - - /** - * Create a general case expression. - * @return general case expression - */ - Case selectCase(); - - /** - * Create an expression for the execution of a database - * function. - * @param name function name - * @param type expected result type - * @param args function arguments - * @return expression - */ - Expression function(String name, Class type, -Expression... args); - - - // methods for downcasting: - - /** - * Downcast Join object to the specified type. - * @param join Join object - * @param type type to be downcast to - * @return Join object of the specified type - * @since 2.1 - */ - Join treat(Join join, Class type); - - /** - * Downcast CollectionJoin object to the specified type. - * @param join CollectionJoin object - * @param type type to be downcast to - * @return CollectionJoin object of the specified type - * @since 2.1 - */ - CollectionJoin treat(CollectionJoin join, Class type); - - /** - * Downcast SetJoin object to the specified type. - * @param join SetJoin object - * @param type type to be downcast to - * @return SetJoin object of the specified type - * @since 2.1 - */ - SetJoin treat(SetJoin join, Class type); - - /** - * Downcast ListJoin object to the specified type. - * @param join ListJoin object - * @param type type to be downcast to - * @return ListJoin object of the specified type - * @since 2.1 - */ - ListJoin treat(ListJoin join, Class type); - - /** - * Downcast MapJoin object to the specified type. - * @param join MapJoin object - * @param type type to be downcast to - * @return MapJoin object of the specified type - * @since 2.1 - */ - MapJoin treat(MapJoin join, Class type); - - - /** - * Downcast Path object to the specified type. - * @param path path - * @param type type to be downcast to - * @return Path object of the specified type - * @since 2.1 - */ - Path treat(Path path, Class type); - - /** - * Downcast Root object to the specified type. - * @param root root - * @param type type to be downcast to - * @return Root object of the specified type - * @since 2.1 - */ - Root treat(Root root, Class type); - - /** - * Create a query which is the union of the given queries. - * @return a new criteria query which returns the union of - * the results of the given queries - * @since 3.2 - */ - CriteriaSelect union(CriteriaSelect left, CriteriaSelect right); - - /** - * Create a query which is the union of the given queries, - * without elimination of duplicate results. - * @return a new criteria query which returns the union of - * the results of the given queries - * @since 3.2 - */ - CriteriaSelect unionAll(CriteriaSelect left, CriteriaSelect right); - - /** - * Create a query which is the intersection of the given queries. - * @return a new criteria query which returns the intersection of - * the results of the given queries - * @since 3.2 - */ - CriteriaSelect intersect(CriteriaSelect left, CriteriaSelect right); - - /** - * Create a query which is the intersection of the given queries, - * without elimination of duplicate results. - * @return a new criteria query which returns the intersection of - * the results of the given queries - * @since 3.2 - */ - CriteriaSelect intersectAll(CriteriaSelect left, CriteriaSelect right); - - /** - * Create a query by (setwise) subtraction of the second query - * from the first query. - * @return a new criteria query which returns the result of - * subtracting the results of the second query from the - * results of the first query - * @since 3.2 - */ - CriteriaSelect except(CriteriaSelect left, CriteriaSelect right); - - /** - * Create a query by (setwise) subtraction of the second query - * from the first query, without elimination of duplicate results. - * @return a new criteria query which returns the result of - * subtracting the results of the second query from the - * results of the first query - * @since 3.2 - */ - CriteriaSelect exceptAll(CriteriaSelect left, CriteriaSelect right); -} ----- - -==== CommonAbstractCriteria Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -/** - * The CommonAbstractCriteria interface defines functionality - * that is common to both top-level criteria queries and subqueries as - * well as to update and delete criteria operations. - * It is not intended to be used directly in query construction. - * - *

Note that criteria queries and criteria update and delete operations - * are typed differently. - * Criteria queries are typed according to the query result type. - * Update and delete operations are typed according to the target of the - * update or delete. - * - * @since 2.1 - */ -public interface CommonAbstractCriteria { - - /** - * Create a subquery of the query. - * @param type the subquery result type - * @return subquery - */ - Subquery subquery(Class type); - - /** - * Create a subquery of the query. - * @param type the subquery result type - * @return subquery - */ - Subquery subquery(EntityType type); - - /** - * Return the predicate that corresponds to the where clause - * restriction(s), or null if no restrictions have been - * specified. - * @return where clause predicate - */ - Predicate getRestriction(); - - /** - * Return the parameters of the query. Returns empty set if - * there are no parameters. - * Modifications to the set do not affect the query. - * @return the query parameters - */ - Set> getParameters(); -} ----- - -==== AbstractQuery Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -import java.util.List; -import java.util.Set; -import jakarta.persistence.metamodel.EntityType; - -/** - * The AbstractQuery interface defines functionality that is common - * to both top-level queries and subqueries. - * It is not intended to be used directly in query construction. - * - *

All queries must have: - * a set of root entities (which may in turn own joins). - *

All queries may have: - * a conjunction of restrictions. - * - * @param the type of the result - * - * @since 2.0 - */ -public interface AbstractQuery extends CommonAbstractCriteria { - - /** - * Create and add a query root corresponding to the given entity, - * forming a cartesian product with any existing roots. - * @param entityClass the entity class - * @return query root corresponding to the given entity - */ - Root from(Class entityClass); - - /** - * Create and add a query root corresponding to the given entity, - * forming a cartesian product with any existing roots. - * @param entity metamodel entity representing the entity - * of type X - * @return query root corresponding to the given entity - */ - Root from(EntityType entity); - - /** - * Modify the query to restrict the query results according - * to the specified boolean expression. - * Replaces the previously added restriction(s), if any. - * @param restriction a simple or compound boolean expression - * @return the modified query - */ - AbstractQuery where(Expression restriction); - - /** - * Modify the query to restrict the query results according - * to the conjunction of the specified restriction predicates. - * Replaces the previously added restriction(s), if any. - * If no restrictions are specified, any previously added - * restrictions are simply removed. - * @param restrictions zero or more restriction predicates - * @return the modified query - */ - AbstractQuery where(Predicate... restrictions); - - /** - * Specify the expressions that are used to form groups over - * the query results. - * Replaces the previous specified grouping expressions, if any. - * If no grouping expressions are specified, any previously - * added grouping expressions are simply removed. - * @param grouping zero or more grouping expressions - * @return the modified query - */ - AbstractQuery groupBy(Expression... grouping); - - /** - * Specify the expressions that are used to form groups over - * the query results. - * Replaces the previous specified grouping expressions, if any. - * If no grouping expressions are specified, any previously - * added grouping expressions are simply removed. - * @param grouping list of zero or more grouping expressions - * @return the modified query - */ - AbstractQuery groupBy(List> grouping); - - /** - * Specify a restriction over the groups of the query. - * Replaces the previous having restriction(s), if any. - * @param restriction a simple or compound boolean expression - * @return the modified query - */ - AbstractQuery having(Expression restriction); - - /** - * Specify restrictions over the groups of the query - * according the conjunction of the specified restriction - * predicates. - * Replaces the previously having added restriction(s), if any. - * If no restrictions are specified, any previously added - * restrictions are simply removed. - * @param restrictions zero or more restriction predicates - * @return the modified query - */ - AbstractQuery having(Predicate... restrictions); - - /** - * Specify whether duplicate query results will be eliminated. - * A true value will cause duplicates to be eliminated. - * A false value will cause duplicates to be retained. - * If distinct has not been specified, duplicate results must - * be retained. - * @param distinct boolean value specifying whether duplicate - * results must be eliminated from the query result or - * whether they must be retained - * @return the modified query - */ - AbstractQuery distinct(boolean distinct); - - /** - * Return the query roots. These are the roots that have - * been defined for the CriteriaQuery or Subquery itself, - * including any subquery roots defined as a result of - * correlation. Returns empty set if no roots have been defined. - * Modifications to the set do not affect the query. - * @return the set of query roots - */ - Set> getRoots(); - - /** - * Return the selection of the query, or null if no selection - * has been set. - * @return selection item - */ - Selection getSelection(); - - /** - * Return a list of the grouping expressions. Returns empty - * list if no grouping expressions have been specified. - * Modifications to the list do not affect the query. - * @return the list of grouping expressions - */ - List> getGroupList(); - - /** - * Return the predicate that corresponds to the restriction(s) - * over the grouping items, or null if no restrictions have - * been specified. - * @return having clause predicate - */ - Predicate getGroupRestriction(); - - /** - * Return whether duplicate query results must be eliminated or - * retained. - * @return boolean indicating whether duplicate query results - * must be eliminated - */ - boolean isDistinct(); - - /** - * Return the result type of the query or subquery. If a result - * type was specified as an argument to the - * createQuery or subquery method, that - * type will be returned. If the query was created using the - * createTupleQuery method, the result type is - * Tuple. Otherwise, the result type is - * Object. - * @return result type - */ - Class getResultType(); -} ----- - -==== CriteriaQuery Interface [[a8857]] - -[source,java] ----- -package jakarta.persistence.criteria; - -import java.util.List; -import java.util.Set; - -/** - * The CriteriaQuery interface defines functionality that is specific - * to top-level queries. - * - * @param the type of the defined result - * - * @since 2.0 - */ -public interface CriteriaQuery extends AbstractQuery { - - /** - * Specify the item that is to be returned in the query result. - * Replaces the previously specified selection(s), if any. - * - *

Note: Applications using the string-based API may need to - * specify the type of the select item when it results from - * a get or join operation and the query result type is - * specified. - * - * 

-     *     For example:
-     *
-     *     CriteriaQuery<String> q = cb.createQuery(String.class);
-     *     Root<Order> order = q.from(Order.class);
-     *     q.select(order.get("shippingAddress").<String>get("state"));
-     *
-     *     CriteriaQuery<Product> q2 = cb.createQuery(Product.class);
-     *     q2.select(q2.from(Order.class)
-     *                 .join("items")
-     *                 .<Item,Product>join("product"));
-     *
-     *
- * @param selection selection specifying the item that - * is to be returned in the query result - * @return the modified query - * @throws IllegalArgumentException if the selection is - * a compound selection and more than one selection - * item has the same assigned alias - */ - CriteriaQuery select(Selection selection); - - /** - * Specify the selection items that are to be returned in the - * query result. - * Replaces the previously specified selection(s), if any. - * - * The type of the result of the query execution depends on - * the specification of the type of the criteria query object - * created as well as the arguments to the multiselect method. - *

An argument to the multiselect method must not be a tuple- - * or array-valued compound selection item. - * - *

The semantics of this method are as follows: - *

    - *
  • - * If the type of the criteria query is - * CriteriaQuery<Tuple> (i.e., a criteria - * query object created by either the - * createTupleQuery method or by passing a - * Tuple class argument to the - * createQuery method), a Tuple object - * corresponding to the arguments of the multiselect - * method, in the specified order, will be instantiated and - * returned for each row that results from the query execution. - * - *
  • If the type of the criteria query is CriteriaQuery<X> for - * some user-defined class X (i.e., a criteria query object - * created by passing a X class argument to the createQuery - * method), the arguments to the multiselect method will be - * passed to the X constructor and an instance of type X will be - * returned for each row. - * - *
  • If the type of the criteria query is CriteriaQuery<X[]> for - * some class X, an instance of type X[] will be returned for - * each row. The elements of the array will correspond to the - * arguments of the multiselect method, in the - * specified order. - * - *
  • If the type of the criteria query is CriteriaQuery<Object> - * or if the criteria query was created without specifying a - * type, and only a single argument is passed to the multiselect - * method, an instance of type Object will be returned for - * each row. - * - *
  • If the type of the criteria query is CriteriaQuery<Object> - * or if the criteria query was created without specifying a - * type, and more than one argument is passed to the multiselect - * method, an instance of type Object[] will be instantiated - * and returned for each row. The elements of the array will - * correspond to the arguments to the multiselect method, - * in the specified order. - *
- * - * @param selections selection items corresponding to the - * results to be returned by the query - * @return the modified query - * @throws IllegalArgumentException if a selection item is - * not valid or if more than one selection item has - * the same assigned alias - */ - CriteriaQuery multiselect(Selection... selections); - - - /** - * Specify the selection items that are to be returned in the - * query result. - * Replaces the previously specified selection(s), if any. - * - *

The type of the result of the query execution depends on - * the specification of the type of the criteria query object - * created as well as the argument to the multiselect method. - * An element of the list passed to the multiselect method - * must not be a tuple- or array-valued compound selection item. - * - *

The semantics of this method are as follows: - *

    - *
  • If the type of the criteria query is CriteriaQuery<Tuple> - * (i.e., a criteria query object created by either the - * createTupleQuery method or by passing a Tuple class argument - * to the createQuery method), a Tuple object corresponding to - * the elements of the list passed to the multiselect method, - * in the specified order, will be instantiated and returned for each - * row that results from the query execution. - * - *
  • If the type of the criteria query is CriteriaQuery<X> for - * some user-defined class X (i.e., a criteria query object - * created by passing a X class argument to the createQuery - * method), the elements of the list passed to the multiselect - * method will be passed to the X constructor and an instance - * of type X will be returned for each row. - * - *
  • If the type of the criteria query is CriteriaQuery<X[]> for - * some class X, an instance of type X[] will be returned for - * each row. The elements of the array will correspond to the - * elements of the list passed to the multiselect method, - * in the specified order. - * - *
  • If the type of the criteria query is CriteriaQuery<Object> - * or if the criteria query was created without specifying a - * type, and the list passed to the multiselect method contains - * only a single element, an instance of type Object will be - * returned for each row. - * - *
  • If the type of the criteria query is CriteriaQuery<Object> - * or if the criteria query was created without specifying a - * type, and the list passed to the multiselect method contains - * more than one element, an instance of type Object[] will be - * instantiated and returned for each row. The elements of the - * array will correspond to the elements of the list passed to - * the multiselect method, in the specified order. - *
- * - * @param selectionList list of selection items corresponding - * to the results to be returned by the query - * @return the modified query - * @throws IllegalArgumentException if a selection item is - * not valid or if more than one selection item has - * the same assigned alias - */ - CriteriaQuery multiselect(List> selectionList); - - /** - * Modify the query to restrict the query result according - * to the specified boolean expression. - * Replaces the previously added restriction(s), if any. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param restriction a simple or compound boolean expression - * @return the modified query - */ - CriteriaQuery where(Expression restriction); - - /** - * Modify the query to restrict the query result according - * to the conjunction of the specified restriction predicates. - * Replaces the previously added restriction(s), if any. - * If no restrictions are specified, any previously added - * restrictions are simply removed. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param restrictions zero or more restriction predicates - * @return the modified query - */ - CriteriaQuery where(Predicate... restrictions); - - /** - * Specify the expressions that are used to form groups over - * the query results. - * Replaces the previous specified grouping expressions, if any. - * If no grouping expressions are specified, any previously - * added grouping expressions are simply removed. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param grouping zero or more grouping expressions - * @return the modified query - */ - CriteriaQuery groupBy(Expression... grouping); - - /** - * Specify the expressions that are used to form groups over - * the query results. - * Replaces the previous specified grouping expressions, if any. - * If no grouping expressions are specified, any previously - * added grouping expressions are simply removed. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param grouping list of zero or more grouping expressions - * @return the modified query - */ - CriteriaQuery groupBy(List> grouping); - - /** - * Specify a restriction over the groups of the query. - * Replaces the previous having restriction(s), if any. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param restriction a simple or compound boolean expression - * @return the modified query - */ - CriteriaQuery having(Expression restriction); - - /** - * Specify restrictions over the groups of the query - * according the conjunction of the specified restriction - * predicates. - * Replaces the previously added having restriction(s), if any. - * If no restrictions are specified, any previously added - * restrictions are simply removed. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param restrictions zero or more restriction predicates - * @return the modified query - */ - CriteriaQuery having(Predicate... restrictions); - - /** - * Specify the ordering expressions that are used to - * order the query results. - * Replaces the previous ordering expressions, if any. - * If no ordering expressions are specified, the previous - * ordering, if any, is simply removed, and results will - * be returned in no particular order. - * The left-to-right sequence of the ordering expressions - * determines the precedence, whereby the leftmost has highest - * precedence. - * @param o zero or more ordering expressions - * @return the modified query - */ - CriteriaQuery orderBy(Order... o); - - /** - * Specify the ordering expressions that are used to - * order the query results. - * Replaces the previous ordering expressions, if any. - * If no ordering expressions are specified, the previous - * ordering, if any, is simply removed, and results will - * be returned in no particular order. - * The order of the ordering expressions in the list - * determines the precedence, whereby the first element in the - * list has highest precedence. - * @param o list of zero or more ordering expressions - * @return the modified query - */ - CriteriaQuery orderBy(List o); - - /** - * Specify whether duplicate query results will be eliminated. - * A true value will cause duplicates to be eliminated. - * A false value will cause duplicates to be retained. - * If distinct has not been specified, duplicate results must - * be retained. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param distinct boolean value specifying whether duplicate - * results must be eliminated from the query result or - * whether they must be retained - * @return the modified query. - */ - CriteriaQuery distinct(boolean distinct); - - /** - * Return the ordering expressions in order of precedence. - * Returns empty list if no ordering expressions have been - * specified. - * Modifications to the list do not affect the query. - * @return the list of ordering expressions - */ - List getOrderList(); -} ----- - -==== CriteriaUpdate Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -import jakarta.persistence.metamodel.SingularAttribute; -import jakarta.persistence.metamodel.EntityType; - -/** - * The CriteriaUpdate interface defines functionality for performing - * bulk update operations using the Criteria API. - * - *

Criteria API bulk update operations map directly to database update - * operations, bypassing any optimistic locking checks. Portable - * applications using bulk update operations must manually update the - * value of the version column, if desired, and/or manually validate - * the value of the version column. - * The persistence context is not synchronized with the result of the - * bulk update. - * - *

A CriteriaUpdate object must have a single root. - * - * @param the entity type that is the target of the update - * - * @since 2.1 - */ -public interface CriteriaUpdate extends CommonAbstractCriteria { - - /** - * Create and add a query root corresponding to the entity - * that is the target of the update. - * A CriteriaUpdate object has a single root, the entity that - * is being updated. - * @param entityClass the entity class - * @return query root corresponding to the given entity - */ - Root from(Class entityClass); - - /** - * Create and add a query root corresponding to the entity - * that is the target of the update. - * A CriteriaUpdate object has a single root, the entity that - * is being updated. - * @param entity metamodel entity representing the entity - * of type X - * @return query root corresponding to the given entity - */ - Root from(EntityType entity); - - /** - * Return the query root. - * @return the query root - */ - Root getRoot(); - - /** - * Update the value of the specified attribute. - * @param attribute attribute to be updated - * @param value new value - * @return the modified update query - */ - CriteriaUpdate set(SingularAttribute attribute, X value); - - /** - * Update the value of the specified attribute. - * @param attribute attribute to be updated - * @param value new value - * @return the modified update query - */ - CriteriaUpdate set(SingularAttribute attribute, Expression value); - - /** - * Update the value of the specified attribute. - * @param attribute attribute to be updated - * @param value new value - * @return the modified update query - */ - CriteriaUpdate set(Path attribute, X value); - - /** - * Update the value of the specified attribute. - * @param attribute attribute to be updated - * @param value new value - * @return the modified update query - */ - CriteriaUpdate set(Path attribute, Expression value); - - /** - * Update the value of the specified attribute. - * @param attributeName name of the attribute to be updated - * @param value new value - * @return the modified update query - */ - CriteriaUpdate set(String attributeName, Object value); - - /** - * Modify the update query to restrict the target of the update - * according to the specified boolean expression. - * Replaces the previously added restriction(s), if any. - * @param restriction a simple or compound boolean expression - * @return the modified update query - */ - CriteriaUpdate where(Expression restriction); - - /** - * Modify the update query to restrict the target of the update - * according to the conjunction of the specified restriction - * predicates. - * Replaces the previously added restriction(s), if any. - * If no restrictions are specified, any previously added - * restrictions are simply removed. - * @param restrictions zero or more restriction predicates - * @return the modified update query - */ - CriteriaUpdate where(Predicate... restrictions); -} ----- - -==== CriteriaDelete Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -import jakarta.persistence.metamodel.EntityType; - -/** - * The CriteriaDelete interface defines functionality for performing - * bulk delete operations using the Criteria API - * - *

Criteria API bulk delete operations map directly to database - * delete operations. The persistence context is not synchronized - * with the result of the bulk delete. - * - *

A CriteriaDelete object must have a single root. - * - * @param the entity type that is the target of the delete - * - * @since 2.1 - */ -public interface CriteriaDelete extends CommonAbstractCriteria { - - - /** - * Create and add a query root corresponding to the entity - * that is the target of the delete. - * A CriteriaDelete object has a single root, the entity that - * is being deleted. - * @param entityClass the entity class - * @return query root corresponding to the given entity - */ - Root from(Class entityClass); - - /** - * Create and add a query root corresponding to the entity - * that is the target of the delete. - * A CriteriaDelete object has a single root, the entity that - * is being deleted. - * @param entity metamodel entity representing the entity - * of type X - * @return query root corresponding to the given entity - */ - Root from(EntityType entity); - - /** - * Return the query root. - * @return the query root - */ - Root getRoot(); - - /** - * Modify the delete query to restrict the target of the deletion - * according to the specified boolean expression. - * Replaces the previously added restriction(s), if any. - * @param restriction a simple or compound boolean expression - * @return the modified delete query - */ - CriteriaDelete where(Expression restriction); - - /** - * Modify the delete query to restrict the target of the deletion - * according to the conjunction of the specified restriction - * predicates. - * Replaces the previously added restriction(s), if any. - * If no restrictions are specified, any previously added - * restrictions are simply removed. - * @param restrictions zero or more restriction predicates - * @return the modified delete query - */ - CriteriaDelete where(Predicate... restrictions); - -} ----- - -==== Subquery Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -import java.util.List; -import java.util.Set; - -/** - * The Subquery interface defines functionality that is - * specific to subqueries. - * - * A subquery has an expression as its selection item. - * - * @param the type of the selection item. - * - * @since 2.0 - */ -public interface Subquery extends AbstractQuery, Expression { - - /** - * Specify the item that is to be returned as the subquery - * result. - * Replaces the previously specified selection, if any. - * @param expression expression specifying the item that - * is to be returned as the subquery result - * @return the modified subquery - */ - Subquery select(Expression expression); - - /** - * Modify the subquery to restrict the result according - * to the specified boolean expression. - * Replaces the previously added restriction(s), if any. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param restriction a simple or compound boolean expression - * @return the modified subquery - */ - Subquery where(Expression restriction); - - /** - * Modify the subquery to restrict the result according - * to the conjunction of the specified restriction predicates. - * Replaces the previously added restriction(s), if any. - * If no restrictions are specified, any previously added - * restrictions are simply removed. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param restrictions zero or more restriction predicates - * @return the modified subquery - */ - Subquery where(Predicate... restrictions); - - /** - * Specify the expressions that are used to form groups over - * the subquery results. - * Replaces the previous specified grouping expressions, if any. - * If no grouping expressions are specified, any previously - * added grouping expressions are simply removed. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param grouping zero or more grouping expressions - * @return the modified subquery - */ - Subquery groupBy(Expression... grouping); - - /** - * Specify the expressions that are used to form groups over - * the subquery results. - * Replaces the previous specified grouping expressions, if any. - * If no grouping expressions are specified, any previously - * added grouping expressions are simply removed. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param grouping list of zero or more grouping expressions - * @return the modified subquery - */ - Subquery groupBy(List> grouping); - - /** - * Specify a restriction over the groups of the subquery. - * Replaces the previous having restriction(s), if any. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param restriction a simple or compound boolean expression - * @return the modified subquery - */ - Subquery having(Expression restriction); - - /** - * Specify restrictions over the groups of the subquery - * according the conjunction of the specified restriction - * predicates. - * Replaces the previously added having restriction(s), if any. - * If no restrictions are specified, any previously added - * restrictions are simply removed. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param restrictions zero or more restriction predicates - * @return the modified subquery - */ - Subquery having(Predicate... restrictions); - - /** - * Specify whether duplicate query results will be eliminated. - * A true value will cause duplicates to be eliminated. - * A false value will cause duplicates to be retained. - * If distinct has not been specified, duplicate results must - * be retained. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param distinct boolean value specifying whether duplicate - * results must be eliminated from the subquery result or - * whether they must be retained - * @return the modified subquery. - */ - Subquery distinct(boolean distinct); - - /** - * Create a subquery root correlated to a root of the - * enclosing query. - * @param parentRoot a root of the containing query - * @return subquery root - */ - Root correlate(Root parentRoot); - - /** - * Create a subquery join object correlated to a join object - * of the enclosing query. - * @param parentJoin join object of the containing query - * @return subquery join - */ - Join correlate(Join parentJoin); - - /** - * Create a subquery collection join object correlated to a - * collection join object of the enclosing query. - * @param parentCollection join object of the containing query - * @return subquery join - */ - CollectionJoin correlate(CollectionJoin parentCollection); - - /** - * Create a subquery set join object correlated to a set join - * object of the enclosing query. - * @param parentSet join object of the containing query - * @return subquery join - */ - SetJoin correlate(SetJoin parentSet); - - /** - * Create a subquery list join object correlated to a list join - * object of the enclosing query. - * @param parentList join object of the containing query - * @return subquery join - */ - ListJoin correlate(ListJoin parentList); - - /** - * Create a subquery map join object correlated to a map join - * object of the enclosing query. - * @param parentMap join object of the containing query - * @return subquery join - */ - MapJoin correlate(MapJoin parentMap); - - /** - * Return the query of which this is a subquery. - * This must be a CriteriaQuery or a Subquery. - * @return the enclosing query or subquery - */ - AbstractQuery getParent(); - - /** - * Return the query of which this is a subquery. - * This may be a CriteriaQuery, CriteriaUpdate, CriteriaDelete, - * or a Subquery. - * @return the enclosing query or subquery - * @since 2.1 - */ - CommonAbstractCriteria getContainingQuery(); - - /** - * Return the selection expression. - * @return the item to be returned in the subquery result - */ - Expression getSelection(); - - /** - * Return the correlated joins of the subquery. - * Returns empty set if the subquery has no correlated - * joins. - * Modifications to the set do not affect the query. - * @return the correlated joins of the subquery - */ - Set> getCorrelatedJoins(); - -} ----- - -==== Selection Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -import jakarta.persistence.TupleElement; -import java.util.List; - -/** - * The Selection interface defines an item that is to be - * returned in a query result. - * - * @param the type of the selection item - * - * @since 2.0 - */ -public interface Selection extends TupleElement { - - /** - * Assigns an alias to the selection item. - * Once assigned, an alias cannot be changed or reassigned. - * Returns the same selection item. - * @param name alias - * @return selection item - */ - Selection alias(String name); - - /** - * Whether the selection item is a compound selection. - * @return boolean indicating whether the selection is a compound - * selection - */ - boolean isCompoundSelection(); - - /** - * Return the selection items composing a compound selection. - * Modifications to the list do not affect the query. - * @return list of selection items - * @throws IllegalStateException if selection is not a - * compound selection - */ - List> getCompoundSelectionItems(); -} ----- - -==== CompoundSelection Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -/** - * The CompoundSelection interface defines a compound selection item - * (tuple, array, or result of constructor). - * - * @param the type of the selection item - * - * @since 2.0 - */ -public interface CompoundSelection extends Selection {} ----- - -==== Expression Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -import java.util.Collection; - -/** - * Type for query expressions. - * - * @param the type of the expression - * - * @since 2.0 - */ -public interface Expression extends Selection { - - /** - * Create a predicate to test whether the expression is null. - * @return predicate testing whether the expression is null - */ - Predicate isNull(); - - /** - * Create a predicate to test whether the expression is - * not null. - * @return predicate testing whether the expression is not null - */ - Predicate isNotNull(); - - /** - * Create a predicate to test whether the expression is equal to - * the argument. - * @param value expression to be tested against - * @return predicate testing for equality - */ - Predicate equalTo(Expression value); - - /** - * Create a predicate to test whether the expression is equal to - * the argument. - * @param value value to be tested against - * @return predicate testing for equality - */ - Predicate equalTo(Object value); - - /** - * Create a predicate to test whether the expression is unequal - * to the argument. - * @param value expression to be tested against - * @return predicate testing for inequality - */ - Predicate notEqualTo(Expression value); - - /** - * Create a predicate to test whether the expression is unequal - * to the argument. - * @param value value to be tested against - * @return predicate testing for inequality - */ - Predicate notEqualTo(Object value); - - /** - * Create a predicate to test whether the expression is a member - * of the argument list. - * @param values values to be tested against - * @return predicate testing for membership - */ - Predicate in(Object... values); - - /** - * Create a predicate to test whether the expression is a member - * of the argument list. - * @param values expressions to be tested against - * @return predicate testing for membership - */ - Predicate in(Expression... values); - - /** - * Create a predicate to test whether the expression is a member - * of the collection. - * @param values collection of values to be tested against - * @return predicate testing for membership - */ - Predicate in(Collection values); - - /** - * Create a predicate to test whether the expression is a member - * of the collection. - * @param values expression corresponding to collection to be - * tested against - * @return predicate testing for membership - */ - Predicate in(Expression> values); - - /** - * Perform a typecast upon the expression, returning a new - * expression object. - * This method does not cause type conversion: - * the runtime type is not changed. - * Warning: may result in a runtime failure. - * @param type intended type of the expression - * @return new expression of the given type - */ - Expression as(Class type); -} ----- - -==== Predicate Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -import java.util.List; - -/** - * The type of a simple or compound predicate: a conjunction or - * disjunction of restrictions. - * A simple predicate is considered to be a conjunction with a - * single conjunct. - * - * @since 2.0 - */ -public interface Predicate extends Expression { - - public static enum BooleanOperator { - AND, OR - } - - /** - * Return the boolean operator for the predicate. - * If the predicate is simple, this is AND. - * @return boolean operator for the predicate - */ - BooleanOperator getOperator(); - - /** - * Whether the predicate has been created from another - * predicate by applying the Predicate.not() method - * or the CriteriaBuilder.not() method. - * @return boolean indicating if the predicate is - * a negated predicate - */ - boolean isNegated(); - - /** - * Return the top-level conjuncts or disjuncts of the predicate. - * Returns empty list if there are no top-level conjuncts or - * disjuncts of the predicate. - * Modifications to the list do not affect the query. - * @return list of boolean expressions forming the predicate - */ - List> getExpressions(); - - /** - * Create a negation of the predicate. - * @return negated predicate - */ - Predicate not(); - -} ----- - -==== Path Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -import jakarta.persistence.metamodel.PluralAttribute; -import jakarta.persistence.metamodel.SingularAttribute; -import jakarta.persistence.metamodel.Bindable; -import jakarta.persistence.metamodel.MapAttribute; - -/** - * Represents a simple or compound attribute path from a - * bound type or collection, and is a "primitive" expression. - * - * @param the type referenced by the path - * - * @since 2.0 - */ -public interface Path extends Expression { - - /** - * Return the bindable object that corresponds to the - * path expression. - * @return bindable object corresponding to the path - */ - Bindable getModel(); - - /** - * Return the parent "node" in the path or null if no parent. - * @return parent - */ - Path getParentPath(); - - /** - * Create a path corresponding to the referenced - * single-valued attribute. - * @param attribute single-valued attribute - * @return path corresponding to the referenced attribute - */ - Path get(SingularAttribute attribute); - - /** - * Create a path corresponding to the referenced - * collection-valued attribute. - * @param collection collection-valued attribute - * @return expression corresponding to the referenced attribute - */ - > Expression get(PluralAttribute collection); - - /** - * Create a path corresponding to the referenced - * map-valued attribute. - * @param map map-valued attribute - * @return expression corresponding to the referenced attribute - */ - > Expression get(MapAttribute map); - - /** - * Create an expression corresponding to the type of the path. - * @return expression corresponding to the type of the path - */ - Expression> type(); - - - //String-based: - - /** - * Create a path corresponding to the referenced attribute. - * - *

Note: Applications using the string-based API may need to - * specify the type resulting from the get operation in order - * to avoid the use of Path variables. - * - * 

-     *     For example:
-     *
-     *     CriteriaQuery<Person> q = cb.createQuery(Person.class);
-     *     Root<Person> p = q.from(Person.class);
-     *     q.select(p)
-     *      .where(cb.isMember("joe",
-     *                         p.<Set<String>>get("nicknames")));
-     *
-     *     rather than:
-     *
-     *     CriteriaQuery<Person> q = cb.createQuery(Person.class);
-     *     Root<Person> p = q.from(Person.class);
-     *     Path<Set<String>> nicknames = p.get("nicknames");
-     *     q.select(p)
-     *      .where(cb.isMember("joe", nicknames));
-     *
- * - * @param attributeName name of the attribute - * @return path corresponding to the referenced attribute - * @throws IllegalStateException if invoked on a path that - * corresponds to a basic type - * @throws IllegalArgumentException if attribute of the given - * name does not otherwise exist - */ - Path get(String attributeName); -} ----- - -==== FetchParent Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -import jakarta.persistence.metamodel.PluralAttribute; -import jakarta.persistence.metamodel.SingularAttribute; - -/** - * Represents an element of the from clause which may - * function as the parent of Fetches. - * - * @param the source type - * @param the target type - * - * @since 2.0 - */ -public interface FetchParent { - - /** - * Return the fetch joins that have been made from this type. - * Returns empty set if no fetch joins have been made from - * this type. - * Modifications to the set do not affect the query. - * @return fetch joins made from this type - */ - java.util.Set> getFetches(); - - /** - * Create a fetch join to the specified single-valued attribute - * using an inner join. - * @param attribute target of the join - * @return the resulting fetch join - */ - Fetch fetch(SingularAttribute attribute); - - /** - * Create a fetch join to the specified single-valued attribute - * using the given join type. - * @param attribute target of the join - * @param jt join type - * @return the resulting fetch join - */ - Fetch fetch(SingularAttribute attribute, JoinType jt); - - /** - * Create a fetch join to the specified collection-valued - * attribute using an inner join. - * @param attribute target of the join - * @return the resulting join - */ - Fetch fetch(PluralAttribute attribute); - - /** - * Create a fetch join to the specified collection-valued - * attribute using the given join type. - * @param attribute target of the join - * @param jt join type - * @return the resulting join - */ - Fetch fetch(PluralAttribute attribute, JoinType jt); - - - //String-based: - - /** - * Create a fetch join to the specified attribute using an - * inner join. - * @param attributeName name of the attribute for the - * target of the join - * @return the resulting fetch join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - @SuppressWarnings("hiding") - Fetch fetch(String attributeName); - - /** - * Create a fetch join to the specified attribute using - * the given join type. - * @param attributeName name of the attribute for the - * target of the join - * @param jt join type - * @return the resulting fetch join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - @SuppressWarnings("hiding") - Fetch fetch(String attributeName, JoinType jt); -} ----- - -==== Fetch Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -import jakarta.persistence.metamodel.Attribute; - -/** - * Represents a join-fetched association or attribute. - * - * @param the source type of the fetch - * @param the target type of the fetch - * - * @since 2.0 - */ -public interface Fetch extends FetchParent { - - /** - * Return the metamodel attribute corresponding to the - * fetch join. - * @return metamodel attribute for the join - */ - Attribute getAttribute(); - - /** - * Return the parent of the fetched item. - * @return fetch parent - */ - FetchParent getParent(); - - /** - * Return the join type used in the fetch join. - * @return join type - */ - JoinType getJoinType(); -} ----- - -==== From Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -import jakarta.persistence.metamodel.SingularAttribute; -import jakarta.persistence.metamodel.CollectionAttribute; -import jakarta.persistence.metamodel.ListAttribute; -import jakarta.persistence.metamodel.MapAttribute; -import jakarta.persistence.metamodel.SetAttribute; -import java.util.Set; - -/** - * Represents a bound type, usually an entity that appears in - * the from clause, but may also be an embeddable belonging to - * an entity in the from clause. - *

Serves as a factory for Joins of associations, embeddables, and - * collections belonging to the type, and for Paths of attributes - * belonging to the type. - * - * @param the source type - * @param the target type - * - * @since 2.0 - */ -@SuppressWarnings("hiding") -public interface From extends Path, FetchParent { - - /** - * Return the joins that have been made from this bound type. - * Returns empty set if no joins have been made from this - * bound type. - * Modifications to the set do not affect the query. - * @return joins made from this type - */ - Set> getJoins(); - - /** - * Whether the From object has been obtained as a result of - * correlation (use of a Subquery correlate - * method). - * @return boolean indicating whether the object has been - * obtained through correlation - */ - boolean isCorrelated(); - - /** - * Returns the parent From object from which the correlated - * From object has been obtained through correlation (use - * of a Subquery correlate method). - * @return the parent of the correlated From object - * @throws IllegalStateException if the From object has - * not been obtained through correlation - */ - From getCorrelationParent(); - - /** - * Create an inner join to the specified single-valued - * attribute. - * @param attribute target of the join - * @return the resulting join - */ - Join join(SingularAttribute attribute); - - /** - * Create a join to the specified single-valued attribute - * using the given join type. - * @param attribute target of the join - * @param jt join type - * @return the resulting join - */ - Join join(SingularAttribute attribute, JoinType jt); - - /** - * Create an inner join to the specified Collection-valued - * attribute. - * @param collection target of the join - * @return the resulting join - */ - CollectionJoin join(CollectionAttribute collection); - - /** - * Create an inner join to the specified Set-valued attribute. - * @param set target of the join - * @return the resulting join - */ - SetJoin join(SetAttribute set); - - /** - * Create an inner join to the specified List-valued attribute. - * @param list target of the join - * @return the resulting join - */ - ListJoin join(ListAttribute list); - - /** - * Create an inner join to the specified Map-valued attribute. - * @param map target of the join - * @return the resulting join - */ - MapJoin join(MapAttribute map); - - /** - * Create a join to the specified Collection-valued attribute - * using the given join type. - * @param collection target of the join - * @param jt join type - * @return the resulting join - */ - CollectionJoin join(CollectionAttribute collection, JoinType jt); - - /** - * Create a join to the specified Set-valued attribute using - * the given join type. - * @param set target of the join - * @param jt join type - * @return the resulting join - */ - SetJoin join(SetAttribute set, JoinType jt); - - /** - * Create a join to the specified List-valued attribute using - * the given join type. - * @param list target of the join - * @param jt join type - * @return the resulting join - */ - ListJoin join(ListAttribute list, JoinType jt); - - /** - * Create a join to the specified Map-valued attribute using - * the given join type. - * @param map target of the join - * @param jt join type - * @return the resulting join - */ - MapJoin join(MapAttribute map, JoinType jt); - - - //String-based: - - /** - * Create an inner join to the specified attribute. - * @param attributeName name of the attribute for the - * target of the join - * @return the resulting join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - Join join(String attributeName); - - /** - * Create an inner join to the specified Collection-valued - * attribute. - * @param attributeName name of the attribute for the - * target of the join - * @return the resulting join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - CollectionJoin joinCollection(String attributeName); - - /** - * Create an inner join to the specified Set-valued attribute. - * @param attributeName name of the attribute for the - * target of the join - * @return the resulting join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - SetJoin joinSet(String attributeName); - - /** - * Create an inner join to the specified List-valued attribute. - * @param attributeName name of the attribute for the - * target of the join - * @return the resulting join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - ListJoin joinList(String attributeName); - - /** - * Create an inner join to the specified Map-valued attribute. - * @param attributeName name of the attribute for the - * target of the join - * @return the resulting join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - MapJoin joinMap(String attributeName); - - /** - * Create a join to the specified attribute using the given - * join type. - * @param attributeName name of the attribute for the - * target of the join - * @param jt join type - * @return the resulting join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - Join join(String attributeName, JoinType jt); - - /** - * Create a join to the specified Collection-valued attribute - * using the given join type. - * @param attributeName name of the attribute for the - * target of the join - * @param jt join type - * @return the resulting join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - CollectionJoin joinCollection(String attributeName, JoinType jt); - - /** - * Create a join to the specified Set-valued attribute using - * the given join type. - * @param attributeName name of the attribute for the - * target of the join - * @param jt join type - * @return the resulting join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - SetJoin joinSet(String attributeName, JoinType jt); - - /** - * Create a join to the specified List-valued attribute using - * the given join type. - * @param attributeName name of the attribute for the - * target of the join - * @param jt join type - * @return the resulting join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - ListJoin joinList(String attributeName, JoinType jt); - - /** - * Create a join to the specified Map-valued attribute using - * the given join type. - * @param attributeName name of the attribute for the - * target of the join - * @param jt join type - * @return the resulting join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - MapJoin joinMap(String attributeName, JoinType jt); -} ----- - -==== Root Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -import jakarta.persistence.metamodel.EntityType; - -/** - * A root type in the from clause. - * Query roots always reference entities. - * - * @param the entity type referenced by the root - * - * @since 2.0 - */ -public interface Root extends From { - - /** - * Return the metamodel entity corresponding to the root. - * @return metamodel entity corresponding to the root - */ - EntityType getModel(); -} ----- - -==== Join Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -import jakarta.persistence.metamodel.Attribute; - -/** - * A join to an entity, embeddable, or basic type. - * - * @param the source type of the join - * @param the target type of the join - * - * @since 2.0 - */ -public interface Join extends From { - - /** - * Modify the join to restrict the result according to the - * specified ON condition and return the join object. - * Replaces the previous ON condition, if any. - * @param restriction a simple or compound boolean expression - * @return the modified join object - * @since 2.1 - */ - Join on(Expression restriction); - - /** - * Modify the join to restrict the result according to the - * specified ON condition and return the join object. - * Replaces the previous ON condition, if any. - * @param restrictions zero or more restriction predicates - * @return the modified join object - * @since 2.1 - */ - Join on(Predicate... restrictions); - - /** - * Return the predicate that corresponds to the ON - * restriction(s) on the join, or null if no ON condition - * has been specified. - * @return the ON restriction predicate - * @since 2.1 - */ - Predicate getOn(); - - /** - * Return the metamodel attribute corresponding to the join. - * @return metamodel attribute corresponding to the join - */ - Attribute getAttribute(); - - /** - * Return the parent of the join. - * @return join parent - */ - From getParent(); - - /** - * Return the join type. - * @return join type - */ - JoinType getJoinType(); -} ----- - -==== JoinType - -[source,java] ----- -package jakarta.persistence.criteria; - -/** - * Defines the three types of joins. - * - * Right outer joins and right outer fetch joins are not required - * to be supported. Applications that use RIGHT join - * types will not be portable. - * - * @since 2.0 - */ -public enum JoinType { - - /** Inner join. */ - INNER, - - /** Left outer join. */ - LEFT, - - /** Right outer join. */ - RIGHT -} ----- - -==== PluralJoin Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -import jakarta.persistence.metamodel.PluralAttribute; - -/** - * The PluralJoin interface defines functionality - * that is common to joins to all collection types. It is - * not intended to be used directly in query construction. - * - * @param the source type - * @param the collection type - * @param the element type of the collection - * - * @since 2.0 - */ -public interface PluralJoin extends Join { - - /** - * Return the metamodel representation for the collection-valued - * attribute corresponding to the join. - * @return metamodel collection-valued attribute corresponding - * to the target of the join - */ - PluralAttribute getModel(); -} ----- - -==== CollectionJoin Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -import java.util.Collection; -import jakarta.persistence.metamodel.CollectionAttribute; - -/** - * The CollectionJoin interface is the type of the result of - * joining to a collection over an association or element - * collection that has been specified as a java.util.Collection. - * - * @param the source type of the join - * @param the element type of the target Collection - * - * @since 2.0 - */ -public interface CollectionJoin - extends PluralJoin, E> { - - /** - * Modify the join to restrict the result according to the - * specified ON condition and return the join object. - * Replaces the previous ON condition, if any. - * @param restriction a simple or compound boolean expression - * @return the modified join object - * @since 2.1 - */ - CollectionJoin on(Expression restriction); - - /** - * Modify the join to restrict the result according to the - * specified ON condition and return the join object. - * Replaces the previous ON condition, if any. - * @param restrictions zero or more restriction predicates - * @return the modified join object - * @since 2.1 - */ - CollectionJoin on(Predicate... restrictions); - - /** - * Return the metamodel representation for the collection - * attribute. - * @return metamodel type representing the Collection that is - * the target of the join - */ - CollectionAttribute getModel(); -} ----- - -==== SetJoin Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -import java.util.Set; -import jakarta.persistence.metamodel.SetAttribute; - -/** - * The SetJoin interface is the type of the result of - * joining to a collection over an association or element - * collection that has been specified as a java.util.Set. - * - * @param the source type of the join - * @param the element type of the target Set - * - * @since 2.0 - */ -public interface SetJoin extends PluralJoin, E> { - - /** - * Modify the join to restrict the result according to the - * specified ON condition and return the join object. - * Replaces the previous ON condition, if any. - * @param restriction a simple or compound boolean expression - * @return the modified join object - * @since 2.1 - */ - SetJoin on(Expression restriction); - - /** - * Modify the join to restrict the result according to the - * specified ON condition and return the join object. - * Replaces the previous ON condition, if any. - * @param restrictions zero or more restriction predicates - * @return the modified join object - * @since 2.1 - */ - SetJoin on(Predicate... restrictions); - - /** - * Return the metamodel representation for the set attribute. - * @return metamodel type representing the Set that is - * the target of the join - */ - SetAttribute getModel(); -} ----- - -==== ListJoin Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -import java.util.List; -import jakarta.persistence.metamodel.ListAttribute; - -/** - * The ListJoin interface is the type of the result of - * joining to a collection over an association or element - * collection that has been specified as a java.util.List. - * - * @param the source type of the join - * @param the element type of the target List - * - * @since 2.0 - */ -public interface ListJoin - extends PluralJoin, E> { - - /** - * Modify the join to restrict the result according to the - * specified ON condition and return the join object. - * Replaces the previous ON condition, if any. - * @param restriction a simple or compound boolean expression - * @return the modified join object - * @since 2.1 - */ - ListJoin on(Expression restriction); - - /** - * Modify the join to restrict the result according to the - * specified ON condition and return the join object. - * Replaces the previous ON condition, if any. - * @param restrictions zero or more restriction predicates - * @return the modified join object - * @since 2.1 - */ - ListJoin on(Predicate... restrictions); - - /** - * Return the metamodel representation for the list attribute. - * @return metamodel type representing the List that is - * the target of the join - */ - ListAttribute getModel(); - - /** - * Create an expression that corresponds to the index of - * the object in the referenced association or element - * collection. - * This method must only be invoked upon an object that - * represents an association or element collection for - * which an order column has been defined. - * @return expression denoting the index - */ - Expression index(); -} ----- - -==== MapJoin Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -import java.util.Map; -import jakarta.persistence.metamodel.MapAttribute; - -/** - * The MapJoin interface is the type of the result of - * joining to a collection over an association or element - * collection that has been specified as a java.util.Map. - * - * @param the source type of the join - * @param the type of the target Map key - * @param the type of the target Map value - * - * @since 2.0 - */ -public interface MapJoin - extends PluralJoin, V> { - - /** - * Modify the join to restrict the result according to the - * specified ON condition and return the join object. - * Replaces the previous ON condition, if any. - * @param restriction a simple or compound boolean expression - * @return the modified join object - * @since 2.1 - */ - MapJoin on(Expression restriction); - - /** - * Modify the join to restrict the result according to the - * specified ON condition and return the join object. - * Replaces the previous ON condition, if any. - * @param restrictions zero or more restriction predicates - * @return the modified join object - * @since 2.1 - */ - MapJoin on(Predicate... restrictions); - - /** - * Return the metamodel representation for the map attribute. - * @return metamodel type representing the Map that is - * the target of the join - */ - MapAttribute getModel(); - - /** - * Create a path expression that corresponds to the map key. - * @return path corresponding to map key - */ - Path key(); - - /** - * Create a path expression that corresponds to the map value. - * This method is for stylistic use only: it just returns this. - * @return path corresponding to the map value - */ - Path value(); - - /** - * Create an expression that corresponds to the map entry. - * @return expression corresponding to the map entry - */ - Expression> entry(); -} ----- - -==== Order Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -/** - * An object that defines an ordering over the query results. - * - * @since 2.0 - */ -public interface Order { - - /** - * Switch the ordering. - * @return a new Order instance with the reversed ordering - */ - Order reverse(); - - /** - * Whether ascending ordering is in effect. - * @return boolean indicating whether ordering is ascending - */ - boolean isAscending(); - - /** - * Return the expression that is used for ordering. - * @return expression used for ordering - */ - Expression getExpression(); -} ----- - -==== ParameterExpression Interface - -[source,java] ----- -package jakarta.persistence.criteria; - -import jakarta.persistence.Parameter; - -/** - * Type of criteria query parameter expressions. - * - * @param the type of the parameter expression - * - * @since 2.0 - */ -public interface ParameterExpression extends Parameter, Expression {} ----- +The complete criteria query API may be found in <>. === Criteria Query API Usage [[a10608]] @@ -3883,8 +122,8 @@ CriteriaQuery createQuery(); Methods for the creation of update and delete queries are described in <>. -The methods CriteriaQuery -createQuery(Class resultClass) and `createTupleQuery` provide for +The methods ` CriteriaQuery +createQuery(Class resultClass)` and `createTupleQuery` provide for typing of criteria query results and for typesafe query execution using the `TypedQuery` API. @@ -3894,7 +133,7 @@ is semantically equivalent to invoking the `createQuery` method with the multiple selection items in a strongly typed manner. See <> and <>. -The CriteriaQuery createQuery() +The `CriteriaQuery createQuery()` method supports both the case where the `select` or `multiselect` method specifies only a single selection item and where the `multiselect` method specifies multiple selection items. If only a single item is diff --git a/spec/src/main/asciidoc/ch07-entitymanagers-and-persistence-contexts.adoc b/spec/src/main/asciidoc/ch07-entitymanagers-and-persistence-contexts.adoc index 3f4143c9..777eceaa 100644 --- a/spec/src/main/asciidoc/ch07-entitymanagers-and-persistence-contexts.adoc +++ b/spec/src/main/asciidoc/ch07-entitymanagers-and-persistence-contexts.adoc @@ -231,285 +231,7 @@ by the persistence provider and to the `PersistenceUnitUtil` interface. The `Cache` interface is described in <>; the `PersistenceUnitUtil` interface in <>. -[source,java] ----- -package jakarta.persistence; - -import java.util.Map; -import jakarta.persistence.metamodel.Metamodel; -import jakarta.persistence.criteria.CriteriaBuilder; - -/** - * Interface used to interact with the entity manager factory - * for the persistence unit. - * - *

When the application has finished using the entity manager - * factory, and/or at application shutdown, the application should - * close the entity manager factory. Once an - * EntityManagerFactory has been closed, all its entity managers - * are considered to be in the closed state. - * - * @since 1.0 - */ -public interface EntityManagerFactory extends AutoCloseable { - - /** - * Create a new application-managed EntityManager. - * This method returns a new EntityManager instance each time - * it is invoked. - * The isOpen method will return true on the returned instance. - * @return entity manager instance - * @throws IllegalStateException if the entity manager factory - * has been closed - */ - public EntityManager createEntityManager(); - - /** - * Create a new application-managed EntityManager with the - * specified Map of properties. - * This method returns a new EntityManager instance each time - * it is invoked. - * The isOpen method will return true on the returned instance. - * @param map properties for entity manager - * @return entity manager instance - * @throws IllegalStateException if the entity manager factory - * has been closed - */ - public EntityManager createEntityManager(Map map); - - /** - * Create a new JTA application-managed EntityManager with the - * specified synchronization type. - * This method returns a new EntityManager instance each time - * it is invoked. - * The isOpen method will return true on the returned instance. - * @param synchronizationType how and when the entity manager should be - * synchronized with the current JTA transaction - * @return entity manager instance - * @throws IllegalStateException if the entity manager factory - * has been configured for resource-local entity managers or is closed - * - * @since 2.1 - */ - public EntityManager createEntityManager(SynchronizationType synchronizationType); - - /** - * Create a new JTA application-managed EntityManager with the - * specified synchronization type and map of properties. - * This method returns a new EntityManager instance each time - * it is invoked. - * The isOpen method will return true on the returned instance. - * @param synchronizationType how and when the entity manager should be - * synchronized with the current JTA transaction - * @param map properties for entity manager - * @return entity manager instance - * @throws IllegalStateException if the entity manager factory - * has been configured for resource-local entity managers or is closed - * - * @since 2.1 - */ - public EntityManager createEntityManager(SynchronizationType synchronizationType, Map map); - - /** - * Return an instance of CriteriaBuilder for the creation of - * CriteriaQuery objects. - * @return CriteriaBuilder instance - * @throws IllegalStateException if the entity manager factory - * has been closed - * - * @since 2.0 - */ - public CriteriaBuilder getCriteriaBuilder(); - - /** - * Return an instance of Metamodel interface for access to the - * metamodel of the persistence unit. - * @return Metamodel instance - * @throws IllegalStateException if the entity manager factory - * has been closed - * - * @since 2.0 - */ - public Metamodel getMetamodel(); - - /** - * Indicates whether the factory is open. Returns true - * until the factory has been closed. - * @return boolean indicating whether the factory is open - */ - public boolean isOpen(); - - /** - * Close the factory, releasing any resources that it holds. - * After a factory instance has been closed, all methods invoked - * on it will throw the IllegalStateException, except - * for isOpen, which will return false. Once an - * EntityManagerFactory has been closed, all its - * entity managers are considered to be in the closed state. - * @throws IllegalStateException if the entity manager factory - * has been closed - */ - public void close(); - - /** - * The name of the persistence unit. - * - * @since 3.2 - */ - public String getName(); - - /** - * Get the properties and associated values that are in effect - * for the entity manager factory. Changing the contents of the - * map does not change the configuration in effect. - * @return properties - * @throws IllegalStateException if the entity manager factory - * has been closed - * - * @since 2.0 - */ - public Map getProperties(); - - /** - * Access the cache that is associated with the entity manager - * factory (the "second level cache"). - * @return instance of the Cache interface or null if - * no cache is in use - * @throws IllegalStateException if the entity manager factory - * has been closed - * - * @since 2.0 - */ - public Cache getCache(); - - /** - * Return interface providing access to utility methods - * for the persistence unit. - * @return PersistenceUnitUtil interface - * @throws IllegalStateException if the entity manager factory - * has been closed - * - * @since 2.0 - */ - public PersistenceUnitUtil getPersistenceUnitUtil(); - - /** - * Return interface providing access to schema management - * operations for the persistence unit. - * @return SchemaManager interface - * @throws IllegalStateException if the entity manager factory - * has been closed - * - * @since 3.2 - */ - public SchemaManager getSchemaManager(); - - /** - * Define the query, typed query, or stored procedure query as - * a named query such that future query objects can be created - * from it using the createNamedQuery or - * createNamedStoredProcedureQuery method. - *

Any configuration of the query object (except for actual - * parameter binding) in effect when the named query is added - * is retained as part of the named query definition. - * This includes configuration information such as max results, - * hints, flush mode, lock mode, result set mapping information, - * and information about stored procedure parameters. - *

When the query is executed, information that can be set - * by means of the query APIs can be overridden. Information - * that is overridden does not affect the named query as - * registered with the entity manager factory, and thus does - * not affect subsequent query objects created from it by - * means of the createNamedQuery or - * createNamedStoredProcedureQuery method. - *

If a named query of the same name has been previously - * defined, either statically via metadata or via this method, - * that query definition is replaced. - * - * @param name name for the query - * @param query Query, TypedQuery, or StoredProcedureQuery object - * - * @since 2.1 - */ - public void addNamedQuery(String name, Query query); - - /** - * Return an object of the specified type to allow access to the - * provider-specific API. If the provider's EntityManagerFactory - * implementation does not support the specified class, the - * PersistenceException is thrown. - * @param cls the class of the object to be returned. This is - * normally either the underlying EntityManagerFactory - * implementation class or an interface that it implements. - * @return an instance of the specified class - * @throws PersistenceException if the provider does not - * support the call - * @since 2.1 - */ - public T unwrap(Class cls); - - /** - * Add a named copy of the EntityGraph to the - * EntityManagerFactory. If an entity graph with the same name - * already exists, it is replaced. - * @param graphName name for the entity graph - * @param entityGraph entity graph - * @since 2.1 - */ - public void addNamedEntityGraph(String graphName, EntityGraph entityGraph); - - /** - * Create a new application-managed {@code EntityManager} with an active - * transaction, and execute the given function, passing the {@code EntityManager} - * to the function. - *

- * If the transaction type of the persistence unit is JTA, and there is a JTA - * transaction already associated with the caller, then the {@code EntityManager} - * is associated with this current transaction. If the given function throws an - * exception, the JTA transaction is marked for rollback, and the exception is - * rethrown. - *

- * Otherwise, if the transaction type of the persistence unit is resource-local, - * or if there is no JTA transaction already associated with the caller, then - * the {@code EntityManager} is associated with a new transaction. If the given - * function returns without throwing an exception, this transaction is committed. - * If the function does throw an exception, the transaction is rolled back, and - * the exception is rethrown. - *

- * Finally, the {@code EntityManager} is closed before this method returns - * control to the client. - * - * @param work a function to be executed in the scope of the transaction - */ - public void runInTransaction(Consumer work); - /** - * Create a new application-managed {@code EntityManager} with an active - * transaction, and call the given function, passing the {@code EntityManager} - * to the function. - *

- * If the transaction type of the persistence unit is JTA, and there is a JTA - * transaction already associated with the caller, then the {@code EntityManager} - * is associated with this current transaction. If the given function returns - * without throwing an exception, the result of the function is returned. If the - * given function throws an exception, the JTA transaction is marked for rollback, - * and the exception is rethrown. - *

- * Otherwise, if the transaction type of the persistence unit is resource-local, - * or if there is no JTA transaction already associated with the caller, then - * the {@code EntityManager} is associated with a new transaction. If the given - * function returns without throwing an exception, this transaction is committed - * and the result of the function is returned. If the function does throw an - * exception, the transaction is rolled back, and the exception is rethrown. - *

- * Finally, the {@code EntityManager} is closed before this method returns - * control to the client. - * - * @param work a function to be called in the scope of the transaction - * @return the value returned by the given function - */ - public R callInTransaction(Function work); -} ----- +This interface may be found in <<_entitymanagerfactory_>>. Any number of vendor-specific properties may be included in the map passed to the `createEntityManager` methods. @@ -592,83 +314,7 @@ transaction for rollback. If the `EntityTransaction.commit` operation fails, the persistence provider must roll back the transaction. -[source,java] ----- -package jakarta.persistence; - -/** - * Interface used to control transactions on resource-local entity - * managers. The {@link EntityManager#getTransaction - * EntityManager.getTransaction()} method returns the - * EntityTransaction interface. - * - * @since 1.0 - */ -public interface EntityTransaction { - - /** - * Start a resource transaction. - * @throws IllegalStateException if isActive() is true - */ - public void begin(); - - /** - * Commit the current resource transaction, writing any - * unflushed changes to the database. - * @throws IllegalStateException if isActive() is false - * @throws RollbackException if the commit fails - */ - public void commit(); - - /** - * Roll back the current resource transaction. - * @throws IllegalStateException if isActive() is false - * @throws PersistenceException if an unexpected error - * condition is encountered - */ - public void rollback(); - - /** - * Mark the current resource transaction so that the only - * possible outcome of the transaction is for the transaction - * to be rolled back. - * @throws IllegalStateException if isActive() is false - */ - public void setRollbackOnly(); - - /** - * Determine whether the current resource transaction has been - * marked for rollback. - * @return boolean indicating whether the transaction has been - * marked for rollback - * @throws IllegalStateException if isActive() is false - */ - public boolean getRollbackOnly(); - - /** - * Indicate whether a resource transaction is in progress. - * @return boolean indicating whether transaction is - * in progress - * @throws PersistenceException if an unexpected error - * condition is encountered - */ - public boolean isActive(); - - /** - * Set the transaction timeout, in seconds. This is a hint. - * @param timeout the timeout, in seconds, or null to indicate - * that the database server should set the timeout - * @since 3.2 - */ - void setTimeout(Integer timeout); - - /** - * The transaction timeout. - * @since 3.2 - */ - Integer getTimeout(); -} ----- +This interface may be found in <<_entitytransaction_>>. The following example illustrates the creation of an entity manager factory in a Java SE environment, and its @@ -1473,171 +1119,7 @@ are invoked on an entity instance that is not associated with the persistence unit from whose entity manager factory this interface has been obtained. -[source,java] ----- -package jakarta.persistence; - -import jakarta.persistence.metamodel.Attribute; - -/** - * Utility interface between the application and the persistence - * provider managing the persistence unit. - * - *

The methods of this interface should only be invoked on entity - * instances obtained from or managed by entity managers for this - * persistence unit or on new entity instances. - * - * @since 2.0 - */ -public interface PersistenceUnitUtil extends PersistenceUtil { - - /** - * Determine the load state of a given persistent attribute - * of an entity belonging to the persistence unit. - * @param entity entity instance containing the attribute - * @param attributeName name of attribute whose load state is - * to be determined - * @return false if entity's state has not been loaded or if - * the attribute state has not been loaded, else true - */ - public boolean isLoaded(Object entity, String attributeName); - - /** - * Determine the load state of a given persistent attribute - * of an entity belonging to the persistence unit. - * @param entity entity instance containing the attribute - * @param attribute attribute whose load state is to be determined - * @return false if entity's state has not been loaded or if - * the attribute state has not been loaded, else true - * @since 3.2 - */ - public boolean isLoaded(E entity, Attribute attribute); - - /** - * Determine the load state of an entity belonging to the - * persistence unit. This method can be used to determine the - * load state of an entity passed as a reference. An entity is - * considered loaded if all attributes for which - * FetchType.EAGER has been specified have been - * loaded. - *

The isLoaded(Object, String) method - * should be used to determine the load state of an attribute. - * Not doing so might lead to unintended loading of state. - * @param entity entity instance whose load state is to be determined - * @return false if the entity has not been loaded, else true - */ - public boolean isLoaded(Object entity); - - /** - * Load the persistent value of a given persistent attribute - * of an entity belonging to the persistence unit and to an - * open persistence context. - * After this method returns, {@link #isLoaded(Object,String)} - * must return true with the given entity instance and attribute. - * @param entity entity instance - * @param attributeName the name of the attribute to be loaded - * @throws IllegalArgumentException if the given object is not an - * instance of an entity class belonging to the persistence unit - * @throws PersistenceException if the entity is not associated - * with an open persistence context or cannot be loaded from the - * database - * @since 3.2 - */ - public void load(Object entity, String attributeName); - - /** - * Load the persistent value of a given persistent attribute - * of an entity belonging to the persistence unit and to an - * open persistence context. - * After this method returns, {@link #isLoaded(Object,Attribute)} - * must return true with the given entity instance and attribute. - * @param entity entity instance to be loaded - * @param attribute the attribute to be loaded - * @throws IllegalArgumentException if the given object is not an - * instance of an entity class belonging to the persistence unit - * @throws PersistenceException if the entity is not associated - * with an open persistence context or cannot be loaded from the - * database - * @since 3.2 - */ - public void load(E entity, Attribute attribute); - - /** - * Load the persistent state of an entity belonging to the - * persistence unit and to an open persistence context. - * After this method returns, {@link #isLoaded(Object)} must - * return true with the given entity instance. - * @param entity entity instance to be loaded - * @throws IllegalArgumentException if the given object is not an - * instance of an entity class belonging to the persistence unit - * @throws PersistenceException if the entity is not associated - * with an open persistence context or cannot be loaded from the - * database - * @since 3.2 - */ - public void load(Object entity); - - /** - * Return true if the given entity belonging to the persistence - * unit and to an open persistence context is an instance of the - * given entity class, or false otherwise. This method may, but - * is not required to, load the given entity by side effect. - * @param entity entity instance - * @param entityClass an entity class belonging to the persistence - * unit - * @throws IllegalArgumentException if the given object is not an - * instance of an entity class belonging to the persistence unit - * or if the given class is not an entity class belonging to the - * persistence unit - * @throws PersistenceException if the entity is not associated - * with an open persistence context or cannot be loaded from the - * database - * @since 3.2 - */ - public boolean isInstance(Object entity, Class entityClass); - - /** - * Return the concrete entity class if the given entity belonging - * to the persistence unit and to an open persistence context. - * This method may, but is not required to, load the given entity - * by side effect. - * @param entity entity instance - * @return an entity class belonging to the persistence unit - * @throws IllegalArgumentException if the given object is not an - * instance of an entity class belonging to the persistence unit - * @throws PersistenceException if the entity is not associated - * with an open persistence context or cannot be loaded from the - * database - * @since 3.2 - */ - public Class getClass(T entity); - - /** - * Return the id of the entity. - * A generated id is not guaranteed to be available until after - * the database insert has occurred. - * Returns null if the entity does not yet have an id. - * @param entity entity instance - * @return id of the entity - * @throws IllegalArgumentException if the object is found not - * to be an entity - */ - public Object getIdentifier(Object entity); - - /** - * Return the version of the entity. - * A generated version is not guaranteed to be available until after - * the database insert has occurred. - * Returns null if the entity does not yet have an id. - * @param entity entity instance - * @return id of the entity - * @throws IllegalArgumentException if the object is found not - * to be an entity - * @since 3.2 - */ - public Object getVersion(Object entity); -} ----- +This interface may be found in <<_persistenceunitutil_>>. === SchemaManager Interface [[a12178]] @@ -1661,77 +1143,4 @@ corresponding action. Thus, the behavior of the `SchemaManager` may be controlled via the properties defined in <> and <>. -[source,java] ----- -package jakarta.persistence; - -import java.util.Map; - -/** - * Allows programmatic {@linkplain #create schema creation}, - * {@linkplain #validate schema validation}, - * {@linkplain #truncate data cleanup}, and - * {@linkplain #drop schema cleanup} for entities belonging - * to a certain persistence unit. - * - *

Properties are inherited from the {@link EntityManagerFactory}, - * that is, they may be specified via {@code persistence.xml} or - * {@link Persistence#createEntityManagerFactory(String, Map)}. - * - * @see EntityManagerFactory#getSchemaManager() - * - * @since 3.2 - */ -public interface SchemaManager { - /** - * Create database objects mapped by entities belonging to the - * persistence unit. - * - *

If a DDL operation fails, the behavior is undefined. - * A provider may throw an exception, or it may ignore the problem - * and continue. - * - * @param createSchemas if {@code true}, attempt to create schemas, - * otherwise, assume the schemas already exist - */ - void create(boolean createSchemas); - - /** - * Drop database objects mapped by entities belonging to the - * persistence unit, undoing the effects of the - * {@linkplain #create(boolean) previous creation}. - * - *

If a DDL operation fails, the behavior is undefined. - * A provider may throw an exception, or it may ignore the problem - * and continue. - * - * @param dropSchemas if {@code true}, drop schemas, - * otherwise, leave them be - */ - void drop(boolean dropSchemas); - - /** - * Validate that the database objects mapped by entities belonging - * to the persistence unit have the expected definitions. - * - *

The persistence provider is not required to perform - * any specific validation, so the semantics of this operation are - * entirely provider-specific. - * - * @throws SchemaValidationException if a database object is missing or - * does not have the expected definition - */ - void validate() throws SchemaValidationException; - - /** - * Truncate the database tables mapped by entities belonging to - * the persistence unit, and then re-import initial data from any - * configured SQL scripts for data loading. - * - *

If a SQL operation fails, the behavior is undefined. - * A provider may throw an exception, or it may ignore the problem - * and continue. - */ - void truncate(); -} ----- \ No newline at end of file +This interface may be found in <<_schemamanager_>>. \ No newline at end of file diff --git a/spec/src/main/asciidoc/ch09-container-provider-contracts.adoc b/spec/src/main/asciidoc/ch09-container-provider-contracts.adoc index f32b1664..5d8a5fff 100644 --- a/spec/src/main/asciidoc/ch09-container-provider-contracts.adoc +++ b/spec/src/main/asciidoc/ch09-container-provider-contracts.adoc @@ -243,92 +243,7 @@ Note that only a single `PersistenceProviderResolver` instance can be defined in a given classloader hierarchy at a given time. -==== PersistenceProviderResolver interface - -[source,java] ----- -package jakarta.persistence.spi; - -import java.util.List; - -/** - * Determine the list of persistence providers available in the - * runtime environment. - * - *

Implementations must be thread-safe. - * - *

Note that the getPersistenceProviders method can potentially - * be called many times: it is recommended that the implementation - * of this method make use of caching. - * - * @see PersistenceProvider - * @since 2.0 - */ -public interface PersistenceProviderResolver { - - /** - * Returns a list of the PersistenceProvider implementations - * available in the runtime environment. - * - * @return list of the persistence providers available - * in the environment - */ - List getPersistenceProviders(); - - /** - * Clear cache of providers. - * - */ - void clearCachedProviders(); -} ----- - -==== PersistenceProviderResolverHolder class - -[source,java] ----- -package jakarta.persistence.spi; - -import java.util.List; - -/** - * Holds the global {@link PersistenceProviderResolver} - * instance. If no PersistenceProviderResolver is set by the - * environment, the default PersistenceProviderResolver is used. - * Enable "jakarta.persistence.spi" logger to show diagnostic information. - * - * Implementations must be thread-safe. - * - * @since 2.0 - */ -public class PersistenceProviderResolverHolder { - - private static PersistenceProviderResolver singleton = new DefaultPersistenceProviderResolver(); - - /** - * Returns the current persistence provider resolver. - * - * @return the current persistence provider resolver - */ - public static PersistenceProviderResolver getPersistenceProviderResolver() { - return singleton; - } - - /** - * Defines the persistence provider resolver used. - * - * @param resolver persistence provider resolver to be used. - */ - public static void setPersistenceProviderResolver(PersistenceProviderResolver resolver) { - if (resolver == null) { - singleton = new DefaultPersistenceProviderResolver(); - } else { - singleton = resolver; - } - } - -} ----- +These interfaces may be found in <>/ === Schema Generation [[a12917]] @@ -586,130 +501,7 @@ implementation is not intended to be used by the application. The `PersistenceProvider` implementation class must have a public no-arg constructor. -[source,java] ----- -package jakarta.persistence.spi; - -import jakarta.persistence.EntityManagerFactory; -import jakarta.persistence.Persistence; -import jakarta.persistence.PersistenceException; -import java.util.Map; - -/** - * Interface implemented by the persistence provider. - * - *

It is invoked by the container in Jakarta EE environments and - * by the {@link Persistence} class in Java SE environments to - * create an {@link EntityManagerFactory} and/or to cause - * schema generation to occur. - * - * @since 1.0 - */ -public interface PersistenceProvider { - - /** - * Called by Persistence class when an - * EntityManagerFactory is to be created. - * - * @param emName the name of the persistence unit - * @param map a Map of properties for use by the - * persistence provider. These properties may be used to - * override the values of the corresponding elements in - * the persistence.xml file or specify values for - * properties not specified in the persistence.xml - * (and may be null if no properties are specified). - * @return EntityManagerFactory for the persistence unit, - * or null if the provider is not the right provider - */ - public EntityManagerFactory createEntityManagerFactory(String emName, Map map); - - /** - * Called by Persistence class when an - * EntityManagerFactory is to be created. - * - * @param configuration the configuration of the persistence unit - * @return EntityManagerFactory for the persistence unit, - * or null if the provider is not the right provider - * @throws IllegalStateException if required configuration is missing - * - * @see Persistence#createEntityManagerFactory(PersistenceConfiguration) - * - * @since 3.2 - */ - public EntityManagerFactory createEntityManagerFactory(PersistenceConfiguration configuration); - - /** - * Called by the container when an EntityManagerFactory - * is to be created. - * - * @param info metadata for use by the persistence provider - * @param map a Map of integration-level properties for use - * by the persistence provider (may be null if no properties - * are specified). These properties may include properties to - * control schema generation. - * If a Bean Validation provider is present in the classpath, - * the container must pass the ValidatorFactory instance in - * the map with the key "jakarta.persistence.validation.factory". - * If the containing archive is a bean archive, the container - * must pass the BeanManager instance in the map with the key - * "jakarta.persistence.bean.manager". - * @return EntityManagerFactory for the persistence unit - * specified by the metadata - */ - public EntityManagerFactory createContainerEntityManagerFactory(PersistenceUnitInfo info, Map map); - - - /** - * Create database schemas and/or tables and/or create DDL - * scripts as determined by the supplied properties. - *

- * Called by the container when schema generation is to - * occur as a separate phase from creation of the entity - * manager factory. - *

- * @param info metadata for use by the persistence provider - * @param map properties for schema generation; these may - * also include provider-specific properties - * @throws PersistenceException if insufficient or inconsistent - * configuration information is provided of if schema - * generation otherwise fails - * - * @since 2.1 - */ - public void generateSchema(PersistenceUnitInfo info, Map map); - - /** - * Create database schemas and/or tables and/or create DDL - * scripts as determined by the supplied properties. - *

- * Called by the Persistence class when schema generation is to - * occur as a separate phase from creation of the entity - * manager factory. - *

- * @param persistenceUnitName the name of the persistence unit - * @param map properties for schema generation; these may - * also contain provider-specific properties. The - * value of these properties override any values that - * may have been configured elsewhere. - * @return true if schema was generated, otherwise false - * @throws PersistenceException if insufficient or inconsistent - * configuration information is provided or if schema - * generation otherwise fails - * - * @since 2.1 - */ - public boolean generateSchema(String persistenceUnitName, Map map); - - /** - * Return the utility interface implemented by the persistence - * provider. - * @return ProviderUtil interface - * - * @since 2.0 - */ - public ProviderUtil getProviderUtil(); -} ----- +This interface may be found in <<_persistenceprovider_>>. The properties used in the `createEntityManagerFactory` method in Java SE environments are @@ -722,338 +514,11 @@ the `PersistenceUtil` implementation to determine the load status of an entity or entity attribute. It is not intended to be invoked by the application. -[source,java] ----- -package jakarta.persistence.spi; - -import jakarta.persistence.PersistenceUtil; - -/** - * Utility interface implemented by the persistence provider. This - * interface is invoked by the {@link - * PersistenceUtil} implementation to determine - * the load status of an entity or entity attribute. - * - * @since 2.0 - */ -public interface ProviderUtil { - - /** - * If the provider determines that the entity has been provided - * by itself and that the state of the specified attribute has - * been loaded, this method returns LoadState.LOADED. - *

If the provider determines that the entity has been provided - * by itself and that either entity attributes with FetchType.EAGER - * have not been loaded or that the state of the specified - * attribute has not been loaded, this methods returns - * LoadState.NOT_LOADED. - *

If a provider cannot determine the load state, this method - * returns LoadState.UNKNOWN. - *

The provider's implementation of this method must not obtain - * a reference to an attribute value, as this could trigger the - * loading of entity state if the entity has been provided by a - * different provider. - * @param entity entity instance - * @param attributeName name of attribute whose load status is - * to be determined - * @return load status of the attribute - */ - public LoadState isLoadedWithoutReference(Object entity, String attributeName); - - /** - * If the provider determines that the entity has been provided - * by itself and that the state of the specified attribute has - * been loaded, this method returns LoadState.LOADED. - *

If a provider determines that the entity has been provided - * by itself and that either the entity attributes with FetchType.EAGER - * have not been loaded or that the state of the specified - * attribute has not been loaded, this method returns - * return LoadState.NOT_LOADED. - *

If the provider cannot determine the load state, this method - * returns LoadState.UNKNOWN. - *

The provider's implementation of this method is permitted to - * obtain a reference to the attribute value. (This access is - * safe because providers which might trigger the loading of the - * attribute state will have already been determined by - * isLoadedWithoutReference. ) - * - * @param entity entity instance - * @param attributeName name of attribute whose load status is - * to be determined - * @return load status of the attribute - */ - public LoadState isLoadedWithReference(Object entity, String attributeName); - - /** - * If the provider determines that the entity has been provided - * by itself and that the state of all attributes for which - * FetchType.EAGER has been specified have been loaded, this - * method returns LoadState.LOADED. - *

If the provider determines that the entity has been provided - * by itself and that not all attributes with FetchType.EAGER - * have been loaded, this method returns LoadState.NOT_LOADED. - *

If the provider cannot determine if the entity has been - * provided by itself, this method returns LoadState.UNKNOWN. - *

The provider's implementation of this method must not obtain - * a reference to any attribute value, as this could trigger the - * loading of entity state if the entity has been provided by a - * different provider. - * @param entity whose loaded status is to be determined - * @return load status of the entity - */ - public LoadState isLoaded(Object entity); -} ----- - -[source,java] ----- -package jakarta.persistence.spi; - -/** - * Load states returned by the {@link ProviderUtil} SPI methods. - * @since 2.0 - * - */ -public enum LoadState { - /** The state of the element is known to have been loaded. */ - LOADED, - /** The state of the element is known not to have been loaded. */ - NOT_LOADED, - /** The load state of the element cannot be determined. */ - UNKNOWN -} ----- +This interface may be found in <<_providerutil_>>. === jakarta.persistence.spi.PersistenceUnitInfo Interface [[a13160]] -[source,java] ----- -package jakarta.persistence.spi; - -import javax.sql.DataSource; -import java.util.List; -import java.util.Properties; -import java.net.URL; -import jakarta.persistence.SharedCacheMode; -import jakarta.persistence.ValidationMode; -import jakarta.persistence.EntityManagerFactory; - -/** - * Interface implemented by the container and used by the - * persistence provider when creating an {@link EntityManagerFactory}. - * - * @since 1.0 - */ -public interface PersistenceUnitInfo { - - /** - * Returns the name of the persistence unit. Corresponds to the - * name attribute in the persistence.xml file. - * @return the name of the persistence unit - */ - public String getPersistenceUnitName(); - - /** - * Returns the fully qualified name of the persistence provider - * implementation class. Corresponds to the provider element in - * the persistence.xml file. - * @return the fully qualified name of the persistence provider - * implementation class - */ - public String getPersistenceProviderClassName(); - - /** - * Returns the fully-qualified class name of an annotation annotated - * {@code Scope} or {@code NormalScope}. Corresponds to the {@code scope} - * element in {@code persistence.xml}. - * @return the fully-qualified class name of the scope annotation, - * or null if no scope was explicitly specified - */ - public String getScopeAnnotationName(); - - /** - * Returns the fully-qualified class names of annotations annotated - * {@code Qualifier}. Corresponds to the {@code qualifier} element in - * {@code persistence.xml}. - * @return the fully-qualified class names of the qualifier annotations, - * or an empty list if no qualifier annotations were explicitly - * specified - */ - public List getQualifierAnnotationNames(); - - /** - * Returns the transaction type of the entity managers created by - * the EntityManagerFactory. The transaction type corresponds to - * the transaction-type attribute in the persistence.xml file. - * @return transaction type of the entity managers created - * by the EntityManagerFactory - */ - public PersistenceUnitTransactionType getTransactionType(); - - /** - * Returns the JTA-enabled data source to be used by the - * persistence provider. The data source corresponds to the - * jta-data-source element in the persistence.xml file or is - * provided at deployment or by the container. - * @return the JTA-enabled data source to be used by the - * persistence provider - */ - public DataSource getJtaDataSource(); - - /** - * Returns the non-JTA-enabled data source to be used by the - * persistence provider for accessing data outside a JTA - * transaction. The data source corresponds to the named - * non-jta-data-source element in the persistence.xml file or - * provided at deployment or by the container. - * @return the non-JTA-enabled data source to be used by the - * persistence provider for accessing data outside a JTA - * transaction - */ - public DataSource getNonJtaDataSource(); - - /** - * Returns the list of the names of the mapping files that the - * persistence provider must load to determine the mappings for - * the entity classes. The mapping files must be in the standard - * XML mapping format, be uniquely named and be resource-loadable - * from the application classpath. Each mapping file name - * corresponds to a mapping-file element in the - * persistence.xml file. - * @return the list of mapping file names that the persistence - * provider must load to determine the mappings for the entity - * classes - */ - public List getMappingFileNames(); - - /** - * Returns a list of URLs for the jar files or exploded jar - * file directories that the persistence provider must examine - * for managed classes of the persistence unit. Each URL - * corresponds to a jar-file element in the - * persistence.xml file. A URL will either be a - * file: URL referring to a jar file or referring to a directory - * that contains an exploded jar file, or some other URL from - * which an InputStream in jar format can be obtained. - * @return a list of URL objects referring to jar files or - * directories - */ - public List getJarFileUrls(); - - /** - * Returns the URL for the jar file or directory that is the - * root of the persistence unit. (If the persistence unit is - * rooted in the WEB-INF/classes directory, this will be the - * URL of that directory.) - * The URL will either be a file: URL referring to a jar file - * or referring to a directory that contains an exploded jar - * file, or some other URL from which an InputStream in jar - * format can be obtained. - * @return a URL referring to a jar file or directory - */ - public URL getPersistenceUnitRootUrl(); - - /** - * Returns the list of the names of the classes that the - * persistence provider must add to its set of managed - * classes. Each name corresponds to a named class element in the - * persistence.xml file. - * @return the list of the names of the classes that the - * persistence provider must add to its set of managed - * classes - */ - public List getManagedClassNames(); - - /** - * Returns whether classes in the root of the persistence unit - * that have not been explicitly listed are to be included in the - * set of managed classes. This value corresponds to the - * exclude-unlisted-classes element in the persistence.xml file. - * @return whether classes in the root of the persistence - * unit that have not been explicitly listed are to be - * included in the set of managed classes - */ - public boolean excludeUnlistedClasses(); - - /** - * Returns the specification of how the provider must use - * a second-level cache for the persistence unit. - * The result of this method corresponds to the shared-cache-mode - * element in the persistence.xml file. - * @return the second-level cache mode that must be used by the - * provider for the persistence unit - * - * @since 2.0 - */ - public SharedCacheMode getSharedCacheMode(); - - /** - * Returns the validation mode to be used by the persistence - * provider for the persistence unit. The validation mode - * corresponds to the validation-mode element in the - * persistence.xml file. - * @return the validation mode to be used by the - * persistence provider for the persistence unit - * - * @since 2.0 - */ - public ValidationMode getValidationMode(); - - /** - * Returns a properties object. Each property corresponds to a - * property element in the persistence.xml file - * or to a property set by the container. - * @return Properties object - */ - public Properties getProperties(); - - /** - * Returns the schema version of the persistence.xml file. - * @return persistence.xml schema version - * - * @since 2.0 - */ - public String getPersistenceXMLSchemaVersion(); - - /** - * Returns ClassLoader that the provider may use to load any - * classes, resources, or open URLs. - * @return ClassLoader that the provider may use to load any - * classes, resources, or open URLs - */ - public ClassLoader getClassLoader(); - - /** - * Add a transformer supplied by the provider that will be - * called for every new class definition or class redefinition - * that gets loaded by the loader returned by the - * {@link PersistenceUnitInfo#getClassLoader} method. The transformer - * has no effect on the result returned by the - * {@link PersistenceUnitInfo#getNewTempClassLoader} method. - * Classes are only transformed once within the same classloading - * scope, regardless of how many persistence units they may be - * a part of. - * @param transformer provider-supplied transformer that the - * container invokes at class-(re)definition time - */ - public void addTransformer(Transformer transformer); - - /** - * Return a new instance of a ClassLoader that the provider may - * use to temporarily load any classes, resources, or open - * URLs. The scope and classpath of this loader is exactly the - * same as that of the loader returned by {@link - * PersistenceUnitInfo#getClassLoader}. None of the classes loaded - * by this class loader will be visible to application - * components. The provider may only use this ClassLoader within - * the scope of the {@link - * PersistenceProvider#createContainerEntityManagerFactory} call. - * @return temporary ClassLoader with same visibility as current - * loader - */ - public ClassLoader getNewTempClassLoader(); -} ----- +This interface may be found in <<_persistenceunitinfo_>>. The enum `jakarta.persistence.spi.PersistenceUnitTransactionType` defines whether @@ -1062,27 +527,10 @@ entity managers. [source,java] ---- -package jakarta.persistence.spi; - -import jakarta.persistence.EntityManagerFactory; - -/** - * Specifies whether entity managers created by the {@link - * EntityManagerFactory} will be JTA or - * resource-local entity managers. - * - * @since 1.0 - */ -public enum PersistenceUnitTransactionType { - - /** JTA entity managers will be created. */ - JTA, - - /** Resource-local entity managers will be created. */ - RESOURCE_LOCAL -} +include::../../../../api/src/main/java/jakarta/persistence/spi/PersistenceUnitTransactionType.java[lines=18..-1] ---- + The enum `jakarta.persistence.SharedCacheMode` defines the use of caching. The `persistence.xml` `shared-cache-mode` element has no default value. The `getSharedCacheMode` method must @@ -1091,49 +539,7 @@ specified for the persistence unit. [source,java] ---- -package jakarta.persistence; - -import jakarta.persistence.spi.PersistenceUnitInfo; - -/** - * Specifies how the provider must use a second-level cache for the - * persistence unit. Corresponds to the value of the persistence.xml - * shared-cache-mode element, and returned as the result of - * {@link PersistenceUnitInfo#getSharedCacheMode()}. - * - * @since 2.0 - */ -public enum SharedCacheMode { - - /** - * All entities and entity-related state and data are cached. - */ - ALL, - - /** - * Caching is disabled for the persistence unit. - */ - NONE, - - /** - * Caching is enabled for all entities for Cacheable(true) - * is specified. All other entities are not cached. - */ - ENABLE_SELECTIVE, - - /** - * Caching is enabled for all entities except those for which - * Cacheable(false) is specified. Entities for which - * Cacheable(false) is specified are not cached. - */ - DISABLE_SELECTIVE, - - /** - * - * Caching behavior is undefined: provider-specific defaults may apply. - */ - UNSPECIFIED -} +include::../../../../api/src/main/java/jakarta/persistence/SharedCacheMode.java[lines=18..-1] ---- The enum `jakarta.persistence.ValidationMode` @@ -1141,37 +547,7 @@ defines the validation mode. [source,java] ---- -package jakarta.persistence; - -/** - * The validation mode to be used by the provider for the persistence - * unit. - * - * @since 2.0 - */ -public enum ValidationMode { - - /** - * If a Bean Validation provider is present in the environment, - * the persistence provider must perform the automatic validation - * of entities. If no Bean Validation provider is present in the - * environment, no lifecycle event validation takes place. - * This is the default behavior. - */ - AUTO, - - /** - * The persistence provider must perform the lifecycle event - * validation. It is an error if there is no Bean Validation - * provider present in the environment. - */ - CALLBACK, - - /** - * The persistence provider must not perform lifecycle event validation. - */ - NONE -} +include::../../../../api/src/main/java/jakarta/persistence/ValidationMode.java[lines=18..-1] ---- ==== jakarta.persistence.spi.ClassTransformer Interface @@ -1182,54 +558,7 @@ transform entities and managed classes at class load time or at class redefinition time. Implementation of this interface by a persistence provider is optional. -[source,java] ----- -package jakarta.persistence.spi; - -import java.security.ProtectionDomain; - -/** - * A persistence provider supplies an instance of this - * interface to the {@link PersistenceUnitInfo#addTransformer - * PersistenceUnitInfo.addTransformer} - * method. The supplied transformer instance will get - * called to transform entity class files when they are - * loaded or redefined. The transformation occurs before - * the class is defined by the JVM. - * - * @since 1.0 - */ -public interface ClassTransformer { - - /** - * Invoked when a class is being loaded or redefined. - * The implementation of this method may transform the - * supplied class file and return a new replacement class - * file. - * - * @param loader the defining loader of the class to be - * transformed, may be null if the bootstrap loader - * @param className the name of the class in the internal form - * of fully qualified class and interface names - * @param classBeingRedefined if this is a redefine, the - * class being redefined, otherwise null - * @param protectionDomain the protection domain of the - * class being defined or redefined - * @param classfileBuffer the input byte buffer in class - * file format - must not be modified - * @return a well-formed class file buffer (the result of - * the transform), or null if no transform is performed - * @throws TransformerException if the input does - * not represent a well-formed class file - */ - byte[] transform(ClassLoader loader, - String className, - Class classBeingRedefined, - ProtectionDomain protectionDomain, - byte[] classfileBuffer) - throws TransformerException; -} ----- +This interface may be found in <<_classtransformer_>>. === jakarta.persistence.Persistence Class [[a13443]] @@ -1244,157 +573,7 @@ environments. The `Persistence` class is used to obtain a `PersistenceUtil` instance in both Jakarta EE and Java SE environments. -[source,java] ----- -package jakarta.persistence; - -import java.util.List; -import java.util.Map; -import java.util.Set; -import java.util.HashSet; -import jakarta.persistence.spi.PersistenceProvider; -import jakarta.persistence.spi.PersistenceProviderResolver; -import jakarta.persistence.spi.PersistenceProviderResolverHolder; -import jakarta.persistence.spi.LoadState; - -/** - * Bootstrap class that is used to obtain an {@link EntityManagerFactory} - * in Java SE environments. It may also be used to cause schema - * generation to occur. - * - *

The Persistence class is available in a Jakarta EE - * container environment as well; however, support for the Java SE - * bootstrapping APIs is not required in container environments. - * - *

The Persistence class is used to obtain a {@link - * PersistenceUtil PersistenceUtil} instance in both - * Jakarta EE and Java SE environments. - * - * @since 1.0 - */ -public class Persistence { - - /** - * Create and return an EntityManagerFactory for the named - * persistence unit. - * - * @param persistenceUnitName - * the name of the persistence unit - * @return the factory that creates EntityManagers configured according to - * the specified persistence unit - */ - public static EntityManagerFactory createEntityManagerFactory(String persistenceUnitName) { - return createEntityManagerFactory(persistenceUnitName, null); - } - - /** - * Create and return an EntityManagerFactory for the named persistence unit - * using the given properties. - * - * @param persistenceUnitName - * the name of the persistence unit - * @param properties - * Additional properties to use when creating the factory. - * These properties may include properties to control - * schema generation. The values of these properties override - * any values that may have been configured elsewhere. - * @return the factory that creates EntityManagers configured according to - * the specified persistence unit. - */ - public static EntityManagerFactory createEntityManagerFactory(String persistenceUnitName, Map properties) { - - EntityManagerFactory emf = null; - PersistenceProviderResolver resolver = PersistenceProviderResolverHolder.getPersistenceProviderResolver(); - - List providers = resolver.getPersistenceProviders(); - - for (PersistenceProvider provider : providers) { - emf = provider.createEntityManagerFactory(persistenceUnitName, properties); - if (emf != null) { - break; - } - } - if (emf == null) { - throw new PersistenceException("No Persistence provider for EntityManager named " + persistenceUnitName); - } - return emf; - } - - /** - * Create and return an EntityManagerFactory for the named persistence unit - * using the given properties. - * - * @param configuration - * configuration of the persistence unit - * @return the factory that creates EntityManagers configured according to - * the specified persistence unit. - * - * @since 3.2 - */ - public static EntityManagerFactory createEntityManagerFactory(PersistenceConfiguration configuration) { - - EntityManagerFactory emf = null; - PersistenceProviderResolver resolver = PersistenceProviderResolverHolder.getPersistenceProviderResolver(); - - List providers = resolver.getPersistenceProviders(); - - for (PersistenceProvider provider : providers) { - emf = provider.createEntityManagerFactory(configuration); - if (emf != null) { - break; - } - } - if (emf == null) { - throw new PersistenceException("No Persistence provider for EntityManager named " + configuration.name()); - } - return emf; - } - - - /** - * Create database schemas and/or tables and/or create DDL - * scripts as determined by the supplied properties. - *

- * Called when schema generation is to occur as a separate phase - * from creation of the entity manager factory. - *

- * @param persistenceUnitName the name of the persistence unit - * @param map properties for schema generation; these may - * also contain provider-specific properties. The - * value of these properties override any values that - * may have been configured elsewhere.. - * @throws PersistenceException if insufficient or inconsistent - * configuration information is provided or if schema - * generation otherwise fails. - * - * @since 2.1 - */ - public static void generateSchema(String persistenceUnitName, Map map) { - PersistenceProviderResolver resolver = PersistenceProviderResolverHolder.getPersistenceProviderResolver(); - List providers = resolver.getPersistenceProviders(); - - for (PersistenceProvider provider : providers) { - if (provider.generateSchema(persistenceUnitName, map)) { - return; - } - } - - throw new PersistenceException("No Persistence provider to generate schema named " + persistenceUnitName); - } - - - /** - * Return the PersistenceUtil instance - * @return PersistenceUtil instance - * @since 2.0 - */ - public static PersistenceUtil getPersistenceUtil() { - // ... - } - - // ... -} ----- +This interface may be found in <<_persistence_>>. The `properties` argument passed to the `createEntityManagerFactory` method is used to specify both standard and vendor-specific properties @@ -1579,48 +758,7 @@ This interface is used to determine load state. The semantics of the methods of this interface are defined in <> below. -[source,java] ----- -package jakarta.persistence; - -/** - * Utility interface between the application and the persistence - * provider(s). - * - *

The PersistenceUtil interface instance obtained from the - * {@link Persistence} class is used to determine the load state of an - * entity or entity attribute regardless of which persistence - * provider in the environment created the entity. - * - * @since 2.0 - */ -public interface PersistenceUtil { - - /** - * Determine the load state of a given persistent attribute. - * @param entity entity containing the attribute - * @param attributeName name of attribute whose load state is - * to be determined - * @return false if entity's state has not been loaded or - * if the attribute state has not been loaded, else true - */ - public boolean isLoaded(Object entity, String attributeName); - - /** - * Determine the load state of an entity. - * This method can be used to determine the load state - * of an entity passed as a reference. An entity is - * considered loaded if all attributes for which - * FetchType.EAGER has been specified have been loaded. - *

The isLoaded(Object, String) method should be used to - * determine the load state of an attribute. - * Not doing so might lead to unintended loading of state. - * @param entity whose load state is to be determined - * @return false if the entity has not been loaded, else true - */ - public boolean isLoaded(Object entity); -} ----- +This interface may be found in <<_persistenceutil_>>. ==== Contracts for Determining the Load State of an Entity or Entity Attribute [[a13592]] diff --git a/spec/src/main/asciidoc/jakarta.persistence-spec.adoc b/spec/src/main/asciidoc/jakarta.persistence-spec.adoc index e244f9a7..4a0b9e28 100644 --- a/spec/src/main/asciidoc/jakarta.persistence-spec.adoc +++ b/spec/src/main/asciidoc/jakarta.persistence-spec.adoc @@ -83,4 +83,8 @@ include::related-documents.adoc[] // == Appendixes :sectnums: -include::appendixes.adoc[] +include::appA-revision-history.adoc[] +include::appB-persistence.adoc[] +include::appC-criteria.adoc[] +include::appD-metamodel.adoc[] +include::appE-spi.adoc[] From 33574011040f723dfbc98e56abe1aa0048cd2a8b Mon Sep 17 00:00:00 2001 From: Gavin King Date: Sat, 23 Mar 2024 00:50:07 +0100 Subject: [PATCH 2/4] try to improve flow --- .../main/asciidoc/ch03-entity-operations.adoc | 49 +++++----- spec/src/main/asciidoc/ch06-criteria-api.adoc | 7 +- ...titymanagers-and-persistence-contexts.adoc | 32 ++++--- .../ch09-container-provider-contracts.adoc | 89 ++++++++----------- 4 files changed, 80 insertions(+), 97 deletions(-) diff --git a/spec/src/main/asciidoc/ch03-entity-operations.adoc b/spec/src/main/asciidoc/ch03-entity-operations.adoc index bfb74d41..727ddf56 100644 --- a/spec/src/main/asciidoc/ch03-entity-operations.adoc +++ b/spec/src/main/asciidoc/ch03-entity-operations.adoc @@ -921,20 +921,19 @@ that enables the effect of “repeatable read” semantics for the items read, whether “optimistically” (as described in <>) or “pessimistically” (as described in <>). -Lock modes can be specified by means of the -EntityManager `lock` method, the methods of the `EntityManager`, -`Query`, and `TypedQuery` interfaces that allow lock modes to be -specified, and the `NamedQuery` annotation. +A lock mode may be explicitly specified as an argument to the +`lock()` method of `EntityManager` or to any other method of +`EntityManager`, `Query`, and `TypedQuery` which accepts a lock +mode, or via the `NamedQuery` annotation. -Lock mode values are defined by the -`LockModeType` enum. Six distinct lock modes are defined. The lock mode -type values `READ` and `WRITE` are synonyms of `OPTIMISTIC` and -`OPTIMISTIC_FORCE_INCREMENT` respectively.footnote:[The lock mode type -NONE may be specified as a value of lock mode arguments and also -provides a default value for annotations.] The -latter are to be preferred for new applications. +Lock mode values are defined by the `LockModeType` enum which may +be found in <<_lockmodetype_>>. Six distinct lock modes are defined. +footnote:[The lock mode type NONE may be specified as a method +argument and also provides a default value for annotations.] +The lock mode type values `READ` and `WRITE` are synonyms for +`OPTIMISTIC` and `OPTIMISTIC_FORCE_INCREMENT` respectively. +The latter are to be preferred for new applications. -This enum may be found in <<_lockmodetype_>>. ===== OPTIMISTIC, OPTIMISTIC_FORCE_INCREMENT [[a2100]] @@ -1898,19 +1897,19 @@ form of metadata or an object created by the dynamic `EntityGraph` API. Entity graphs are used in the specification of “fetch plans” for query or `find` operations. -The `EntityGraph`, `AttributeNode`, and -`Subgraph` interfaces are used to dynamically construct entity graphs. -The annotations to statically define entity graphs, namely -`NamedEntityGraph`, `NamedAttributeNode`, and `NamedSubgraph`, are -described in <>. -The `named-entity-graph` XML element and its subelements may be used to -override these annotations or to define additional named entity graphs. +The `EntityGraph`, `AttributeNode`, and `Subgraph` interfaces found in +<> are used to dynamically construct entity +graphs. + +The annotations `NamedEntityGraph`, `NamedAttributeNode`, and +`NamedSubgraph` described in <> are used to statically define +entity graphs. The `named-entity-graph` XML element and its subelements +may be used to override these annotations or to define additional named +entity graphs. The semantics of entity graphs with regard to find and query operations are described in <>. -These interfaces may be found in <>. - ==== Use of Entity Graphs in find and query operations [[a2814]] An entity graph can be used with the `find` @@ -2493,11 +2492,9 @@ include::../../../../api/src/main/java/jakarta/persistence/CacheStoreMode.java[l ==== Cache Interface [[a12124]] -The `Cache` interface allows the application to request eviction of -entity data from the second-level cache directly and immediately, -outside the scope of any persistence context. - -This interface may be found in <<_cache_>>. +The `Cache` interface found in <<_cache_>> allows the application to +request eviction of entity data from the second-level cache directly +and immediately, outside the scope of any persistence context. === Query APIs [[a3125]] diff --git a/spec/src/main/asciidoc/ch06-criteria-api.adoc b/spec/src/main/asciidoc/ch06-criteria-api.adoc index d759e082..61621574 100644 --- a/spec/src/main/asciidoc/ch06-criteria-api.adoc +++ b/spec/src/main/asciidoc/ch06-criteria-api.adoc @@ -21,6 +21,8 @@ form of metamodel objects over which the Criteria API operates. The semantics of criteria queries are designed to reflect those of Jakarta Persistence query language queries. +The complete criteria query API may be found in <>. + The syntax of the Criteria API is designed to allow the construction of an object-based query “graph”, whose nodes correspond to the semantic query elements. @@ -32,8 +34,7 @@ entities and embeddable types that constitute the query domain, play a role analogous to that of the identification variables of the Jakarta Persistence query language. -These concepts are further described in the sections that follow. The -`jakarta.persistence.criteria` interfaces are presented in <>. +These concepts are further described in the sections that follow. Sections <> through <> describe the construction and modification of criteria query objects. Additional requirements on the persistence provider are described in <>. @@ -42,8 +43,6 @@ The metamodel on which criteria queries are based was already presented in <>. The static metamodel classes which are used to construct strongly-typed criteria queries are described in <>. -The complete criteria query API may be found in <>. - === Criteria Query API Usage [[a10608]] The `jakarta.persistence.criteria` API diff --git a/spec/src/main/asciidoc/ch07-entitymanagers-and-persistence-contexts.adoc b/spec/src/main/asciidoc/ch07-entitymanagers-and-persistence-contexts.adoc index 777eceaa..3fa7948f 100644 --- a/spec/src/main/asciidoc/ch07-entitymanagers-and-persistence-contexts.adoc +++ b/spec/src/main/asciidoc/ch07-entitymanagers-and-persistence-contexts.adoc @@ -217,22 +217,22 @@ EntityManagerFactory emf = === EntityManagerFactory Interface -The `EntityManagerFactory` interface is used +The `EntityManagerFactory` interface found in <<_entitymanagerfactory_>> + +An `EntityManagerFactory` may be used by the application to obtain an application-managed entity manager. When the application has finished using the entity manager factory, and/or at application shutdown, the application should close the entity manager factory. Once an entity manager factory has been closed, all its entity managers are considered to be in the closed state. -The `EntityManagerFactory` interface provides +An `EntityManagerFactory` also provides access to information and services that are global to the persistence unit. This includes access to the second level cache that is maintained by the persistence provider and to the `PersistenceUnitUtil` interface. The `Cache` interface is described in <>; the `PersistenceUnitUtil` interface in <>. -This interface may be found in <<_entitymanagerfactory_>>. - Any number of vendor-specific properties may be included in the map passed to the `createEntityManager` methods. Properties that are not recognized by a vendor must be ignored. @@ -301,10 +301,10 @@ presence of JTA transactions that may or may not be active. ==== The EntityTransaction Interface -The `EntityTransaction` interface is used to -control resource transactions on resource-local entity managers. The -`EntityManager.getTransaction()` method returns an instance of the -`EntityTransaction` interface. +The `EntityTransaction` interface found in <<_entitytransaction_>> +is used to control resource transactions on resource-local entity +managers. The `getTransaction()` method of `EntityManager` returns +an instance of the `EntityTransaction` interface. When a resource-local entity manager is used, and the persistence provider runtime throws an exception defined to @@ -314,8 +314,6 @@ transaction for rollback. If the `EntityTransaction.commit` operation fails, the persistence provider must roll back the transaction. -This interface may be found in <<_entitytransaction_>>. - The following example illustrates the creation of an entity manager factory in a Java SE environment, and its use in creating and using a resource-local entity manager. @@ -1112,17 +1110,19 @@ provider must detach all managed entities. === PersistenceUnitUtil Interface [[a12177]] -The `PersistenceUnitUtil` interface provides -access to utility methods that can be invoked on entities associated +The `PersistenceUnitUtil` interface found in <<_persistenceunitutil_>> +declares utility methods that can be invoked on entities associated with the persistence unit. The behavior is undefined if these methods are invoked on an entity instance that is not associated with the persistence unit from whose entity manager factory this interface has been obtained. -This interface may be found in <<_persistenceunitutil_>>. - === SchemaManager Interface [[a12178]] +The `SchemaManager` interface may be found in <<_schemamanager_>>. +An instance of `SchemaManager` may be obtained by calling the +`getSchemaManager()` method of `EntityManagerFactory`. + The `SchemaManager` interface allows programmatic control over schema generation and cleanup at runtime. This differs from the functionality described in <> which allows schema generation before or during @@ -1141,6 +1141,4 @@ The methods of `SchemaManager` correspond to values of the property corresponding action. Thus, the behavior of the `SchemaManager` may be controlled via the -properties defined in <> and <>. - -This interface may be found in <<_schemamanager_>>. \ No newline at end of file +properties defined in <> and <>. \ No newline at end of file diff --git a/spec/src/main/asciidoc/ch09-container-provider-contracts.adoc b/spec/src/main/asciidoc/ch09-container-provider-contracts.adoc index 5d8a5fff..c0de4651 100644 --- a/spec/src/main/asciidoc/ch09-container-provider-contracts.adoc +++ b/spec/src/main/asciidoc/ch09-container-provider-contracts.adoc @@ -173,17 +173,19 @@ provider for the named persistence unit, it must return `false` when The `PersistenceProviderResolver` and `PersistenceProviderResolverHolder` mechanism supports the dynamic -discovery of persistence providers.footnote:[In dynamic -environments (e.g., OSGi-based environments, containers based on dynamic -kernels, etc.), the list of persistence providers may change.] +discovery of persistence providers.footnote:[In dynamic environments +(e.g., OSGi-based environments, containers based on dynamic kernels, +etc.), the list of persistence providers may change.] -The `PersistenceProviderResolver` instance is -responsible for returning the list of providers available in the -environment. +- The `PersistenceProviderResolver` instance is responsible for + returning the list of providers available in the environment. -The `PersistenceProviderResolverHolder` class -holds the `PersistenceProviderResolver` instance that is in use. The -implementation of `PersistenceProviderResolverHolder` must be +- The `PersistenceProviderResolverHolder` class holds the + `PersistenceProviderResolver` instance that is in use. + +These interfaces may be found in <>. + +The implementation of `PersistenceProviderResolverHolder` must be threadsafe, but no guarantee is made against multiple threads setting the resolver. @@ -243,8 +245,6 @@ Note that only a single `PersistenceProviderResolver` instance can be defined in a given classloader hierarchy at a given time. -These interfaces may be found in <>/ - === Schema Generation [[a12917]] In cases where a preconfigured database (or a @@ -489,48 +489,42 @@ approach as defined by the Bean Validation specification ==== jakarta.persistence.spi.PersistenceProvider -The interface -`jakarta.persistence.spi.PersistenceProvider` must be implemented by the -persistence provider. +The `PersistenceProvider` interface found in <<_persistenceprovider_>> +must be implemented by the persistence provider. -It is invoked by the container in Jakarta EE -environments and by the `jakarta.persistence.Persistence` class in Java SE -environments. The `jakarta.persistence.spi.PersistenceProvider` -implementation is not intended to be used by the application. +The `PersistenceProvider` implementation class must have a public +constructor with no parameters. -The `PersistenceProvider` implementation -class must have a public no-arg constructor. +An instance of `PersistenceProvider` is responsible for creating +provider-specific implementations of `EntityManagerFactory`. It +is invoked by the container in Jakarta EE environments and by the +`jakarta.persistence.Persistence` class in Java SE environments. The +`jakarta.persistence.spi.PersistenceProvider` implementation is not +intended to be used by the application. -This interface may be found in <<_persistenceprovider_>>. - -The properties used in the -`createEntityManagerFactory` method in Java SE environments are -described further in <> below. +The properties passed to the `createEntityManagerFactory()` method +in Java SE environments are described further in <> below. ==== jakarta.persistence.spi.ProviderUtil -The `ProviderUtil` interface is invoked by -the `PersistenceUtil` implementation to determine the load status of an -entity or entity attribute. It is not intended to be invoked by the +The `ProviderUtil` interface found in <<_providerutil_>> is called by +the `PersistenceUtil` implementation to determine the load status of +an entity or entity attribute. It is not intended to be invoked by the application. -This interface may be found in <<_providerutil_>>. - === jakarta.persistence.spi.PersistenceUnitInfo Interface [[a13160]] -This interface may be found in <<_persistenceunitinfo_>>. +The `PersistenceUnitInfo` interface may be found in <<_persistenceunitinfo_>>. -The enum -`jakarta.persistence.spi.PersistenceUnitTransactionType` defines whether -the entity managers created by the factory will be JTA or resource-local -entity managers. +The enum `jakarta.persistence.spi.PersistenceUnitTransactionType` +defines whether the entity managers created by the factory will be +JTA or resource-local entity managers. This enum is deprecated. [source,java] ---- include::../../../../api/src/main/java/jakarta/persistence/spi/PersistenceUnitTransactionType.java[lines=18..-1] ---- - The enum `jakarta.persistence.SharedCacheMode` defines the use of caching. The `persistence.xml` `shared-cache-mode` element has no default value. The `getSharedCacheMode` method must @@ -552,16 +546,15 @@ include::../../../../api/src/main/java/jakarta/persistence/ValidationMode.java[l ==== jakarta.persistence.spi.ClassTransformer Interface -The `jakarta.persistence.spi.ClassTransformer` -interface is implemented by a persistence provider that wants to -transform entities and managed classes at class load time or at class -redefinition time. Implementation of this interface by a persistence -provider is optional. - -This interface may be found in <<_classtransformer_>>. +The `ClassTransformer` interface found in <<_classtransformer_>> may be +implemented by a persistence provider to transform entities and managed +classes at class load time or at class redefinition time. A persistence +provider is not required to implement this interface. === jakarta.persistence.Persistence Class [[a13443]] +The `Persistence` class may be found in <<_persistence_>>. + The `Persistence` class is used to obtain an `EntityManagerFactory` instance in Java SE environments. It may also be used for schema generation—i.e., to create database schemas and/or tables and/or to create DDL scripts. @@ -573,8 +566,6 @@ environments. The `Persistence` class is used to obtain a `PersistenceUtil` instance in both Jakarta EE and Java SE environments. -This interface may be found in <<_persistence_>>. - The `properties` argument passed to the `createEntityManagerFactory` method is used to specify both standard and vendor-specific properties and hints intended for use in creating the entity manager factory and @@ -754,11 +745,9 @@ options the provider does not recognize, it should ignore those options. === PersistenceUtil Interface -This interface is used to determine load -state. The semantics of the methods of this interface are defined in -<> below. - -This interface may be found in <<_persistenceutil_>>. +The `PersistenceUtil` interface found in <<_persistenceutil_>> is used to +determine the load state of entity instances. The semantics of the methods +of this interface are defined in <> below. ==== Contracts for Determining the Load State of an Entity or Entity Attribute [[a13592]] From c5597aebf274948e6ef51b1e880d31480939ac2a Mon Sep 17 00:00:00 2001 From: Gavin King Date: Sat, 23 Mar 2024 10:26:37 +0100 Subject: [PATCH 3/4] tidy up xrefs --- spec/src/main/asciidoc/appB-persistence.adoc | 6 ++-- spec/src/main/asciidoc/appC-criteria.adoc | 6 ++-- spec/src/main/asciidoc/appD-metamodel.adoc | 2 +- spec/src/main/asciidoc/appE-spi.adoc | 2 +- .../main/asciidoc/ch03-entity-operations.adoc | 5 ++- .../src/main/asciidoc/ch05-metamodel-api.adoc | 2 +- spec/src/main/asciidoc/ch06-criteria-api.adoc | 31 +++++++++---------- .../ch09-container-provider-contracts.adoc | 2 +- 8 files changed, 27 insertions(+), 29 deletions(-) diff --git a/spec/src/main/asciidoc/appB-persistence.adoc b/spec/src/main/asciidoc/appB-persistence.adoc index 78730421..794db350 100644 --- a/spec/src/main/asciidoc/appB-persistence.adoc +++ b/spec/src/main/asciidoc/appB-persistence.adoc @@ -1,5 +1,5 @@ [appendix] -== Persistence API Interfaces +== Persistence API Interfaces [[persistence-api]] === `EntityManager` [[_entitymanager_]] [source,java] @@ -49,13 +49,13 @@ include::../../../../api/src/main/java/jakarta/persistence/TypedQuery.java[lines include::../../../../api/src/main/java/jakarta/persistence/StoredProcedureQuery.java[lines=18..-1] ---- -=== `Tuple` [[a3868]] +=== `Tuple` [[_tuple_]] [source,java] ---- include::../../../../api/src/main/java/jakarta/persistence/Tuple.java[lines=18..-1] ---- -=== `TupleElement` [[a3949]] +=== `TupleElement` [[_tupleelement_]] [source,java] ---- include::../../../../api/src/main/java/jakarta/persistence/TupleElement.java[lines=18..-1] diff --git a/spec/src/main/asciidoc/appC-criteria.adoc b/spec/src/main/asciidoc/appC-criteria.adoc index 8631ca8c..a790ae74 100644 --- a/spec/src/main/asciidoc/appC-criteria.adoc +++ b/spec/src/main/asciidoc/appC-criteria.adoc @@ -1,7 +1,7 @@ [appendix] -== Criteria API Interfaces [[a6997]] +== Criteria API Interfaces [[criteria-api]] -=== `CriteriaBuilder` +=== `CriteriaBuilder` [[_criteriabuilder_]] [source,java] ---- include::../../../../api/src/main/java/jakarta/persistence/criteria/CriteriaBuilder.java[lines=18..-1] @@ -13,7 +13,7 @@ include::../../../../api/src/main/java/jakarta/persistence/criteria/CriteriaBuil include::../../../../api/src/main/java/jakarta/persistence/criteria/CriteriaDelete.java[lines=18..-1] ---- -=== `CriteriaQuery` [[a8857]] +=== `CriteriaQuery` [[_criteriaquery_]] [source,java] ---- include::../../../../api/src/main/java/jakarta/persistence/criteria/CriteriaQuery.java[lines=18..-1] diff --git a/spec/src/main/asciidoc/appD-metamodel.adoc b/spec/src/main/asciidoc/appD-metamodel.adoc index 55c7b65a..19036bd7 100644 --- a/spec/src/main/asciidoc/appD-metamodel.adoc +++ b/spec/src/main/asciidoc/appD-metamodel.adoc @@ -1,5 +1,5 @@ [appendix] -== Metamodel API Interfaces +== Metamodel API Interfaces [[metamodel-api]] === `Metamodel` [source,java] diff --git a/spec/src/main/asciidoc/appE-spi.adoc b/spec/src/main/asciidoc/appE-spi.adoc index ce26f398..540048cc 100644 --- a/spec/src/main/asciidoc/appE-spi.adoc +++ b/spec/src/main/asciidoc/appE-spi.adoc @@ -1,5 +1,5 @@ [appendix] -== Persistence SPI Interfaces +== Persistence SPI Interfaces [[persistence-spi]] === `ClassTransformer` [[_classtransformer_]] [source,java] diff --git a/spec/src/main/asciidoc/ch03-entity-operations.adoc b/spec/src/main/asciidoc/ch03-entity-operations.adoc index 727ddf56..ac69dd00 100644 --- a/spec/src/main/asciidoc/ch03-entity-operations.adoc +++ b/spec/src/main/asciidoc/ch03-entity-operations.adoc @@ -1898,8 +1898,7 @@ Entity graphs are used in the specification of “fetch plans” for query or `find` operations. The `EntityGraph`, `AttributeNode`, and `Subgraph` interfaces found in -<> are used to dynamically construct entity -graphs. +<> are used to dynamically construct entity graphs. The annotations `NamedEntityGraph`, `NamedAttributeNode`, and `NamedSubgraph` described in <> are used to statically define @@ -2504,7 +2503,7 @@ also support parameter binding and pagination control. The `StoredProcedureQuery` API is used for the execution of queries that invoke stored procedures defined in the database. -These interfaces may be found in <>. +These interfaces may be found in <>. ==== Query Execution diff --git a/spec/src/main/asciidoc/ch05-metamodel-api.adoc b/spec/src/main/asciidoc/ch05-metamodel-api.adoc index b2642340..9143d98c 100644 --- a/spec/src/main/asciidoc/ch05-metamodel-api.adoc +++ b/spec/src/main/asciidoc/ch05-metamodel-api.adoc @@ -263,4 +263,4 @@ of the managed classes of a persistence unit. An instance of `Metamodel` may be obtained by calling the `getMetamodel()` method of `EntityManagerFactory` or `EntityManager`. -The complete metamodel API may be found in <>. \ No newline at end of file +The complete metamodel API may be found in <>. \ No newline at end of file diff --git a/spec/src/main/asciidoc/ch06-criteria-api.adoc b/spec/src/main/asciidoc/ch06-criteria-api.adoc index 61621574..199321f9 100644 --- a/spec/src/main/asciidoc/ch06-criteria-api.adoc +++ b/spec/src/main/asciidoc/ch06-criteria-api.adoc @@ -21,7 +21,7 @@ form of metamodel objects over which the Criteria API operates. The semantics of criteria queries are designed to reflect those of Jakarta Persistence query language queries. -The complete criteria query API may be found in <>. +The complete criteria query API may be found in <>. The syntax of the Criteria API is designed to allow the construction of an object-based query “graph”, whose nodes @@ -76,15 +76,15 @@ of the criteria API is described in <>. === Constructing Criteria Queries [[a10614]] -A criteria query is constructed through the -creation and modification of a -`jakarta.persistence.criteria.CriteriaQuery` object. +A criteria query is constructed through the creation and modification of +an instance of `jakarta.persistence.criteria.CriteriaQuery`. This interface +is found in <<_criteriaquery_>>. -The `CriteriaBuilder` interface is used to -construct `CriteriaQuery`, `CriteriaUpdate`, and `CriteriaDelete` -objects. The `CriteriaBuilder` implementation is accessed through the -`getCriteriaBuilder` method of the `EntityManager` or -`EntityManagerFactory` interface. +The `CriteriaBuilder` interface found in <<_criteriabuilder_>> is used to +construct `CriteriaQuery`, `CriteriaUpdate`, and `CriteriaDelete` objects. +The `CriteriaBuilder` implementation is accessed through the +`getCriteriaBuilder` method of the `EntityManager` or `EntityManagerFactory` +interface. For example: @@ -121,16 +121,15 @@ CriteriaQuery createQuery(); Methods for the creation of update and delete queries are described in <>. -The methods ` CriteriaQuery -createQuery(Class resultClass)` and `createTupleQuery` provide for -typing of criteria query results and for typesafe query execution using -the `TypedQuery` API. +The methods ` CriteriaQuery createQuery(Class resultClass)` and +`createTupleQuery` provide for typing of criteria query results and for +typesafe query execution using the `TypedQuery` API. The effect of the `createTupleQuery` method is semantically equivalent to invoking the `createQuery` method with the `Tuple.class` argument. The `Tuple` interface supports the extraction of -multiple selection items in a strongly typed manner. See <> and -<>. +multiple selection items in a strongly typed manner. See <<_tuple_>> and +<<_tupleelement_>>. The `CriteriaQuery createQuery()` method supports both the case where the `select` or `multiselect` method @@ -908,7 +907,7 @@ The `multiselect` method also supports the specification and aggregation of multiple selection items. When the `multiselect` method is used, the aggregation of the selection items is determined by the result type of the `CriteriaQuery` object as described -in <> and <>. +in <>. A `Selection` instance passed to the `construct`, `tuple`, `array`, or `multiselect` methods can be one of diff --git a/spec/src/main/asciidoc/ch09-container-provider-contracts.adoc b/spec/src/main/asciidoc/ch09-container-provider-contracts.adoc index c0de4651..c9f5240e 100644 --- a/spec/src/main/asciidoc/ch09-container-provider-contracts.adoc +++ b/spec/src/main/asciidoc/ch09-container-provider-contracts.adoc @@ -183,7 +183,7 @@ etc.), the list of persistence providers may change.] - The `PersistenceProviderResolverHolder` class holds the `PersistenceProviderResolver` instance that is in use. -These interfaces may be found in <>. +These interfaces may be found in <>. The implementation of `PersistenceProviderResolverHolder` must be threadsafe, but no guarantee is made against multiple threads setting From b34768000db185b70a60d20028246fd3e64d2139 Mon Sep 17 00:00:00 2001 From: Gavin King Date: Sat, 23 Mar 2024 12:53:55 +0100 Subject: [PATCH 4/4] further improvements to xrefs --- spec/src/main/asciidoc/appB-persistence.adoc | 6 +++-- spec/src/main/asciidoc/appC-criteria.adoc | 2 ++ spec/src/main/asciidoc/appD-metamodel.adoc | 6 +++-- spec/src/main/asciidoc/appE-spi.adoc | 2 ++ .../main/asciidoc/ch03-entity-operations.adoc | 25 +++++++++++-------- .../src/main/asciidoc/ch05-metamodel-api.adoc | 17 ++++++------- spec/src/main/asciidoc/ch06-criteria-api.adoc | 3 +-- .../ch09-container-provider-contracts.adoc | 12 ++++----- .../asciidoc/ch10-metadata-annotations.adoc | 2 ++ 9 files changed, 44 insertions(+), 31 deletions(-) diff --git a/spec/src/main/asciidoc/appB-persistence.adoc b/spec/src/main/asciidoc/appB-persistence.adoc index 794db350..680e45b3 100644 --- a/spec/src/main/asciidoc/appB-persistence.adoc +++ b/spec/src/main/asciidoc/appB-persistence.adoc @@ -1,6 +1,8 @@ [appendix] == Persistence API Interfaces [[persistence-api]] +The following APIs are defined in the package `jakarta.persistence`. + === `EntityManager` [[_entitymanager_]] [source,java] ---- @@ -31,7 +33,7 @@ include::../../../../api/src/main/java/jakarta/persistence/LockModeType.java[lin include::../../../../api/src/main/java/jakarta/persistence/Cache.java[lines=18..-1] ---- -=== `Query` [[a3127]] +=== `Query` [[_query_]] [source,java] ---- include::../../../../api/src/main/java/jakarta/persistence/Query.java[lines=18..-1] @@ -103,7 +105,7 @@ include::../../../../api/src/main/java/jakarta/persistence/SchemaManager.java[li include::../../../../api/src/main/java/jakarta/persistence/Persistence.java[lines=18..-1] ---- -=== `PersistenceConfiguration` +=== `PersistenceConfiguration` [[_persistenceconfiguration_]] [source,java] ---- include::../../../../api/src/main/java/jakarta/persistence/PersistenceConfiguration.java[lines=18..-1] diff --git a/spec/src/main/asciidoc/appC-criteria.adoc b/spec/src/main/asciidoc/appC-criteria.adoc index a790ae74..ff800900 100644 --- a/spec/src/main/asciidoc/appC-criteria.adoc +++ b/spec/src/main/asciidoc/appC-criteria.adoc @@ -1,6 +1,8 @@ [appendix] == Criteria API Interfaces [[criteria-api]] +The following APIs are defined in the package `jakarta.persistence.criteria`. + === `CriteriaBuilder` [[_criteriabuilder_]] [source,java] ---- diff --git a/spec/src/main/asciidoc/appD-metamodel.adoc b/spec/src/main/asciidoc/appD-metamodel.adoc index 19036bd7..a246307c 100644 --- a/spec/src/main/asciidoc/appD-metamodel.adoc +++ b/spec/src/main/asciidoc/appD-metamodel.adoc @@ -1,12 +1,14 @@ [appendix] == Metamodel API Interfaces [[metamodel-api]] -=== `Metamodel` +The following APIs are defined in the package `jakarta.persistence.metamodel`. + +=== `Metamodel` [[_metamodel_]] [source,java] ---- include::../../../../api/src/main/java/jakarta/persistence/metamodel/Metamodel.java[lines=18..-1] ---- -=== `StaticMetamodel` +=== `StaticMetamodel` [[_staticmetamodel_]] [source,java] ---- include::../../../../api/src/main/java/jakarta/persistence/metamodel/StaticMetamodel.java[lines=18..-1] diff --git a/spec/src/main/asciidoc/appE-spi.adoc b/spec/src/main/asciidoc/appE-spi.adoc index 540048cc..b2cb5054 100644 --- a/spec/src/main/asciidoc/appE-spi.adoc +++ b/spec/src/main/asciidoc/appE-spi.adoc @@ -1,6 +1,8 @@ [appendix] == Persistence SPI Interfaces [[persistence-spi]] +The following APIs are defined in the package `jakarta.persistence.spi`. + === `ClassTransformer` [[_classtransformer_]] [source,java] ---- diff --git a/spec/src/main/asciidoc/ch03-entity-operations.adoc b/spec/src/main/asciidoc/ch03-entity-operations.adoc index ac69dd00..84c2e134 100644 --- a/spec/src/main/asciidoc/ch03-entity-operations.adoc +++ b/spec/src/main/asciidoc/ch03-entity-operations.adoc @@ -2685,16 +2685,21 @@ The following hint is defined by this specification for use in query configurati jakarta.persistence.query.timeout // time in milliseconds -This hint may be used with the `Query`, -`TypedQuery`, or `StoredProcedureQuery` `setHint` method or the -`NamedQuery`, `NamedNativeQuery`, and `NamedStoredProcedureQuery` -annotations. It may also be passed as a property to the -`Persistence.createEntityManagerFactory` method and used in the -`properties` element of the `persistence.xml` file. See <>, -<>, <>, <>. When used in -the `createEntityManagerFactory` method, the `persistence.xml` file, and -annotations, the `timeout` hint serves as a default value which can be -selectively overridden by use in the `setHint` method. +This hint may: + +- be passed to the `setHint()` method of the `Query`, `TypedQuery`, + and `StoredProcedureQuery` interfaces found in <>, +- used with the `NamedQuery`, `NamedNativeQuery`, and + `NamedStoredProcedureQuery` annotations specified in <>, +- passed as a property to the `createEntityManagerFactory()` method + of the `Persistence` class, as defined in <>, or +- used in the `properties` element of the `persistence.xml` file, as + defined in <>. + +The timeout specified by calling the `createEntityManagerFactory()` +method, via the `persistence.xml` file, or in annotations, serves as +a default value which can be selectively overridden by calling the +`setHint()` method. Portable applications should not rely on this hint. Depending on the persistence provider and database in use, the diff --git a/spec/src/main/asciidoc/ch05-metamodel-api.adoc b/spec/src/main/asciidoc/ch05-metamodel-api.adoc index 9143d98c..bcf394b4 100644 --- a/spec/src/main/asciidoc/ch05-metamodel-api.adoc +++ b/spec/src/main/asciidoc/ch05-metamodel-api.adoc @@ -8,10 +8,9 @@ This specification provides a set of interfaces for dynamically accessing a metamodel representing the managed classes of a persistence unit. Instances of metamodel types may be obtained either: -- via programmatic lookup using an instance of the interface - `jakarta.persistence.metamodel.Metamodel` obtained from the - `EntityManagerFactory` or `EntityManager` by calling - `getMetamodel()`, or +- via programmatic lookup using an instance of the interface `Metamodel` + (found in <<_metamodel_>>) obtained from the `EntityManagerFactory` or + `EntityManager` by calling `getMetamodel()`, or - in a typesafe way, using _static metamodel classes_. A static metamodel class is a class with static members providing direct @@ -47,11 +46,11 @@ this specification.] * The name of the metamodel class is derived from the name of the managed class by appending "`_`" to the name of the managed class. -* The metamodel class `X_` must be annotated with the -`jakarta.persistence.StaticMetamodel` annotationfootnote:[If the class -was generated, the `javax.annotation.processing.Generated` or `jakarta.annotation.Generated` -annotation should be used to annotate the class. The use of any other annotations on static -metamodel classes is undefined.]. +* The metamodel class `X_` must be annotated with the `StaticMetamodel` +annotation found in <<_staticmetamodel_>>.footnote:[If the class was +generated, it should also be annotated with either +`javax.annotation.processing.Generated` or `jakarta.annotation.Generated`. +The use of any other annotations on static metamodel classes is undefined.] * If the managed class `X` extends another class `S`, where `S` is the most derived managed class (i.e., entity or mapped superclass) extended diff --git a/spec/src/main/asciidoc/ch06-criteria-api.adoc b/spec/src/main/asciidoc/ch06-criteria-api.adoc index 199321f9..9c082939 100644 --- a/spec/src/main/asciidoc/ch06-criteria-api.adoc +++ b/spec/src/main/asciidoc/ch06-criteria-api.adoc @@ -77,8 +77,7 @@ of the criteria API is described in <>. === Constructing Criteria Queries [[a10614]] A criteria query is constructed through the creation and modification of -an instance of `jakarta.persistence.criteria.CriteriaQuery`. This interface -is found in <<_criteriaquery_>>. +an instance of the `CriteriaQuery` interface found in <<_criteriaquery_>>. The `CriteriaBuilder` interface found in <<_criteriabuilder_>> is used to construct `CriteriaQuery`, `CriteriaUpdate`, and `CriteriaDelete` objects. diff --git a/spec/src/main/asciidoc/ch09-container-provider-contracts.adoc b/spec/src/main/asciidoc/ch09-container-provider-contracts.adoc index c9f5240e..ad05d536 100644 --- a/spec/src/main/asciidoc/ch09-container-provider-contracts.adoc +++ b/spec/src/main/asciidoc/ch09-container-provider-contracts.adoc @@ -724,12 +724,12 @@ be used for vendor-specific information. The namespace === jakarta.persistence.PersistenceConfiguration Class [[a13444]] -The `PersistenceConfiguration` class is used to programmatically define and -configure a persistence unit and create an `EntityManagerFactory` instance -directly. Thus, `PersistenceConfiguration` is an alternative to XML-based -configuration using `persistence.xml`, and so the configuration options -available via this API reflect the similarly-named elements of -`persistence.xml`. See <>. +The `PersistenceConfiguration` class found in <<_persistenceconfiguration_>> +is used to programmatically define and configure a persistence unit and create +an `EntityManagerFactory` instance directly. Thus, `PersistenceConfiguration` +is an alternative to XML-based configuration using `persistence.xml`, and so +the configuration options available via this API reflect the similarly-named +elements of `persistence.xml`. See <>. A programmatically-configured persistence unit is considered a Java SE persistence unit, even when this API is used within the Jakarta EE diff --git a/spec/src/main/asciidoc/ch10-metadata-annotations.adoc b/spec/src/main/asciidoc/ch10-metadata-annotations.adoc index 8f82da0e..9a20ce56 100644 --- a/spec/src/main/asciidoc/ch10-metadata-annotations.adoc +++ b/spec/src/main/asciidoc/ch10-metadata-annotations.adoc @@ -235,6 +235,8 @@ public @interface NamedSubgraph { === Annotations for Queries [[a13710]] +The following annotations are used to declare named queries. + ==== NamedQuery Annotation [[a13711]] The `NamedQuery` annotation declared a named query written in the Jakarta