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.

Tuples can be manually extracted from entities using the Projector which is obtained using the ProjectorFactory.getProjector(EntityManager) factory method.

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(String qlString) Create a Query instance for executing an ObjectGrid query language statement.
QueryQueue	createQueryQueue(String qlString, Class entityClass) Create a QueryQueue for an entity map.
Object	find(Class entityClass, Object primaryKey) Find an entity by primary key in the ObjectGrid cache.
Object	findForUpdate(Class entityClass, Object primaryKey) Find an entity by primary key with the intent to be updated.
void	flush() Synchronize the EntityManager to the ObjectGrid cache.
FetchPlan	getFetchPlan() Get the current mutable FetchPlan.
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	invalidate(Object entity) Invalidate the entity instance from the ObjectGrid cache, including the transactional, client and server caches.
Object	merge(Object entity) Merge the entity instance with the ObjectGrid.
void	persist(Object entity) Make an entity instance managed and persistent in the ObjectGrid cache.
void	remove(Object entity) Remove the entity instance from the ObjectGrid.
void	setFlushMode(FlushModeType flushMode) Set the flush mode that applies to all objects contained in the EntityManager's context.

Method Detail

persist

void persist(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.)

IllegalArgumentException - if not a valid entity

TransactionRequiredException - if invoked without an active transaction.

See Also:

ObjectMap.insert(Object, Object)

remove

void remove(Object entity)

Remove the entity instance from the ObjectGrid.

Parameters:

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

Throws:

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

TransactionRequiredException - if invoked without an active transaction.

See Also:

ObjectMap.remove(Object)

invalidate

void invalidate(Object entity)

Invalidate the entity instance from the ObjectGrid cache, including the transactional, client and server caches.

This method is similar to remove, but does not flow the changes to the entity's Loader.

Parameters:

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

Throws:

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

TransactionRequiredException - if invoked without an active transaction.

Since:

WAS XD 6.1.0.3

See Also:

ObjectMap.invalidate(Object, boolean)

find

Object find(Class entityClass,
            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:

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

Object findForUpdate(Class entityClass,
                     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:

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.

If not set, the default is FlushModeType.AUTO.

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.

Each EntityManager is associated with one EntityTransaction. Repeated calls to this method for the same EntityManager instance will result in the same EntityTransaction instance.

Returns:

the EntityTransaction instance

createQuery

Query createQuery(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".

Required Permission: ObjectGridPermission.QUERY

Parameters:

qlString - an ObjectGrid query string

Returns:

the new query instance

Throws:

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.

createQueryQueue

QueryQueue createQueryQueue(String qlString,
                            Class entityClass)

Create a QueryQueue for an entity map.

An entity QueryQueue will select all the entities which match the query filter's WHERE condition. Users can call QueryQueue.getNextEntity(long) or QueryQueue.getNextEntities(int, long) to get one or more entities at one time.

A QueryQueue is useful for retrieving select entities in an iterative manner.

The query string's SELECT clause must specify one and only one entity identification variable and no other functions or attributes.

For example:

 "SELECT t FROM Tasks t WHERE t.type=?1 AND t.status='PENDING' ORDER BY t.createTime"
 

An entity class can be optionally specified to indicate which class the result(s) will be projected into. The specified entity class must have the same entity name as specified in the query string. If a null value is used as the entity class, then the result will not be projected; the key tuple(s) will be returned by theQueryQueue.getNextEntity(long) or QueryQueue.getNextEntities(int, long) methods.

Parameters:

qlString - the query SQL string

entityClass - the entity class the result will be projected to; null if the results are not projected.

Returns:

a QueryQueue instance

Since:

WAS XD 6.1 FIX3

See Also:

QueryQueue

merge

Object merge(Object entity)

Merge the entity instance with the ObjectGrid. The entity to merge can be a new, detached or managed entity. Once merged, the input entity will remain in it's original state is not managed. The entity returned by this method is the managed result of the merge operation.

Parameters:

entity - the managed, new or detached entity instance to merge with the ObjectGrid cache.

Returns:

a managed entity representing the result of the merge.

Throws:

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

TransactionRequiredException - if invoked without an active transaction.

OptimisticLockException - if there is a mismatch between the version of the entity and a managed entity. This exception may not be thrown until commit or flush time.

Since:

WAS XD 6.1.0.3

getFetchPlan

FetchPlan getFetchPlan()

Get the current mutable FetchPlan.

A FetchPlan is used to customize how the eager relations are fetched with the fetch operation. A fetch operation could be any of the following: find(Class, Object), findForUpdate(Class, Object), Query operations, or QueryQueue operations.

A FetchPlan object is normally used on the client side to access for a distributed ObjectGrid. However, when used with a local ObjectGrid, the FetchPlan object can be used to customize the relations to be projected when the fetch operation is executed.

The FetchPlan object is mutable, and once changed, the changed value will be applied to the fetch operations executed afterwards.

Returns:

the current FetchPlan object

Since:

WAS XD 6.1.0.5