Entity instance life cycles

Each entity instance goes through a life cycle of different states.

Life cycle of an entity instance

An entity instance has the following states:

When entities change from state to state, you can invoke life-cycle, call-back methods.

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

The EntityManager interface supports the find operation with and without transaction demarcation:
Figure 1. Managed entity example
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.
Figure 2. Detached entity example
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.
//A customer with Id "10" exists in the eXtreme Scale 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 eXtreme Scale 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 the eXtreme Scale, but since the instance 
// is in detached state, the commit operation throws an
// EntityExistsException for the Customer Object.
em.getTransaction().commit(); 
When you are persisting an entity, note the following items:

Removing or invalidating an entity

Removing or invalidating an entity has similar semantics as the persist method. Removing an entity removes the entity from the eXtreme Scale and the operating system. Invalidating an entity only removes the entity from the eXtreme Scale, and does not invoke the Loader plug-ins.
//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();