org.datanucleus.api.jpa

Class JPAEntityManager

java.lang.Object

org.datanucleus.api.jpa.JPAEntityManager

All Implemented Interfaces:

javax.persistence.EntityManager

public class JPAEntityManager
extends Object
implements javax.persistence.EntityManager

EntityManager implementation for JPA.

Field Summary

Fields

Modifier and Type	Field and Description
protected org.datanucleus.ExecutionContext	ec The underlying ExecutionContext managing the persistence.
protected javax.persistence.EntityManagerFactory	emf Parent EntityManagerFactory.
protected JPAFetchPlan	fetchPlan Fetch Plan (extension).
protected javax.persistence.FlushModeType	flushMode The Flush Mode.
protected static org.datanucleus.util.Localiser	LOCALISER Localisation utility for output messages
protected javax.persistence.PersistenceContextType	persistenceContextType Type of Persistence Context
protected javax.persistence.EntityTransaction	tx Current Transaction (when using ResourceLocal).

Constructor Summary

Constructors

Constructor and Description
JPAEntityManager(javax.persistence.EntityManagerFactory theEMF, org.datanucleus.NucleusContext nucleusCtx, javax.persistence.PersistenceContextType contextType) Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
void	clear() Clear the persistence context, causing all managed entities to become detached.
void	close() Close an application-managed EntityManager.
boolean	contains(Object entity) Check if the instance belongs to the current persistence context.
JPAQuery	createNamedQuery(String queryName) Create an instance of Query for executing a named query (in JPQL or SQL).
<T> javax.persistence.TypedQuery<T>	createNamedQuery(String queryName, Class<T> resultClass) Create an instance of Query for executing a named query (in JPQL or SQL).
StoredProcedureQuery	createNamedStoredProcedureQuery(String procName) Create an instance of Query for executing a stored procedure.
javax.persistence.Query	createNativeQuery(String sqlString) Create an instance of Query for executing an SQL statement.
javax.persistence.Query	createNativeQuery(String sqlString, Class resultClass) Create an instance of Query for executing an SQL query.
javax.persistence.Query	createNativeQuery(String sqlString, String resultSetMapping) Create an instance of Query for executing an SQL query.
<T> javax.persistence.TypedQuery<T>	createQuery(javax.persistence.criteria.CriteriaQuery<T> criteriaQuery) Method to return a query for the specified Criteria Query.
JPAQuery	createQuery(String queryString) Create an instance of Query for executing a JPQL statement.
<T> javax.persistence.TypedQuery<T>	createQuery(String queryString, Class<T> resultClass)
StoredProcedureQuery	createStoredProcedureQuery(String procName) Create an instance of Query for executing a stored procedure.
StoredProcedureQuery	createStoredProcedureQuery(String procedureName, Class... resultClasses) Create an instance of StoredProcedureQuery for executing a stored procedure in the database.
StoredProcedureQuery	createStoredProcedureQuery(String procedureName, String... resultSetMappings) Create an instance of StoredProcedureQuery for executing a stored procedure in the database.
void	detach(Object entity) Remove the given entity from the persistence context, causing a managed entity to become detached.
<T> T	find(Class<T> entityClass, Object primaryKey, javax.persistence.LockModeType lock)
<T> T	find(Class<T> entityClass, Object primaryKey, javax.persistence.LockModeType lock, Map<String,Object> properties) Method to return the persistent object of the specified entity type with the provided PK.
<T> T	find(Class<T> entityClass, Object primaryKey, Map<String,Object> properties) Find by primary key, using the specified properties.
Object	find(Class entityClass, Object primaryKey) Method to find an object from its primary key.
void	flush() Synchronize the persistence context to the underlying database.
javax.persistence.criteria.CriteriaBuilder	getCriteriaBuilder() Return an instance of QueryBuilder for the creation of Criteria API QueryDefinition objects.
Object	getDelegate() Return the underlying provider object for the EntityManager, if available.
javax.persistence.EntityManagerFactory	getEntityManagerFactory() Return the entity manager factory for the entity manager.
org.datanucleus.ExecutionContext	getExecutionContext()
JPAFetchPlan	getFetchPlan() Acessor for the current FetchPlan
javax.persistence.FlushModeType	getFlushMode() Get the flush mode that applies to all objects contained in the persistence context.
static javax.persistence.LockModeType	getJPALockModeTypeForLockType(short lockType) Convenience method to convert from LockManager lock type to JPA LockModeType
javax.persistence.LockModeType	getLockMode(Object entity) Get the current lock mode for the entity instance.
static short	getLockTypeForJPALockModeType(javax.persistence.LockModeType lock) Convenience method to convert from the JPA LockModeType to the type expected by LockManager
javax.persistence.metamodel.Metamodel	getMetamodel() Return an instance of Metamodel interface for access to the metamodel of the persistence unit.
Map<String,Object>	getProperties() Get the properties and associated values that are in effect for the entity manager.
Object	getReference(Class entityClass, Object primaryKey) Get an instance, whose state may be lazily fetched.
Set<String>	getSupportedProperties() Get the names of the properties that are supported for use with the entity manager.
javax.persistence.EntityTransaction	getTransaction() Return the resource-level transaction object.
boolean	isOpen() Determine whether the EntityManager is open.
boolean	isTransactionActive()
void	joinTransaction() Indicate to the EntityManager that a JTA transaction is active.
void	lock(Object entity, javax.persistence.LockModeType lockMode) Set the lock mode for an entity object contained in the persistence context.
void	lock(Object entity, javax.persistence.LockModeType lock, Map<String,Object> properties) Set the lock mode for an entity object contained in the persistence context.
Object	merge(Object entity) Merge the state of the given entity into the current persistence context.
void	persist(Object entity) Make an instance managed and persistent.
void	refresh(Object entity) Refresh the state of the instance from the database, overwriting changes made to the entity, if any.
void	refresh(Object entity, javax.persistence.LockModeType lock)
void	refresh(Object entity, javax.persistence.LockModeType lock, Map<String,Object> properties)
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.
void	remove(Object entity) Remove the entity instance.
void	setFlushMode(javax.persistence.FlushModeType flushMode) Set the flush mode that applies to all objects contained in the persistence context.
void	setProperty(String propertyName, Object value) Set an entity manager property.
<T> T	unwrap(Class<T> cls) Return an object of the specified type to allow access to the provider-specific API.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOCALISER

protected static final org.datanucleus.util.Localiser LOCALISER

Localisation utility for output messages

ec

protected org.datanucleus.ExecutionContext ec

The underlying ExecutionContext managing the persistence.

emf

protected javax.persistence.EntityManagerFactory emf

Parent EntityManagerFactory.

tx

protected javax.persistence.EntityTransaction tx

Current Transaction (when using ResourceLocal). Will be null if using JTA.

flushMode

protected javax.persistence.FlushModeType flushMode

The Flush Mode.

persistenceContextType

protected javax.persistence.PersistenceContextType persistenceContextType

Type of Persistence Context

fetchPlan

protected JPAFetchPlan fetchPlan

Fetch Plan (extension).

Constructor Detail

JPAEntityManager

public JPAEntityManager(javax.persistence.EntityManagerFactory theEMF,
                org.datanucleus.NucleusContext nucleusCtx,
                javax.persistence.PersistenceContextType contextType)

Constructor.

Parameters:

theEMF - The parent EntityManagerFactory

nucleusCtx - Nucleus Context

contextType - The Persistence Context type

Method Detail

clear

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.

Specified by:

clear in interface javax.persistence.EntityManager

isOpen

public boolean isOpen()

Determine whether the EntityManager is open.

Specified by:

isOpen in interface javax.persistence.EntityManager

Returns:

true until the EntityManager has been closed.

getExecutionContext

public org.datanucleus.ExecutionContext getExecutionContext()

close

public void close()

Close an application-managed EntityManager. After the close method has been invoked, all methods on the EntityManager instance and any Query objects obtained from it will throw the IllegalStateException except for getTransaction and isOpen (which will return false). If this method is called when the EntityManager is associated with an active transaction, the persistence context remains managed until the transaction completes.

Specified by:

close in interface javax.persistence.EntityManager

Throws:

IllegalStateException - if the EntityManager is container-managed.

getEntityManagerFactory

public javax.persistence.EntityManagerFactory getEntityManagerFactory()

Return the entity manager factory for the entity manager.

Specified by:

getEntityManagerFactory in interface javax.persistence.EntityManager

Returns:

EntityManagerFactory instance

Throws:

IllegalStateException - if the entity manager has been closed.

getFetchPlan

public JPAFetchPlan getFetchPlan()

Acessor for the current FetchPlan

Returns:

The FetchPlan

contains

public boolean contains(Object entity)

Check if the instance belongs to the current persistence context.

Specified by:

contains in interface javax.persistence.EntityManager

Parameters:

entity -

Returns:

Whether it is contained in the current context

Throws:

IllegalArgumentException - if not an entity

find

public Object find(Class entityClass,
          Object primaryKey)

Method to find an object from its primary key.

Specified by:

find in interface javax.persistence.EntityManager

Parameters:

entityClass - The entity class

primaryKey - The PK value

Returns:

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

find

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 recognised, it is silently ignored.

Specified by:

find in interface javax.persistence.EntityManager

Parameters:

entityClass - Class of the entity required

primaryKey - The PK value

properties - standard and vendor-specific properties

Returns:

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

find

public <T> T find(Class<T> entityClass,
         Object primaryKey,
         javax.persistence.LockModeType lock)

Specified by:

find in interface javax.persistence.EntityManager

find

public <T> T find(Class<T> entityClass,
         Object primaryKey,
         javax.persistence.LockModeType lock,
         Map<String,Object> properties)

Method to return the persistent object of the specified entity type with the provided PK.

Specified by:

find in interface javax.persistence.EntityManager

Parameters:

entityClass - Entity type

primaryKey - PK. Can be an instanceof the PK type, or the key when using single-field

lock - Any locking to apply

properties - Any optional properties to control the operation

getDelegate

public Object getDelegate()

Return the underlying provider object for the EntityManager, if available. The result of this method is implementation specific.

Specified by:

getDelegate in interface javax.persistence.EntityManager

unwrap

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.

Specified by:

unwrap in interface javax.persistence.EntityManager

Parameters:

cls - the class of the object to be returned. This is normally either the underlying EntityManager implementation class or an interface that it implements.

Returns:

an instance of the specified class

Throws:

javax.persistence.PersistenceException - if the provider does not support the call.

getReference

public Object getReference(Class 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.

Specified by:

getReference in interface javax.persistence.EntityManager

Parameters:

entityClass - Class of the entity

primaryKey - The PK

Returns:

the found 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 entities PK

javax.persistence.EntityNotFoundException - if the entity state cannot be accessed

lock

public void lock(Object entity,
        javax.persistence.LockModeType lockMode)

Set the lock mode for an entity object contained in the persistence context.

Specified by:

lock in interface javax.persistence.EntityManager

Parameters:

entity - The Entity

lockMode - Lock mode

Throws:

javax.persistence.PersistenceException - if an unsupported lock call is made

IllegalArgumentException - if the instance is not an entity or is a detached entity

javax.persistence.TransactionRequiredException - if there is no transaction

lock

public void lock(Object entity,
        javax.persistence.LockModeType lock,
        Map<String,Object> properties)

Set the lock mode for an entity object contained in the persistence context.

Specified by:

lock in interface javax.persistence.EntityManager

Parameters:

entity - The Entity

lock - Lock mode

properties - Optional properties controlling the operation

Throws:

javax.persistence.PersistenceException - if an unsupported lock call is made

IllegalArgumentException - if the instance is not an entity or is a detached entity

javax.persistence.TransactionRequiredException - if there is no transaction

persist

public void persist(Object entity)

Make an instance managed and persistent.

Specified by:

persist in interface javax.persistence.EntityManager

Parameters:

entity - The Entity

Throws:

javax.persistence.EntityExistsException - if the entity already exists. (The EntityExistsException may be thrown when the persist operation is invoked, or the EntityExistsException/PersistenceException may be thrown at flush/commit time.)

IllegalArgumentException - if not an entity

javax.persistence.TransactionRequiredException - if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION and there is no transaction.

merge

public Object merge(Object entity)

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

Specified by:

merge in interface javax.persistence.EntityManager

Parameters:

entity - The Entity

Returns:

the instance that the state was merged to

Throws:

IllegalArgumentException - if instance is not an entity or is a removed entity

javax.persistence.TransactionRequiredException - if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION and there is no transaction.

detach

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.

Specified by:

detach in interface javax.persistence.EntityManager

Parameters:

entity -

Throws:

IllegalArgumentException - if the instance is not an entity

refresh

public void refresh(Object entity)

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

Specified by:

refresh in interface javax.persistence.EntityManager

Parameters:

entity - The Entity

Throws:

IllegalArgumentException - if not an entity or entity is not managed

javax.persistence.TransactionRequiredException - if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION and there is no transaction.

javax.persistence.EntityNotFoundException - if the entity no longer exists in the database

refresh

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 recognised, it is silently ignored.

Specified by:

refresh in interface javax.persistence.EntityManager

Parameters:

entity -

properties - standard and vendor-specific properties

Throws:

IllegalArgumentException - if the instance is not an entity or the entity is not managed

javax.persistence.TransactionRequiredException - if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION and there is no transaction.

javax.persistence.EntityNotFoundException - if the entity no longer exists in the database

refresh

public void refresh(Object entity,
           javax.persistence.LockModeType lock)

Specified by:

refresh in interface javax.persistence.EntityManager

refresh

public void refresh(Object entity,
           javax.persistence.LockModeType lock,
           Map<String,Object> properties)

Specified by:

refresh in interface javax.persistence.EntityManager

remove

public void remove(Object entity)

Remove the entity instance.

Specified by:

remove in interface javax.persistence.EntityManager

Parameters:

entity - The Entity

Throws:

IllegalArgumentException - if not an entity or if a detached entity

javax.persistence.TransactionRequiredException - if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION and there is no transaction.

flush

public void flush()

Synchronize the persistence context to the underlying database.

Specified by:

flush in interface javax.persistence.EntityManager

Throws:

javax.persistence.TransactionRequiredException - if there is no transaction

javax.persistence.PersistenceException - if the flush fails

getFlushMode

public javax.persistence.FlushModeType getFlushMode()

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

Specified by:

getFlushMode in interface javax.persistence.EntityManager

Returns:

flushMode

setFlushMode

public void setFlushMode(javax.persistence.FlushModeType flushMode)

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

Specified by:

setFlushMode in interface javax.persistence.EntityManager

Parameters:

flushMode - Mode of flush

getLockMode

public javax.persistence.LockModeType getLockMode(Object entity)

Get the current lock mode for the entity instance.

Specified by:

getLockMode in interface javax.persistence.EntityManager

Parameters:

entity - The entity in question

Returns:

lock mode

Throws:

javax.persistence.TransactionRequiredException - if there is no transaction

IllegalArgumentException - if the instance is not a managed entity and a transaction is active

getTransaction

public javax.persistence.EntityTransaction getTransaction()

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

Specified by:

getTransaction in interface javax.persistence.EntityManager

Returns:

EntityTransaction instance

Throws:

IllegalStateException - if invoked on a JTA EntityManager.

joinTransaction

public void joinTransaction()

Indicate to the EntityManager that a JTA transaction is active. This method should be called on a JTA application managed EntityManager that was created outside the scope of the active transaction to associate it with the current JTA transaction.

Specified by:

joinTransaction in interface javax.persistence.EntityManager

Throws:

javax.persistence.TransactionRequiredException - if there is no transaction.

createQuery

public <T> javax.persistence.TypedQuery<T> createQuery(javax.persistence.criteria.CriteriaQuery<T> criteriaQuery)

Method to return a query for the specified Criteria Query.

Specified by:

createQuery in interface javax.persistence.EntityManager

Parameters:

criteriaQuery - The Criteria query

Returns:

The JPA query to use

getCriteriaBuilder

public javax.persistence.criteria.CriteriaBuilder getCriteriaBuilder()

Return an instance of QueryBuilder for the creation of Criteria API QueryDefinition objects.

Specified by:

getCriteriaBuilder in interface javax.persistence.EntityManager

Returns:

QueryBuilder instance

Throws:

IllegalStateException - if the entity manager has been closed.

createNamedQuery

public <T> javax.persistence.TypedQuery<T> createNamedQuery(String queryName,
                                                   Class<T> resultClass)

Create an instance of Query for executing a named query (in JPQL or SQL).

Specified by:

createNamedQuery in interface javax.persistence.EntityManager

Parameters:

queryName - the name of a query defined in metadata

Returns:

the new query instance

Throws:

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

createNamedQuery

public JPAQuery createNamedQuery(String queryName)

Create an instance of Query for executing a named query (in JPQL or SQL).

Specified by:

createNamedQuery in interface javax.persistence.EntityManager

Parameters:

queryName - the name of a query defined in metadata

Returns:

the new query instance

Throws:

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

createNativeQuery

public javax.persistence.Query createNativeQuery(String sqlString)

Create an instance of Query for executing an SQL statement.

Specified by:

createNativeQuery in interface javax.persistence.EntityManager

Parameters:

sqlString - a native SQL query string

Returns:

the new query instance

createNativeQuery

public javax.persistence.Query createNativeQuery(String sqlString,
                                        Class resultClass)

Create an instance of Query for executing an SQL query.

Specified by:

createNativeQuery in interface javax.persistence.EntityManager

Parameters:

sqlString - a native SQL query string

resultClass - the class of the resulting instance(s)

Returns:

the new query instance

createNativeQuery

public javax.persistence.Query createNativeQuery(String sqlString,
                                        String resultSetMapping)

Create an instance of Query for executing an SQL query.

Specified by:

createNativeQuery in interface javax.persistence.EntityManager

Parameters:

sqlString - a native SQL query string

resultSetMapping - the name of the result set mapping

Returns:

the new query instance

createNamedStoredProcedureQuery

public StoredProcedureQuery createNamedStoredProcedureQuery(String procName)

Create an instance of Query for executing a stored procedure.

Parameters:

procName - the name of the stored procedure defined in metadata

Returns:

the new query instance

Throws:

IllegalArgumentException - if a stored procedure has not been defined with the given name

createStoredProcedureQuery

public StoredProcedureQuery createStoredProcedureQuery(String procName)

Create an instance of Query for executing a stored procedure.

Parameters:

procName - Name of stored procedure defined in metadata

Returns:

the new stored procedure query instance

createStoredProcedureQuery

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 resultClass arguments must be specified in the order in which the result sets will be returned by the stored procedure invocation.

Parameters:

procedureName - name of the stored procedure in the database

resultClasses - classes to which the result sets produced by the stored procedure are to be mapped

Returns:

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

createStoredProcedureQuery

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 resultSetMappings argument must be specified in the order in which the result sets will be returned by the stored procedure invocation.

Parameters:

procedureName - name of the stored procedure in the database

resultSetMappings - the names of the result set mappings to be used in mapping result sets returned by the stored procedure

Returns:

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

createQuery

public <T> javax.persistence.TypedQuery<T> createQuery(String queryString,
                                              Class<T> resultClass)

Specified by:

createQuery in interface javax.persistence.EntityManager

createQuery

public JPAQuery createQuery(String queryString)

Create an instance of Query for executing a JPQL statement.

Specified by:

createQuery in interface javax.persistence.EntityManager

Parameters:

queryString - a Java Persistence query string

Returns:

the new query instance

Throws:

IllegalArgumentException - if query string is not valid

setProperty

public void setProperty(String propertyName,
               Object value)

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

Specified by:

setProperty in interface javax.persistence.EntityManager

Parameters:

propertyName - Name of the property

value - The value

Throws:

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

getProperties

public Map<String,Object> getProperties()

Get the properties and associated values that are in effect for the entity manager. Changing the contents of the map does not change the configuration in effect.

Specified by:

getProperties in interface javax.persistence.EntityManager

getSupportedProperties

public Set<String> getSupportedProperties()

Get the names of the properties that are supported for use with the entity manager. These correspond to properties and hints that may be passed to the methods of the EntityManager interface that take a properties argument or used with the PersistenceContext annotation. These properties include all standard entity manager hints and properties as well as vendor-specific one supported by the provider. These properties may or may not currently be in effect.

Returns:

property names Names of the properties accepted

getMetamodel

public javax.persistence.metamodel.Metamodel getMetamodel()

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

Specified by:

getMetamodel in interface javax.persistence.EntityManager

Returns:

Metamodel instance

Throws:

IllegalStateException - if the entity manager has been closed.

isTransactionActive

public boolean isTransactionActive()

Returns:

true if there is an active transaction associated to this EntityManager

getLockTypeForJPALockModeType

public static short getLockTypeForJPALockModeType(javax.persistence.LockModeType lock)

Convenience method to convert from the JPA LockModeType to the type expected by LockManager

Parameters:

lock - JPA LockModeType

Returns:

The lock type

getJPALockModeTypeForLockType

public static javax.persistence.LockModeType getJPALockModeTypeForLockType(short lockType)

Convenience method to convert from LockManager lock type to JPA LockModeType

Parameters:

lockType - Lock type

Returns:

JPA LockModeType