EntityManager API

The EntityManager API simplifies the interaction with the eXtreme Scale cache by providing an easy way to declare and interact with a complex graph of related objects.

Entity manager 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 the getEntityManager method, is available. This method returns a reference to an entity manager to use for this thread. The EntityManager interface can replace the Session and ObjectMap interfaces for all applications.

Obtaining an EntityManager instance from a session

The getEntityManager method is available on a Session object. The following code example illustrates how to create a local ObjectGrid instance and access the EntityManger. See the EntityManager interface in the API documentation 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. For code examples and further details, see Entity manager tutorial: Creating an entity class .

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 state of the object before you commit the transaction.
Note: The preceding example does not include any required transactional boundaries, such as begin and commit. See the Entity manager tutorial for more information.

Finding an entity

You can locate the entity in the ObjectGrid cache with the with the find method by providing a key after the entity is stored in the cache. 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 the begin and commit methods.

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. Then call the remove method on the EntityManager interface. For more information about the various states of an entity, such as new, managed, detached, and removed, see Entity instance life cycles.

Invalidating an entity

The invalidate method behaves much like the remove method, but does not invoke any Loader plug-ins. 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 you call the find method, you can call the invalidate method on the EntityManager interface. See Entity instance life cycles for more information about 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(); // update the date of the order
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. See Query API for more information about using queries.

Using query queues

An entity QueryQueue is a queue-like data structure associated with an entity query. It selects all the entities that match the WHERE condition on the query filter and puts the result entities in a queue. Clients can then iteratively retrieve entities from this queue. See Entity query queues for more information about how to use query queues with entities.