Interacting with EntityManager

WebSphere eXtreme Scale Programming Guide > Access data in WebSphere eXtreme Scale > EntityManager API introduction

Interacting with EntityManager

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, 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. You can use these EntityManager APIs if the client has access to the defined entity classes.

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 EntityManager. 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.

Persist an entity

Persist an entity means saving 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.
The preceding example does not include any required transactional boundaries, such as begin and commit. See the Entity manager tutorial for more information.

Find an entity

You can locate the entity in the ObjectGrid cache 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));
Remove 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.

Invalidate 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.

Update 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.

Queries and query queues

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 the Query API for more information about using queries.
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 queuesfor more information.

Entity listeners and callback methods
Applications can be notified when the state of an entity transitions from state to state. Two callback mechanisms exist for state change events: life cycle callback methods that are defined on an entity class and are invoked whenever the entity state changes, and entity listeners, which are more general because the entity listener can be registered on several entities.
Entity listener examples
You can write EntityListeners based on your requirements. Several example scripts follow.

Parent topic
EntityManager API introduction

+
Search Tips | Advanced Search