See the WebSphere eXtreme Scale Wiki for links to eXtreme Scale Version 7.0 documentation.
If you log in
with your developerWorks ID, you can leave comments and feedback for the development team.
The EntityManager API simplifies the interaction with the ObjectGrid cache by providing an easy way to declare and interact with a complex graph of related objects.
Most cache products used Map-based APIs to store data as key-value pairs. The ObjectGrid ObjectMap API and WebSphere Dynacache, among others, use this approach. Though successful, the following are some of its limitations:
- The cache must use reflection to extract data from the objects in the cache, which has performance implications.
- Two applications cannot share a cache if the two applications use different objects for the same data.
- Data evolution is not possible. You cannot easily add an attribute to a cached Java object.
- Working with graphs of objects is cumbersome. The application must store artificial references between objects and manually join them together.
The EntityManager API uses the existing Map-based infrastructure, but it converts entity objects to and from tuples before storing or reading them from the Map. An entity object is transformed into a key tuple and a value tuple, which are then stored as key-value pairs. A tuple is an array of primitive attributes.
This set of APIs significantly eases the use of ObjectGrid by following the Plain Old Java Object (POJO) style of programming that is adopted by most frameworks.
The following topics are covered in this section:
EntityManager Overview
Applications typically first obtain an ObjectGrid reference, and then a Session from that reference for each thread. Sessions cannot be shared between threads. An extra method on Session, known as getEntityManager, is now available. This method returns a reference to an EntityManager to use for this thread. EntityManager can replace the Session and ObjectMap interfaces for all applications.
Obtaining EntityManager from ObjectGrid Session
The method getEntityManager() is available on a Session object. The following code example illustrates how to create a local ObjectGrid and access EntityManger. See the EntityManager interface for details about all the supported methods.
ObjectGrid og = ObjectGridManagerFactory.getObjectGridManager().createObjectGrid("intro-grid");
Session s = og.getSession();
EntityManager em = s.getEntityManager();
A one-to-one relationship exists between the Session object and EntityManager object. You can use the EntityManager object more than once. Basic EntityManager tutorial step 1 contains code examples that provide further details.
Persisting an Entity
Persisting an entity means to save the state of a new entity in an ObjectGrid cache. After the persist method is called, the entity is in the managed state. Persist is a transactional operation, and the new entity is stored in the ObjectGrid cache after the transaction commits.
Every entity has a corresponding BackingMap, in which the tuples are stored. The BackingMap has the same name as the entity, and is created when the class is registered. The following code example demonstrates how to create an Order object by using the persist operation.
Order order = new Order(123);
em.persist(order);
order.setX();
...
The Order object is created with the key 123, and the object is passed to the persist method. You can continue to modify the object's state before you commit the transaction.
Note: The preceding example does not include any required transactional boundaries, such as begin and commit. Refer to Basic EntityManager tutorial step 1 for further details.
Finding an Entity
You can easily locate the entity in the ObjectGrid cache with the key after it is stored there by issuing the find method. This method does not require any transactional boundary, which is useful for read-only semantics. The following example illustrates that only one line of code is needed to locate the entity.
Order foundOrder = (Order)em.find(Order.class, new Integer(123));
Removing an Entity
The remove method, like the persist method, is a transactional operation. The following example shows the transactional boundary by calling begin and commit.
em.getTransaction().begin();
Order foundOrder = (Order)em.find(Order.class, new Integer(123));
em.remove(foundOrder );
em.getTransaction().commit();
The entity must first be managed before it can be removed, which you can accomplish by calling the find method within the transactional boundary. After which, call the remove method on the EntityManager. Life cycle of an entity instance explains the various states of an entity, such as new, managed, detached, and removed.
Invalidating an Entity 
The invalidate method behaves much like the remove method, but does not invoke any Loader plugins. Use this method to remove entities from the ObjectGrid but to preserve them in the backend data store.
em.getTransaction().begin();
Order foundOrder = (Order)em.find(Order.class, new Integer(123));
em.invalidate(foundOrder );
em.getTransaction().commit();
The entity must first be managed before it can be invalidated, which you can accomplish by calling the find method within the transactional boundary. After which, call the invalidate method on the EntityManager. Life cycle of an entity instance explains the various states of an entity.
Updating an Entity
The update method is also a transactional operation. The entity must be managed before any updates can be applied.
em.getTransaction().begin();
Order foundOrder = (Order)em.find(Order.class, new Integer(123));
foundOrder.date = new Date(); em.getTransaction().commit();
In the preceding example, the persist method is not called after the entity is updated. The entity is updated in the ObjectGrid cache when the transaction is committed.
Using Queries
With the flexible query engine, you can retrieve entities by using EntityManager API. Create SELECT type queries over an entity or Object-based schema by using the ObjectGrid query language. Query interface explains in detail how you can run the queries by using the EntityManager API.
Using query queues 
An entity QueryQueue is a queue-like data structure associated with an entity query. It selects all the entities which match the query filter's WHERE condition and put the result entities in a queue. Clients can then retrieve entities from this queue in an iterative manner. See the Entity query queues topic for details on how to use query queues with entities.
© Copyright IBM Corporation 2007,2009. All Rights Reserved.
