JavaEE API 8.0.1 · javax.persistence.EntityManager

Method Summary

Modifier and Type	Method and Description
public void	clear() Clear the persistence context, causing all managed entities to become detached.
public void	close() Close an application-managed entity manager.
public boolean	Returns: boolean indicating if entity is in persistence context contains(Object entity instance entity) Check if the instance is a managed entity instance belonging to the current persistence context.
public <T> EntityGraph<T>	Returns: entity graph createEntityGraph(Class<T> class of entity graph rootType) Return a mutable EntityGraph that can be used to dynamically create an EntityGraph.
public EntityGraph<?>	Returns: entity graph createEntityGraph(String name of an entity graph graphName) Return a mutable copy of the named EntityGraph.
public Query	Returns: the new query instance createNamedQuery(String the name of a query defined in metadata name) Create an instance of `Query` for executing a named query (in the Java Persistence query language or in native SQL).
public <T> TypedQuery<T>	Returns: the new query instance createNamedQuery(String the name of a query defined in metadata name, Class<T> the type of the query result resultClass) Create an instance of `TypedQuery` for executing a Java Persistence query language named query.
public StoredProcedureQuery	Returns: the new stored procedure query instance createNamedStoredProcedureQuery(String name assigned to the stored procedure query in metadata name) Create an instance of `StoredProcedureQuery` for executing a stored procedure in the database.
public Query	Returns: the new query instance createNativeQuery(String a native SQL query string sqlString) Create an instance of `Query` for executing a native SQL statement, e.g., for update or delete.
public Query	Returns: the new query instance createNativeQuery(String a native SQL query string sqlString, Class<T> the class of the resulting instance(s) resultClass) Create an instance of `Query` for executing a native SQL query.
public Query	Returns: the new query instance createNativeQuery(String a native SQL query string sqlString, String the name of the result set mapping resultSetMapping) Create an instance of `Query` for executing a native SQL query.
public Query	Returns: the new query instance createQuery(String a Java Persistence query string qlString) Create an instance of `Query` for executing a Java Persistence query language statement.
public <T> TypedQuery<T>	Returns: the new query instance createQuery(CriteriaQuery<T> a criteria query object criteriaQuery) Create an instance of `TypedQuery` for executing a criteria query.
public Query	Returns: the new query instance createQuery(CriteriaUpdate<T> a criteria update query object updateQuery) Create an instance of `Query` for executing a criteria update query.
public Query	Returns: the new query instance createQuery(CriteriaDelete<T> a criteria delete query object deleteQuery) Create an instance of `Query` for executing a criteria delete query.
public <T> TypedQuery<T>	Returns: the new query instance createQuery(String a Java Persistence query string qlString, Class<T> the type of the query result resultClass) Create an instance of `TypedQuery` for executing a Java Persistence query language statement.
public StoredProcedureQuery	Returns: the new stored procedure query instance createStoredProcedureQuery(String name of the stored procedure in the database procedureName) Create an instance of `StoredProcedureQuery` for executing a stored procedure in the database.
public StoredProcedureQuery	Returns: the new stored procedure query instance createStoredProcedureQuery(String name of the stored procedure in the database procedureName, Class<T>... classes to which the result sets produced by the stored procedure are to be mapped resultClasses) Create an instance of `StoredProcedureQuery` for executing a stored procedure in the database.
public StoredProcedureQuery	Returns: the new stored procedure query instance createStoredProcedureQuery(String name of the stored procedure in the database procedureName, String... the names of the result set mappings to be used in mapping result sets returned by the stored procedure resultSetMappings) Create an instance of `StoredProcedureQuery` for executing a stored procedure in the database.
public void	detach(Object entity instance entity) Remove the given entity from the persistence context, causing a managed entity to become detached.
public <T> T	Returns: the found entity instance or null if the entity does not exist find(Class<T> entity class entityClass, Object primary key primaryKey) Find by primary key.
public <T> T	Returns: the found entity instance or null if the entity does not exist find(Class<T> entity class entityClass, Object primary key primaryKey, Map<String, Object> standard and vendor-specific properties and hints properties) Find by primary key, using the specified properties.
public <T> T	Returns: the found entity instance or null if the entity does not exist find(Class<T> entity class entityClass, Object primary key primaryKey, LockModeType lock mode lockMode) Find by primary key and lock.
public <T> T	Returns: the found entity instance or null if the entity does not exist find(Class<T> entity class entityClass, Object primary key primaryKey, LockModeType lock mode lockMode, Map<String, Object> standard and vendor-specific properties and hints properties) Find by primary key and lock, using the specified properties.
public void	flush() Synchronize the persistence context to the underlying database.
public CriteriaBuilder	Returns: CriteriaBuilder instance getCriteriaBuilder() Return an instance of `CriteriaBuilder` for the creation of `CriteriaQuery` objects.
public Object	Returns: underlying provider object for EntityManager getDelegate() Return the underlying provider object for the `EntityManager`, if available.
public EntityGraph<?>	Returns: named entity graph getEntityGraph(String name of an existing entity graph graphName) Return a named EntityGraph.
public <T> List<EntityGraph<? super T>>	Returns: list of all entity graphs defined for the entity getEntityGraphs(Class<T> entity class entityClass) Return all named EntityGraphs that have been defined for the provided class type.
public EntityManagerFactory	Returns: EntityManagerFactory instance getEntityManagerFactory() Return the entity manager factory for the entity manager.
public FlushModeType	Returns: flushMode getFlushMode() Get the flush mode that applies to all objects contained in the persistence context.
public LockModeType	Returns: lock mode getLockMode(Object entity instance entity) Get the current lock mode for the entity instance.
public Metamodel	Returns: Metamodel instance getMetamodel() Return an instance of `Metamodel` interface for access to the metamodel of the persistence unit.
public Map<String, Object>	Returns: map of properties and hints in effect for entity manager getProperties() Get the properties and hints and associated values that are in effect for the entity manager.
public <T> T	Returns: the found entity instance getReference(Class<T> entity class entityClass, Object primary key primaryKey) Get an instance, whose state may be lazily fetched.
public EntityTransaction	Returns: EntityTransaction instance getTransaction() Return the resource-level `EntityTransaction` object.
public boolean	Returns: boolean isJoinedToTransaction() Determine whether the entity manager is joined to the current transaction.
public boolean	Returns: true until the entity manager has been closed isOpen() Determine whether the entity manager is open.
public void	joinTransaction() Indicate to the entity manager that a JTA transaction is active and join the persistence context to it.
public void	lock(Object entity instance entity, LockModeType lock mode lockMode) Lock an entity instance that is contained in the persistence context with the specified lock mode type.
public void	lock(Object entity instance entity, LockModeType lock mode lockMode, Map<String, Object> standard and vendor-specific properties and hints properties) Lock an entity instance that is contained in the persistence context with the specified lock mode type and with specified properties.
public <T> T	Returns: the managed instance that the state was merged to merge(T entity instance entity) Merge the state of the given entity into the current persistence context.
public void	persist(Object entity instance entity) Make an instance managed and persistent.
public void	refresh(Object entity instance entity) Refresh the state of the instance from the database, overwriting changes made to the entity, if any.
public void	refresh(Object entity instance entity, Map<String, Object> standard and vendor-specific properties and hints properties) Refresh the state of the instance from the database, using the specified properties, and overwriting changes made to the entity, if any.
public void	refresh(Object entity instance entity, LockModeType lock mode 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.
public void	refresh(Object entity instance entity, LockModeType lock mode lockMode, Map<String, Object> standard and vendor-specific properties and hints 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 and with specified properties.
public void	remove(Object entity instance entity) Remove the entity instance.
public void	setFlushMode(FlushModeType flush mode flushMode) Set the flush mode that applies to all objects contained in the persistence context.
public void	setProperty(String name of property or hint propertyName, Object value for property or hint value) Set an entity manager property or hint.
public <T> T	Returns: an instance of the specified class unwrap(Class<T> the class of the object to be returned. This is normally either the underlying `EntityManager` implementation class or an interface that it implements. cls) Return an object of the specified type to allow access to the provider-specific API.

Method Detail

clear	back to summary
public void clear() 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.

close back to summary

close	back to summary
public void close() 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. Exceptions IllegalStateException: if the entity manager is container-managed

public void close()

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.

Exceptions

IllegalStateException:: if the entity manager is container-managed

contains	back to summary
public boolean contains(Object entity) Check if the instance is a managed entity instance belonging to the current persistence context. Parameters entity:Object entity instance Returns:boolean boolean indicating if entity is in persistence context Exceptions IllegalArgumentException: if not an entity

contains

back to summary

public boolean contains(Object entity)

Check if the instance is a managed entity instance belonging to the current persistence context.

Parameters

entity:Object: entity instance

Returns:boolean

boolean indicating if entity is in persistence context

Exceptions

IllegalArgumentException:: if not an entity

createEntityGraph	back to summary
public <T> EntityGraph<T> createEntityGraph(Class<T> rootType) Return a mutable EntityGraph that can be used to dynamically create an EntityGraph. Parameters rootType:Class<T> class of entity graph Returns:EntityGraph<T> entity graph Since Java Persistence 2.1

createEntityGraph

back to summary

public <T> EntityGraph<T> createEntityGraph(Class<T> rootType)

Return a mutable EntityGraph that can be used to dynamically create an EntityGraph.

Parameters

rootType:Class<T>: class of entity graph

Returns:EntityGraph<T>

entity graph

Since

Java Persistence 2.1

createEntityGraph	back to summary
public EntityGraph<?> createEntityGraph(String graphName) Return a mutable copy of the named EntityGraph. If there is no entity graph with the specified name, null is returned. Parameters graphName:String name of an entity graph Returns:EntityGraph<?> entity graph Since Java Persistence 2.1

createEntityGraph

back to summary

public EntityGraph<?> createEntityGraph(String graphName)

Return a mutable copy of the named EntityGraph. If there is no entity graph with the specified name, null is returned.

Parameters

graphName:String: name of an entity graph

Returns:EntityGraph<?>

entity graph

Since

Java Persistence 2.1

createNamedQuery back to summary

createNamedQuery	back to summary
public Query createNamedQuery(String name) Create an instance of `Query` for executing a named query (in the Java Persistence query language or in native SQL). Parameters name:String the name of a query defined in metadata Returns:Query the new query instance Exceptions 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 Query for executing a named query (in the Java Persistence query language or in native SQL).

Parameters

name:String: the name of a query defined in metadata

Returns:Query

the new query instance

Exceptions

IllegalArgumentException:: if a query has not been defined with the given name or if the query string is found to be invalid

createNamedQuery back to summary

createNamedQuery	back to summary
public <T> TypedQuery<T> createNamedQuery(String name, Class<T> resultClass) Create an instance of `TypedQuery` for executing a Java 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. Parameters name:String the name of a query defined in metadata resultClass:Class<T> the type of the query result Returns:TypedQuery<T> the new query instance Exceptions 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 Java Persistence 2.0

public <T> TypedQuery<T> createNamedQuery(String name, Class<T> resultClass)

Create an instance of TypedQuery for executing a Java 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.

Parameters

name:String: the name of a query defined in metadata
resultClass:Class<T>: the type of the query result

Returns:TypedQuery<T>

the new query instance

Exceptions

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

Java Persistence 2.0

createNamedStoredProcedureQuery back to summary

createNamedStoredProcedureQuery	back to summary
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[]. Parameters name:String name assigned to the stored procedure query in metadata Returns:StoredProcedureQuery the new stored procedure query instance Exceptions IllegalArgumentException: if a query has not been defined with the given name Since Java Persistence 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[].

Parameters

name:String: name assigned to the stored procedure query in metadata

Returns:StoredProcedureQuery

the new stored procedure query instance

Exceptions

IllegalArgumentException:: if a query has not been defined with the given name

Since

Java Persistence 2.1

createNativeQuery back to summary

createNativeQuery	back to summary
public Query createNativeQuery(String sqlString) 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. Parameters sqlString:String a native SQL query string Returns:Query the new query instance

public Query createNativeQuery(String sqlString)

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.

Parameters

sqlString:String: a native SQL query string

Returns:Query

the new query instance

createNativeQuery back to summary

createNativeQuery	back to summary
public Query createNativeQuery(String sqlString, Class<T> resultClass) Create an instance of `Query` for executing a native SQL query. Parameters sqlString:String a native SQL query string resultClass:Class<T> the class of the resulting instance(s) Returns:Query the new query instance

public Query createNativeQuery(String sqlString, Class<T> resultClass)

Create an instance of Query for executing a native SQL query.

Parameters

sqlString:String: a native SQL query string
resultClass:Class<T>: the class of the resulting instance(s)

Returns:Query

the new query instance

createNativeQuery back to summary

createNativeQuery	back to summary
public Query createNativeQuery(String sqlString, String resultSetMapping) Create an instance of `Query` for executing a native SQL query. Parameters sqlString:String a native SQL query string resultSetMapping:String the name of the result set mapping Returns:Query the new query instance

public Query createNativeQuery(String sqlString, String resultSetMapping)

Create an instance of Query for executing a native SQL query.

Parameters

sqlString:String: a native SQL query string
resultSetMapping:String: the name of the result set mapping

Returns:Query

the new query instance

createQuery back to summary

createQuery	back to summary
public Query createQuery(String qlString) Create an instance of `Query` for executing a Java Persistence query language statement. Parameters qlString:String a Java Persistence query string Returns:Query the new query instance Exceptions IllegalArgumentException: if the query string is found to be invalid

public Query createQuery(String qlString)

Create an instance of Query for executing a Java Persistence query language statement.

Parameters

qlString:String: a Java Persistence query string

Returns:Query

the new query instance

Exceptions

IllegalArgumentException:: if the query string is found to be invalid

createQuery back to summary

createQuery	back to summary
public <T> TypedQuery<T> createQuery(CriteriaQuery<T> criteriaQuery) Create an instance of `TypedQuery` for executing a criteria query. Parameters criteriaQuery:CriteriaQuery<T> a criteria query object Returns:TypedQuery<T> the new query instance Exceptions IllegalArgumentException: if the criteria query is found to be invalid Since Java Persistence 2.0

public <T> TypedQuery<T> createQuery(CriteriaQuery<T> criteriaQuery)

Create an instance of TypedQuery for executing a criteria query.

Parameters

criteriaQuery:CriteriaQuery<T>: a criteria query object

Returns:TypedQuery<T>

the new query instance

Exceptions

IllegalArgumentException:: if the criteria query is found to be invalid

Since

Java Persistence 2.0

createQuery back to summary

createQuery	back to summary
public Query createQuery(CriteriaUpdate<T> updateQuery) Create an instance of `Query` for executing a criteria update query. Parameters updateQuery:CriteriaUpdate<T> a criteria update query object Returns:Query the new query instance Exceptions IllegalArgumentException: if the update query is found to be invalid Since Java Persistence 2.1

public Query createQuery(CriteriaUpdate<T> updateQuery)

Create an instance of Query for executing a criteria update query.

Parameters

updateQuery:CriteriaUpdate<T>: a criteria update query object

Returns:Query

the new query instance

Exceptions

IllegalArgumentException:: if the update query is found to be invalid

Since

Java Persistence 2.1

createQuery back to summary

createQuery	back to summary
public Query createQuery(CriteriaDelete<T> deleteQuery) Create an instance of `Query` for executing a criteria delete query. Parameters deleteQuery:CriteriaDelete<T> a criteria delete query object Returns:Query the new query instance Exceptions IllegalArgumentException: if the delete query is found to be invalid Since Java Persistence 2.1

public Query createQuery(CriteriaDelete<T> deleteQuery)

Create an instance of Query for executing a criteria delete query.

Parameters

deleteQuery:CriteriaDelete<T>: a criteria delete query object

Returns:Query

the new query instance

Exceptions

IllegalArgumentException:: if the delete query is found to be invalid

Since

Java Persistence 2.1

createQuery back to summary

createQuery	back to summary
public <T> TypedQuery<T> createQuery(String qlString, Class<T> resultClass) Create an instance of `TypedQuery` for executing a Java 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. Parameters qlString:String a Java Persistence query string resultClass:Class<T> the type of the query result Returns:TypedQuery<T> the new query instance Exceptions 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 Java Persistence 2.0

public <T> TypedQuery<T> createQuery(String qlString, Class<T> resultClass)

Create an instance of TypedQuery for executing a Java 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.

Parameters

qlString:String: a Java Persistence query string
resultClass:Class<T>: the type of the query result

Returns:TypedQuery<T>

the new query instance

Exceptions

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

Java Persistence 2.0

createStoredProcedureQuery back to summary

createStoredProcedureQuery	back to summary
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. If the stored procedure returns one or more result sets, any result set will be returned as a list of type Object[]. Parameters procedureName:String name of the stored procedure in the database Returns:StoredProcedureQuery the new stored procedure query instance Exceptions IllegalArgumentException: if a stored procedure of the given name does not exist (or the query execution will fail) Since Java Persistence 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.

If the stored procedure returns one or more result sets, any result set will be returned as a list of type Object[].

Parameters

procedureName:String: name of the stored procedure in the database

Returns:StoredProcedureQuery

the new stored procedure query instance

Exceptions

IllegalArgumentException:: if a stored procedure of the given name does not exist (or the query execution will fail)

Since

Java Persistence 2.1

createStoredProcedureQuery back to summary

createStoredProcedureQuery	back to summary
public StoredProcedureQuery createStoredProcedureQuery(String procedureName, Class<T>... 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 `resultClass` arguments must be specified in the order in which the result sets will be returned by the stored procedure invocation. Parameters procedureName:String name of the stored procedure in the database resultClasses:Class<T>[] classes to which the result sets produced by the stored procedure are to be mapped Returns:StoredProcedureQuery the new stored procedure query instance Exceptions IllegalArgumentException: if a stored procedure of the given name does not exist (or the query execution will fail) Since Java Persistence 2.1

public StoredProcedureQuery createStoredProcedureQuery(String procedureName, Class<T>... 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 resultClass arguments must be specified in the order in which the result sets will be returned by the stored procedure invocation.

Parameters

procedureName:String: name of the stored procedure in the database
resultClasses:Class<T>[]: classes to which the result sets produced by the stored procedure are to be mapped

Returns:StoredProcedureQuery

the new stored procedure query instance

Exceptions

IllegalArgumentException:: if a stored procedure of the given name does not exist (or the query execution will fail)

Since

Java Persistence 2.1

createStoredProcedureQuery back to summary

createStoredProcedureQuery	back to summary
public StoredProcedureQuery createStoredProcedureQuery(String procedureName, String... resultSetMappings) 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. Parameters procedureName:String name of the stored procedure in the database resultSetMappings:String[] the names of the result set mappings to be used in mapping result sets returned by the stored procedure Returns:StoredProcedureQuery the new stored procedure query instance Exceptions 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)

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.

Parameters

procedureName:String: name of the stored procedure in the database
resultSetMappings:String[]: the names of the result set mappings to be used in mapping result sets returned by the stored procedure

Returns:StoredProcedureQuery

the new stored procedure query instance

Exceptions

IllegalArgumentException:: if a stored procedure or result set mapping of the given name does not exist (or the query execution will fail)

detach	back to summary
public void detach(Object entity) 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. Parameters entity:Object entity instance Exceptions IllegalArgumentException: if the instance is not an entity Since Java Persistence 2.0

detach

back to summary

public void detach(Object entity)

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.

Parameters

entity:Object: entity instance

Exceptions

IllegalArgumentException:: if the instance is not an entity

Since

Java Persistence 2.0

find	back to summary
public <T> T find(Class<T> entityClass, Object primaryKey) 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. Parameters entityClass:Class<T> entity class primaryKey:Object primary key Returns:T the found entity instance or null if the entity does not exist Exceptions 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

find

back to summary

public <T> T find(Class<T> entityClass, Object primaryKey)

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.

Parameters

entityClass:Class<T>: entity class
primaryKey:Object: primary key

Returns:T

the found entity instance or null if the entity does not exist

Exceptions

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

find	back to summary
public <T> T find(Class<T> entityClass, Object primaryKey, Map<String, Object> properties) 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. Parameters entityClass:Class<T> entity class primaryKey:Object primary key properties:Map<String, Object> standard and vendor-specific properties and hints Returns:T the found entity instance or null if the entity does not exist Exceptions 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 Java Persistence 2.0

find

back to summary

public <T> T find(Class<T> entityClass, Object primaryKey, Map<String, Object> properties)

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.

Parameters

entityClass:Class<T>: entity class
primaryKey:Object: primary key
properties:Map<String, Object>: standard and vendor-specific properties and hints

Returns:T

the found entity instance or null if the entity does not exist

Exceptions

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

Java Persistence 2.0

find back to summary

find	back to summary
public <T> T find(Class<T> entityClass, Object primaryKey, LockModeType lockMode) 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: 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 Parameters entityClass:Class<T> entity class primaryKey:Object primary key lockMode:LockModeType lock mode Returns:T the found entity instance or null if the entity does not exist Exceptions 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 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 OptimisticLockException: if the optimistic version check fails PessimisticLockException: if pessimistic locking fails and the transaction is rolled back LockTimeoutException: if pessimistic locking fails and only the statement is rolled back PersistenceException: if an unsupported lock call is made Since Java Persistence 2.0

public <T> T find(Class<T> entityClass, Object primaryKey, LockModeType lockMode)

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:

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

Parameters

entityClass:Class<T>: entity class
primaryKey:Object: primary key
lockMode:LockModeType: lock mode

Returns:T

the found entity instance or null if the entity does not exist

Exceptions

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
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
OptimisticLockException:: if the optimistic version check fails
PessimisticLockException:: if pessimistic locking fails and the transaction is rolled back
LockTimeoutException:: if pessimistic locking fails and only the statement is rolled back
PersistenceException:: if an unsupported lock call is made

Since

Java Persistence 2.0

find back to summary

find	back to summary
public <T> T find(Class<T> entityClass, Object primaryKey, LockModeType lockMode, Map<String, Object> properties) 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. Parameters entityClass:Class<T> entity class primaryKey:Object primary key lockMode:LockModeType lock mode properties:Map<String, Object> standard and vendor-specific properties and hints Returns:T the found entity instance or null if the entity does not exist Exceptions 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 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 OptimisticLockException: if the optimistic version check fails PessimisticLockException: if pessimistic locking fails and the transaction is rolled back LockTimeoutException: if pessimistic locking fails and only the statement is rolled back PersistenceException: if an unsupported lock call is made Since Java Persistence 2.0

public <T> T find(Class<T> entityClass, Object primaryKey, LockModeType lockMode, Map<String, Object> properties)

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 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.

Parameters

entityClass:Class<T>: entity class
primaryKey:Object: primary key
lockMode:LockModeType: lock mode
properties:Map<String, Object>: standard and vendor-specific properties and hints

Returns:T

the found entity instance or null if the entity does not exist

Exceptions

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
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
OptimisticLockException:: if the optimistic version check fails
PessimisticLockException:: if pessimistic locking fails and the transaction is rolled back
LockTimeoutException:: if pessimistic locking fails and only the statement is rolled back
PersistenceException:: if an unsupported lock call is made

Since

Java Persistence 2.0

flush	back to summary
public void flush() Synchronize the persistence context to the underlying database. Exceptions TransactionRequiredException: if there is no transaction or if the entity manager has not been joined to the current transaction PersistenceException: if the flush fails

flush

back to summary

public void flush()

Synchronize the persistence context to the underlying database.

Exceptions

TransactionRequiredException:: if there is no transaction or if the entity manager has not been joined to the current transaction
PersistenceException:: if the flush fails

getCriteriaBuilder back to summary

getCriteriaBuilder	back to summary
public CriteriaBuilder getCriteriaBuilder() Return an instance of `CriteriaBuilder` for the creation of `CriteriaQuery` objects. Returns:CriteriaBuilder CriteriaBuilder instance Exceptions IllegalStateException: if the entity manager has been closed Since Java Persistence 2.0

public CriteriaBuilder getCriteriaBuilder()

Return an instance of CriteriaBuilder for the creation of CriteriaQuery objects.

Returns:CriteriaBuilder

CriteriaBuilder instance

Exceptions

IllegalStateException:: if the entity manager has been closed

Since

Java Persistence 2.0

getDelegate back to summary

getDelegate	back to summary
public Object getDelegate() 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. Returns:Object underlying provider object for EntityManager

public Object getDelegate()

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.

Returns:Object: underlying provider object for EntityManager

getEntityGraph	back to summary
public EntityGraph<?> getEntityGraph(String graphName) Return a named EntityGraph. The returned EntityGraph should be considered immutable. Parameters graphName:String name of an existing entity graph Returns:EntityGraph<?> named entity graph Exceptions IllegalArgumentException: if there is no EntityGraph of the given name Since Java Persistence 2.1

getEntityGraph

back to summary

public EntityGraph<?> getEntityGraph(String graphName)

Return a named EntityGraph. The returned EntityGraph should be considered immutable.

Parameters

graphName:String: name of an existing entity graph

Returns:EntityGraph<?>

named entity graph

Exceptions

IllegalArgumentException:: if there is no EntityGraph of the given name

Since

Java Persistence 2.1

getEntityGraphs	back to summary
public <T> List<EntityGraph<? super T>> getEntityGraphs(Class<T> entityClass) Return all named EntityGraphs that have been defined for the provided class type. Parameters entityClass:Class<T> entity class Returns:List<EntityGraph<? super T>> list of all entity graphs defined for the entity Exceptions IllegalArgumentException: if the class is not an entity Since Java Persistence 2.1

getEntityGraphs

back to summary

public <T> List<EntityGraph<? super T>> getEntityGraphs(Class<T> entityClass)

Return all named EntityGraphs that have been defined for the provided class type.

Parameters

entityClass:Class<T>: entity class

Returns:List<EntityGraph<? super T>>

list of all entity graphs defined for the entity

Exceptions

IllegalArgumentException:: if the class is not an entity

Since

Java Persistence 2.1

getEntityManagerFactory	back to summary
public EntityManagerFactory getEntityManagerFactory() Return the entity manager factory for the entity manager. Returns:EntityManagerFactory EntityManagerFactory instance Exceptions IllegalStateException: if the entity manager has been closed Since Java Persistence 2.0

getEntityManagerFactory

back to summary

public EntityManagerFactory getEntityManagerFactory()

Return the entity manager factory for the entity manager.

Returns:EntityManagerFactory

EntityManagerFactory instance

Exceptions

IllegalStateException:: if the entity manager has been closed

Since

Java Persistence 2.0

getFlushMode	back to summary
public FlushModeType getFlushMode() Get the flush mode that applies to all objects contained in the persistence context. Returns:FlushModeType flushMode

getFlushMode

back to summary

public FlushModeType getFlushMode()

Get the flush mode that applies to all objects contained in the persistence context.

Returns:FlushModeType: flushMode

getLockMode	back to summary
public LockModeType getLockMode(Object entity) Get the current lock mode for the entity instance. Parameters entity:Object entity instance Returns:LockModeType lock mode Exceptions TransactionRequiredException: if there is no transaction or if the entity manager has not been joined to the current transaction IllegalArgumentException: if the instance is not a managed entity and a transaction is active Since Java Persistence 2.0

getLockMode

back to summary

public LockModeType getLockMode(Object entity)

Get the current lock mode for the entity instance.

Parameters

entity:Object: entity instance

Returns:LockModeType

lock mode

Exceptions

TransactionRequiredException:: if there is no transaction or if the entity manager has not been joined to the current transaction
IllegalArgumentException:: if the instance is not a managed entity and a transaction is active

Since

Java Persistence 2.0

getMetamodel back to summary

getMetamodel	back to summary
public Metamodel getMetamodel() Return an instance of `Metamodel` interface for access to the metamodel of the persistence unit. Returns:Metamodel Metamodel instance Exceptions IllegalStateException: if the entity manager has been closed Since Java Persistence 2.0

public Metamodel getMetamodel()

Return an instance of Metamodel interface for access to the metamodel of the persistence unit.

Returns:Metamodel

Metamodel instance

Exceptions

IllegalStateException:: if the entity manager has been closed

Since

Java Persistence 2.0

getProperties	back to summary
public Map<String, Object> getProperties() 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. Returns:Map<String, Object> map of properties and hints in effect for entity manager Since Java Persistence 2.0

getProperties

back to summary

public Map<String, Object> getProperties()

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.

Returns:Map<String, Object>: map of properties and hints in effect for entity manager
Since: Java Persistence 2.0

getReference back to summary

getReference	back to summary
public <T> T getReference(Class<T> entityClass, Object primaryKey) Get an instance, 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 to throw the `EntityNotFoundException` when `getReference` is called.) The application should not expect that the instance state will be available upon detachment, unless it was accessed by the application while the entity manager was open. Parameters entityClass:Class<T> entity class primaryKey:Object primary key Returns:T the found entity instance Exceptions 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 EntityNotFoundException: if the entity state cannot be accessed

public <T> T getReference(Class<T> entityClass, Object primaryKey)

Get an instance, 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 to throw the EntityNotFoundException when getReference is called.) The application should not expect that the instance state will be available upon detachment, unless it was accessed by the application while the entity manager was open.

Parameters

entityClass:Class<T>: entity class
primaryKey:Object: primary key

Returns:T

the found entity instance

Exceptions

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
EntityNotFoundException:: if the entity state cannot be accessed

getTransaction back to summary

getTransaction	back to summary
public EntityTransaction getTransaction() Return the resource-level `EntityTransaction` object. The `EntityTransaction` instance may be used serially to begin and commit multiple transactions. Returns:EntityTransaction EntityTransaction instance Exceptions IllegalStateException: if invoked on a JTA entity manager

public EntityTransaction getTransaction()

Return the resource-level EntityTransaction object. The EntityTransaction instance may be used serially to begin and commit multiple transactions.

Returns:EntityTransaction

EntityTransaction instance

Exceptions

IllegalStateException:: if invoked on a JTA entity manager

isJoinedToTransaction	back to summary
public boolean isJoinedToTransaction() 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 Returns:boolean boolean Since Java Persistence 2.1

isJoinedToTransaction

back to summary

public boolean isJoinedToTransaction()

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

Returns:boolean: boolean
Since: Java Persistence 2.1

isOpen	back to summary
public boolean isOpen() Determine whether the entity manager is open. Returns:boolean true until the entity manager has been closed

isOpen

back to summary

public boolean isOpen()

Determine whether the entity manager is open.

Returns:boolean: true until the entity manager has been closed

joinTransaction back to summary

joinTransaction	back to summary
public void joinTransaction() 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. Exceptions TransactionRequiredException: if there is no transaction

public void joinTransaction()

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.

Exceptions

TransactionRequiredException:: if there is no transaction

lock back to summary

lock	back to summary
public void lock(Object entity, LockModeType lockMode) 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 Parameters entity:Object entity instance lockMode:LockModeType lock mode Exceptions IllegalArgumentException: if the instance is not an entity or is a detached entity TransactionRequiredException: if there is no transaction or if invoked on an entity manager which has not been joined to the current transaction EntityNotFoundException: if the entity does not exist in the database when pessimistic locking is performed OptimisticLockException: if the optimistic version check fails PessimisticLockException: if pessimistic locking fails and the transaction is rolled back LockTimeoutException: if pessimistic locking fails and only the statement is rolled back 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.

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

Parameters

entity:Object: entity instance
lockMode:LockModeType: lock mode

Exceptions

IllegalArgumentException:: if the instance is not an entity or is a detached entity
TransactionRequiredException:: if there is no transaction or if invoked on an entity manager which has not been joined to the current transaction
EntityNotFoundException:: if the entity does not exist in the database when pessimistic locking is performed
OptimisticLockException:: if the optimistic version check fails
PessimisticLockException:: if pessimistic locking fails and the transaction is rolled back
LockTimeoutException:: if pessimistic locking fails and only the statement is rolled back
PersistenceException:: if an unsupported lock call is made

lock back to summary

lock	back to summary
public void lock(Object entity, LockModeType lockMode, Map<String, Object> properties) 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. Parameters entity:Object entity instance lockMode:LockModeType lock mode properties:Map<String, Object> standard and vendor-specific properties and hints Exceptions IllegalArgumentException: if the instance is not an entity or is a detached entity TransactionRequiredException: if there is no transaction or if invoked on an entity manager which has not been joined to the current transaction EntityNotFoundException: if the entity does not exist in the database when pessimistic locking is performed OptimisticLockException: if the optimistic version check fails PessimisticLockException: if pessimistic locking fails and the transaction is rolled back LockTimeoutException: if pessimistic locking fails and only the statement is rolled back PersistenceException: if an unsupported lock call is made Since Java Persistence 2.0

public void lock(Object entity, LockModeType lockMode, Map<String, Object> properties)

Lock an entity instance that is contained in the persistence context with the specified 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.

Parameters

entity:Object: entity instance
lockMode:LockModeType: lock mode
properties:Map<String, Object>: standard and vendor-specific properties and hints

Exceptions

IllegalArgumentException:: if the instance is not an entity or is a detached entity
TransactionRequiredException:: if there is no transaction or if invoked on an entity manager which has not been joined to the current transaction
EntityNotFoundException:: if the entity does not exist in the database when pessimistic locking is performed
OptimisticLockException:: if the optimistic version check fails
PessimisticLockException:: if pessimistic locking fails and the transaction is rolled back
LockTimeoutException:: if pessimistic locking fails and only the statement is rolled back
PersistenceException:: if an unsupported lock call is made

Since

Java Persistence 2.0

merge back to summary

merge	back to summary
public <T> T merge(T entity) Merge the state of the given entity into the current persistence context. Parameters entity:T entity instance Returns:T the managed instance that the state was merged to Exceptions IllegalArgumentException: if instance is not an entity or is a removed entity TransactionRequiredException: if there is no transaction when invoked on a container-managed entity manager of that is of type `PersistenceContextType.TRANSACTION`

public <T> T merge(T entity)

Merge the state of the given entity into the current persistence context.

Parameters

entity:T: entity instance

Returns:T

the managed instance that the state was merged to

Exceptions

IllegalArgumentException:: if instance is not an entity or is a removed entity
TransactionRequiredException:: if there is no transaction when invoked on a container-managed entity manager of that is of type PersistenceContextType.TRANSACTION

persist back to summary

persist	back to summary
public void persist(Object entity) Make an instance managed and persistent. Parameters entity:Object entity instance Exceptions 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.) IllegalArgumentException: if the instance is not an entity 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)

Make an instance managed and persistent.

Parameters

entity:Object: entity instance

Exceptions

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.)
IllegalArgumentException:: if the instance is not an entity
TransactionRequiredException:: if there is no transaction when invoked on a container-managed entity manager of that is of type PersistenceContextType.TRANSACTION

refresh back to summary

refresh	back to summary
public void refresh(Object entity) Refresh the state of the instance from the database, overwriting changes made to the entity, if any. Parameters entity:Object entity instance Exceptions IllegalArgumentException: if the instance is not an entity or the entity is not managed TransactionRequiredException: if there is no transaction when invoked on a container-managed entity manager of type `PersistenceContextType.TRANSACTION` EntityNotFoundException: if the entity no longer exists in the database

public void refresh(Object entity)

Refresh the state of the instance from the database, overwriting changes made to the entity, if any.

Parameters

entity:Object: entity instance

Exceptions

IllegalArgumentException:: if the instance is not an entity or the entity is not managed
TransactionRequiredException:: if there is no transaction when invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION
EntityNotFoundException:: if the entity no longer exists in the database

refresh back to summary

refresh	back to summary
public void refresh(Object entity, Map<String, Object> properties) 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. Parameters entity:Object entity instance properties:Map<String, Object> standard and vendor-specific properties and hints Exceptions IllegalArgumentException: if the instance is not an entity or the entity is not managed TransactionRequiredException: if there is no transaction when invoked on a container-managed entity manager of type `PersistenceContextType.TRANSACTION` EntityNotFoundException: if the entity no longer exists in the database Since Java Persistence 2.0

public void refresh(Object entity, Map<String, Object> properties)

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.

Parameters

entity:Object: entity instance
properties:Map<String, Object>: standard and vendor-specific properties and hints

Exceptions

IllegalArgumentException:: if the instance is not an entity or the entity is not managed
TransactionRequiredException:: if there is no transaction when invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION
EntityNotFoundException:: if the entity no longer exists in the database

Since

Java Persistence 2.0

refresh back to summary

refresh	back to summary
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. 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. Parameters entity:Object entity instance lockMode:LockModeType lock mode Exceptions IllegalArgumentException: if the instance is not an entity or the entity is not managed 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 EntityNotFoundException: if the entity no longer exists in the database PessimisticLockException: if pessimistic locking fails and the transaction is rolled back LockTimeoutException: if pessimistic locking fails and only the statement is rolled back PersistenceException: if an unsupported lock call is made Since Java Persistence 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.

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.

Parameters

entity:Object: entity instance
lockMode:LockModeType: lock mode

Exceptions

IllegalArgumentException:: if the instance is not an entity or the entity is not managed
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
EntityNotFoundException:: if the entity no longer exists in the database
PessimisticLockException:: if pessimistic locking fails and the transaction is rolled back
LockTimeoutException:: if pessimistic locking fails and only the statement is rolled back
PersistenceException:: if an unsupported lock call is made

Since

Java Persistence 2.0

refresh back to summary

refresh	back to summary
public void refresh(Object entity, LockModeType lockMode, Map<String, Object> 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 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. Parameters entity:Object entity instance lockMode:LockModeType lock mode properties:Map<String, Object> standard and vendor-specific properties and hints Exceptions IllegalArgumentException: if the instance is not an entity or the entity is not managed 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 EntityNotFoundException: if the entity no longer exists in the database PessimisticLockException: if pessimistic locking fails and the transaction is rolled back LockTimeoutException: if pessimistic locking fails and only the statement is rolled back PersistenceException: if an unsupported lock call is made Since Java Persistence 2.0

public void refresh(Object entity, LockModeType lockMode, Map<String, Object> 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 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.

Parameters

entity:Object: entity instance
lockMode:LockModeType: lock mode
properties:Map<String, Object>: standard and vendor-specific properties and hints

Exceptions

IllegalArgumentException:: if the instance is not an entity or the entity is not managed
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
EntityNotFoundException:: if the entity no longer exists in the database
PessimisticLockException:: if pessimistic locking fails and the transaction is rolled back
LockTimeoutException:: if pessimistic locking fails and only the statement is rolled back
PersistenceException:: if an unsupported lock call is made

Since

Java Persistence 2.0

remove back to summary

remove	back to summary
public void remove(Object entity) Remove the entity instance. Parameters entity:Object entity instance Exceptions IllegalArgumentException: if the instance is not an entity or is a detached entity TransactionRequiredException: if invoked on a container-managed entity manager of type `PersistenceContextType.TRANSACTION` and there is no transaction

public void remove(Object entity)

Remove the entity instance.

Parameters

entity:Object: entity instance

Exceptions

IllegalArgumentException:: if the instance is not an entity or is a detached entity
TransactionRequiredException:: if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION and there is no transaction

setFlushMode	back to summary
public void setFlushMode(FlushModeType flushMode) Set the flush mode that applies to all objects contained in the persistence context. Parameters flushMode:FlushModeType flush mode

setFlushMode

back to summary

public void setFlushMode(FlushModeType flushMode)

Set the flush mode that applies to all objects contained in the persistence context.

Parameters

flushMode:FlushModeType: flush mode

setProperty

back to summary

public void setProperty(String propertyName, Object value)

Set an entity manager property or hint. If a vendor-specific property or hint is not recognized, it is silently ignored.

Parameters

propertyName:String: name of property or hint
value:Object: value for property or hint

Exceptions

IllegalArgumentException:: if the second argument is not valid for the implementation

Since

Java Persistence 2.0

unwrap back to summary

public <T> T unwrap(Class<T> cls)

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.

Parameters

cls:Class<T>: the class of the object to be returned. This is normally either the underlying EntityManager implementation class or an interface that it implements.

Returns:T

an instance of the specified class

Exceptions

PersistenceException:: if the provider does not support the call

Since

Java Persistence 2.0

public Interface EntityManager

Method Summary

Method Detail