org.josef.jpa

Class EntityDataAccess

java.lang.Object

org.josef.jpa.EntityDataAccess

@Status(stage=DEVELOPMENT,
        unitTests=PARTIAL)
 @Review(by="Kees Schotanus",
        at="2009-09-28")
public final class EntityDataAccess
extends Object

Utility class that provides data access for JPA/EJB 3 entities.
This class contains all the methods from EntityManager that directly deal with one or more JPA Entities. Use this class in combination with EntityManagerHelper for example to handle transactions.
Note: All create, update and delete actions are logged (whether they are successful or not).

Version:

1.0 $Revision: 6101 $

Author:

Kees Schotanus

Method Summary

Modifier and Type	Method and Description
static <T> boolean	contains(T entity) Determines whether the supplied entity belongs to the current persistence context.
static <T> List<T>	executeNamedQuery(javax.persistence.EntityManager entityManager, String queryName, Map<String,Object> parameterNamesToValues, Class<T> type) Executes a named query using the supplied entityManager.
static <T> List<T>	executeNamedQuery(String queryName, Map<String,Object> queryParameters, Class<T> type) Executes a named query.
static <T> List<T>	findAll(Class<T> type) Find all entities of the supplied class.
static <T> List<T>	findAll(javax.persistence.EntityManager entityManager, Class<T> type) Find all entities of the supplied class, using the supplied entityManager.
static <T> List<T>	findByCriteria(Class<T> type, Searchable searchCriteria) Finds entities of type <T> by criteria.
static <T> List<T>	findByCriteria(javax.persistence.EntityManager entityManager, Class<T> type, Searchable searchCriteria) Finds entities of type <T> by criteria using the supplied entityManager.
static <T> T	findById(Class<T> type, Object primaryKey) Finds a persisted entity by its id (primary key).
static javax.persistence.EntityManager	getEntityManager() Convenience method to get the EntityManagerHelper.
static <T> T	getReference(Class<T> type, Object primaryKey) Gets a reference to a persisted entity by its id (primary key).
static void	lock(Object entity, javax.persistence.LockModeType lockMode) Sets the supplied lockMode on the supplied entity.
static <T> T	merge(T entity) Merges the supplied entity with the persisted state of the supplied entity.
static <T> T	persist(T entity) Persists the supplied entity that previously should not have been persisted.
static void	refresh(Object entity) Refreshes the state of the supplied entity from the database.
static <T> void	remove(Class<T> type, Object primaryKey) Removes a previously persisted entity.

Methods inherited from class java.lang.Object

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

Method Detail

getEntityManager

public static javax.persistence.EntityManager getEntityManager()

Convenience method to get the EntityManagerHelper.

Returns:

The EntityManager associated with the current thread.

persist

public static <T> T persist(T entity)

Persists the supplied entity that previously should not have been persisted.
After a successful persist the merge(Object) should be used.

Type Parameters:

T - The type of the entity to persist.

Parameters:

entity - The entity to persists.

Returns:

The persisted entity.

Throws:

NullPointerException - When the supplied entity is null.

javax.persistence.PersistenceException - When the persist operation failed.

See Also:

EntityManager.persist(Object)

merge

public static <T> T merge(T entity)

Merges the supplied entity with the persisted state of the supplied entity.

Type Parameters:

T - The type of the entity to merge.

Parameters:

entity - The entity to merge.

Returns:

A copy of the merged state of the supplied entity.

Throws:

NullPointerException - When the supplied entity is null.

javax.persistence.PersistenceException - when the merge operation failed.

See Also:

EntityManager.merge(Object)

remove

public static <T> void remove(Class<T> type,
                              Object primaryKey)

Removes a previously persisted entity.

Type Parameters:

T - The type of the entity to remove.

Parameters:

type - The class type of the entity to remove.

primaryKey - The primary key of the entity to remove.

Throws:

NullPointerException - When the supplied primaryKey is null.

javax.persistence.PersistenceException - when the remove operation failed.

See Also:

EntityManager.remove(Object)

contains

public static <T> boolean contains(T entity)

Determines whether the supplied entity belongs to the current persistence context.

Type Parameters:

T - The type of entity to check.

Parameters:

entity - The entity to check.

Returns:

True when the supplied entity belongs to the current persistence context, otherwise false is returned.

Throws:

NullPointerException - When the supplied entity is null.

See Also:

EntityManager.contains(Object)

findById

public static <T> T findById(Class<T> type,
                             Object primaryKey)

Finds a persisted entity by its id (primary key).

Type Parameters:

T - The type of the entity to find.

Parameters:

type - The class type of the entity to find.

primaryKey - The primary key of the entity to find.

Returns:

The entity with the supplied primaryKey or null when no entity with the supplied primaryKey exists.

Throws:

NullPointerException - When either the supplied type or the supplied primaryKey is null.

See Also:

EntityManager.find(Class, Object)

findAll

public static <T> List<T> findAll(Class<T> type)

Find all entities of the supplied class.

Type Parameters:

T - The type of the entities to find.

Parameters:

type - The class type of the entities to find.

Returns:

All elements of the supplied type.

Throws:

NullPointerException - When the supplied type is null.

findAll

public static <T> List<T> findAll(javax.persistence.EntityManager entityManager,
                                  Class<T> type)

Find all entities of the supplied class, using the supplied entityManager.

Type Parameters:

T - The type of the entities to find.

Parameters:

entityManager - The entity manager to use.

type - The class type of the entities to find.

Returns:

All elements of the supplied class.

Throws:

NullPointerException - When either the supplied entityManager or class is null.

findByCriteria

public static <T> List<T> findByCriteria(Class<T> type,
                                         Searchable searchCriteria)

Finds entities of type <T> by criteria.

Type Parameters:

T - The type of the entities to find.

Parameters:

type - The class type of the entities to find.

searchCriteria - The search criteria that are used to find the entities.

Returns:

All entities that adhere to the supplied searchCriteria.
The returned List is possibly empty but never null.

Throws:

NullPointerException - When either the supplied theClass or searchCriteria is null.

findByCriteria

public static <T> List<T> findByCriteria(javax.persistence.EntityManager entityManager,
                                         Class<T> type,
                                         Searchable searchCriteria)

Finds entities of type <T> by criteria using the supplied entityManager.

Type Parameters:

T - The type of the entities to find.

Parameters:

entityManager - The entity manager to use.

type - The class type of the entities to find.

searchCriteria - The search criteria that are used to find the entities.

Returns:

All entities that adhere to the supplied searchCriteria.
The returned List is possibly empty but never null.

Throws:

NullPointerException - When either the supplied entityManager or theClass or searchCriteria is null.

executeNamedQuery

public static <T> List<T> executeNamedQuery(String queryName,
                                            Map<String,Object> queryParameters,
                                            Class<T> type)

Executes a named query.

Type Parameters:

T - The type of the Persistable to return.

Parameters:

queryName - Name of the query.

queryParameters - The query parameters.
The named properties will be set on the query. Supply null when the named query does not accept properties.

type - The class type of the entities to find.

Returns:

The result of executing the supplied namedQuery.

Throws:

NullPointerException - When either the supplied queryName or theClass is null.

IllegalArgumentException - When the supplied queryName is empty.

executeNamedQuery

public static <T> List<T> executeNamedQuery(javax.persistence.EntityManager entityManager,
                                            String queryName,
                                            Map<String,Object> parameterNamesToValues,
                                            Class<T> type)

Executes a named query using the supplied entityManager.

Type Parameters:

T - The type of the Persistable to return.

Parameters:

entityManager - The entity manager to use.

queryName - Name of the query.

parameterNamesToValues - The mapping of property names to property values.
The named properties will be set on the query. Supply null when the named query does not accept properties.

type - The class type of the entities to find.

Returns:

The result of executing the supplied namedQuery.

Throws:

NullPointerException - When either the supplied queryName or theClass is null.

IllegalArgumentException - When the supplied queryName is empty.

getReference

public static <T> T getReference(Class<T> type,
                                 Object primaryKey)

Gets a reference to a persisted entity by its id (primary key).
This Entity may be lazily fetched and may throw an EntityNotFoundException upon first access.

Type Parameters:

T - The type of the entity to find.

Parameters:

type - The class type of the reference to get.

primaryKey - The primary key the entity to find.

Returns:

The reference to an entity with the supplied primaryKey.

Throws:

javax.persistence.EntityNotFoundException - When the entity is not found.

NullPointerException - When either the supplied type or the supplied primaryKey is null.

See Also:

EntityManager.getReference(Class, Object)

lock

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

Sets the supplied lockMode on the supplied entity.

Parameters:

entity - The entity to lock.

lockMode - The lock mode.

Throws:

IllegalArgumentException - When the supplied instance is a detached entity.

IllegalStateException - When the EntityManager is closed.

NullPointerException - When either the supplied entity or lockMode is null.

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

javax.persistence.TransactionRequiredException - When no transaction exists.

refresh

public static void refresh(Object entity)

Refreshes the state of the supplied entity from the database.

Parameters:

entity - The entity to refresh.

Throws:

IllegalArgumentException - When the supplied entity is not managed.

IllegalStateException - When the EntityManager is closed.

NullPointerException - When the supplied entity is null.

javax.persistence.TransactionRequiredException - When no transaction exists.

javax.persistence.EntityNotFoundException - When the supplied entity does no longer exists in the database.

See Also:

EntityManager.refresh(Object)