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.

An entity instance has the following states:

• New: A newly created entity instance that does not exist in the ObjectGrid cache.
• Managed: The entity instance exists in the ObjectGrid cache and is retrieved or persisted using EntityManager. An entity must be associated with an active transaction to be in the managed state.
• Detached: The entity instance exists in the ObjectGrid cache, but is no longer associated with an active transaction.
• Removed: The entity instance is removed, or is scheduled to be removed, from the ObjectGrid cache when the transaction is flushed or committed.
• Invalidated: The entity instance is invalidated, or is scheduled to be invalidated, from the ObjectGrid cache when the transaction is flushed or committed.

When entities change from state to state, you can invoke life-cycle, call-back methods. To configure such methods, see the Entity listeners and callback methods topic.

The following sections further describe the meanings of New, Managed, Detached, Removed and Invalidated states as the states apply to an entity.

Finding an entity

EntityManager supports the find operation with and without transaction demarcation:

em.getTransaction().begin();
Order o=(Order)em.find(Order.class,"ASD100");
// Entity instance "o" is now managed
em.getTransaction().commit()
// Entity instance "o" is now detached.

Order o=(Order)em.find(Order,class,"ASD100");
// Detached Entity instance "o". Not within the transaction boundary

Persisting an entity

With the EntityManager Interface, you can persist entities by using the persist method. You can persist only a new entity instance, and you must describe it with a sample code. The Basic EntityManager tutorial step 2 example has the following entities: Customer, Item, OrderLine and Order.

//A customer with Id "10" exists in ObjectGrid cache, and the customer is placing a new Order.
Order newOrder = createNewOrder(); // Assuming this method sets relationships between Item, OrderLine and Order
em.getTransaction().begin();
Customer customer10=(Customer)em.find(Customer.class, "10"); // entity instance customer10 is now managed
newOrder.customer=customer10;
//persist newOrder. It is in "new" state
em.persist(newOrder);
// newOrder is now in "Managed" state
// Transaction commit operation persists Order, OrderLines and Item.
// Since the Customer already exists and is in Managed state, the persist operation ignores the Customer entity in this case.
// If customer object values are modified, the object is updated in the ObjectGrid Cache.
em.getTransaction().commit();
//At this point, all instances are detached.

//The customer places another order, and this time the code uses the detached entity instance. This is an Error
// and an Exception is thrown.


Order newOrder2 = createNewOrder(); // Assuming this method sets relationships between Item, OrderLine and Order
em.getTransaction().begin();
newOrder.customer=customer10; // using a detached customer10 instance.
em.persist(newOrder2);
// The Commit call persists the Order in ObjectGrid. The customer10 instance already exists
// in ObjectGrid, but since the instance is in detached state, the commit operation throws an
// EntityExistsException for the Customer Object.
em.getTransaction().commit(); 

Note the following items when persisting an entity:

• You can persist only new entities. The entities are in the managed state after the em.persist(object) is called. The entity stays in the managed state, until the transaction is either committed or rolled back. Essentially, it is an insert operation.
• The persist operation is ignored for managed entities, and any value changes are updated. If dirty, it is an update operation.
• If CascadeType is PERSIST or ALL, the operation is cascaded to the associations.
• If a newly created Entity or a detached Entity is persisted, an EntityExistsException exception results if the key exists in the ObjectGrid Cache. Essentially, it is an insert operation, which results in an exception due to a duplicate key.

Removing or invalidating an Entity

Removing or invalidating an entity has similar semantics as the persist method. Removing an entity removes the entity from ObjectGrid and the back-end. Invalidating an entity only removes the entity from ObjectGrid, and does not invoke the Loader plug-ins. 

Entity invalidation is new for ObjectGrid in WebSphere eXtreme Scale Version 6.1.0.3.

• To remove an entity, the entity must be in managed state.
• If CascadeType is REMOVE or ALL, the remove operation is cascaded to the associations.
• If CascadeType is INVALIDATE or ALL, the invalidate operation is cascaded to the associations.
• An IllegalArgumentException exception can be thrown if removing or invalidating a detached entity.
• If an entity is new, the remove or invalidate operation ignores the entity. Cascading is honored, based on CascadeType.

//A correct way of removing.
//The an Order with OrderNumber ASD100 exists and needs to be removed:
em.getTransaction().begin();
Order o=(Order)em.find(Order.class,"ASD100"); // Managed
em.remove(o);
em.getTransaction().commit();

//An incorrect way of removing:
Order o=(Order)em.find(Order.class,"ASD100"); // Detached. Not within transaction demarcation
em.getTransaction().begin();
em.remove(o); // Can throw an IllegalArgumentException exception
em.getTransaction().commit();

Wiki Disclaimer and License

© Copyright IBM Corporation 2007,2009. All Rights Reserved.