com.ibm.websphere.objectgrid.em
Interface EntityManager

public interface EntityManager

An EntityManager allows transactional introspection and manipulation of entities.

Each EntityManager is associated with an ObjectGrid Session. Use the Session.getEntityManager() method to retrieve the Session's EntityManager instance. Simultaneous interaction with the EntityManager and the owning ObjectGrid Session is allowed.

All interactions with the EntityManager must be from a single thread. Multi-thread access to the EntityManager is not supported.

The EntityManager manages each entity within it's context scope. Entity operations will not be synchronized to the underlying ObjectGrid cache until the transaction is committed or the EntityManager context is flushed to the cache.

Each entity is backed by an ObjectGrid map with the same name as the entity and utilizes the inherent map configuration for locking, evicting, indexing and synchronizing with a loader. See BackingMap for details on how entity a map can be configured and optimized for each entity.

The EntityManager converts each entity instance to key and value Tuple instances using the entity's persistent fields or properties and stores the Tuples in the entity's associated ObjectMap. The metadata that describes the Tuple can be accessed using the ObjectMap.getEntityMetadata() or BackingMap.getEntityMetadata() methods.

Accessing entities and Tuples simultaneously in a single transaction is not supported and may cause unexpected results.

Since:

WAS XD 6.1

See Also:

Tuple, EntityMetadata

Method Summary

void	clear() Clear the EntityManager's context.
Query	createQuery(java.lang.String qlString) Create a Query instance for executing an ObjectGrid query language statement.
java.lang.Object	find(java.lang.Class entityClass, java.lang.Object primaryKey) Find an entity by primary key in the ObjectGrid cache.
java.lang.Object	findForUpdate(java.lang.Class entityClass, java.lang.Object primaryKey) Find an entity by primary key with the intent to be updated.
void	flush() Synchronize the EntityManager to the ObjectGrid cache.
FlushModeType	getFlushMode() Get the flush mode that applies to all objects contained in the EntityManager's context.
EntityTransaction	getTransaction() Return the resource-level transaction object.
void	persist(java.lang.Object entity) Make an entity instance managed and persistent in the ObjectGrid cache.
void	remove(java.lang.Object entity) Remove the entity instance from the ObjectGrid cache.
void	setFlushMode(FlushModeType flushMode) Set the flush mode that applies to all objects contained in the EntityManager's context.

Method Detail

persist

void persist(java.lang.Object entity)

Make an entity instance managed and persistent in the ObjectGrid cache.

Parameters:

entity - the entity object instance to make persistent.

Throws:

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

java.lang.IllegalArgumentException - if not a valid entity

TransactionRequiredException - if invoked without an active transaction.

See Also:

ObjectMap.insert(Object, Object)

remove

void remove(java.lang.Object entity)

Remove the entity instance from the ObjectGrid cache.

Parameters:

entity - the managed entity instance to remove from the ObjectGrid cache.

Throws:

java.lang.IllegalArgumentException - if instance is not an entity or is a detached entity

TransactionRequiredException - if invoked without an active transaction.

See Also:

ObjectMap.remove(Object)

find

java.lang.Object find(java.lang.Class entityClass,
                      java.lang.Object primaryKey)

Find an entity by primary key in the ObjectGrid cache.

Parameters:

entityClass - the class representing the entity to find.

primaryKey - an object instance representing the key of the entity to find. The key may be a single Object (for single value keys), an IdClass or Entity instance (for composite keys) or a Tuple instance.

Returns:

the entity instance or null if the entity does not exist

Throws:

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

See Also:

Tuple, ObjectMap.get(Object)

findForUpdate

java.lang.Object findForUpdate(java.lang.Class entityClass,
                               java.lang.Object primaryKey)

Find an entity by primary key with the intent to be updated.

If the underlying map is configured with pessimistic locking strategy, an upgradeable lock mode is obtained for this entity instance's map entry. Any associated entities that are loaded are not locked for update. If the associates are need to be locked in the same manner, then findForUpdate should be called for each associated entity.

Parameters:

entityClass - the class representing the entity to find.

primaryKey - an object instance representing the key of the entity to find.

Returns:

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

Throws:

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

See Also:

ObjectMap.getForUpdate(Object)

flush

void flush()

Synchronize the EntityManager to the ObjectGrid cache.

All managed entities in the current transaction are synchronized with the ObjectGrid cache and the associated ObjectGrid session is flushed.

Throws:

TransactionRequiredException - if there is no transaction

PersistenceException - if the flush fails

See Also:

Session.flush()

setFlushMode

void setFlushMode(FlushModeType flushMode)

Set the flush mode that applies to all objects contained in the EntityManager's context.

Parameters:

flushMode - the FlushModeType.

getFlushMode

FlushModeType getFlushMode()

Get the flush mode that applies to all objects contained in the EntityManager's context.

Returns:

flushMode

getTransaction

EntityTransaction getTransaction()

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

Returns:

the EntityTransaction instance

createQuery

Query createQuery(java.lang.String qlString)

Create a Query instance for executing an ObjectGrid query language statement.

When security is enabled, this method requires an com.ibm.websphere.objectgrid.security.ObjectGridPermission with action "query".

Parameters:

qlString - an ObjectGrid query string

Returns:

the new query instance

Throws:

java.lang.IllegalArgumentException - if query string is not valid

clear

void clear()

Clear the EntityManager's context.

Causes all managed entities to become detached. Any changes made to entities that have not been flushed to the cache will not be persisted.