Each entity instance goes through a life cycle of different
states.
Life cycle of an entity instance
An
entity instance has the following states:
- New: A newly created entity instance that does not exist
in the eXtreme Scale cache.
- Managed: The entity instance exists in the eXtreme Scale cache and is retrieved
or persisted using the entity manager. An entity must be associated
with an active transaction to be in the managed state.
- Detached: The entity instance exists in the eXtreme Scale cache, but is no
longer associated with an active transaction.
- Removed: The entity instance is removed, or is scheduled
to be removed, from the eXtreme Scale cache
when the transaction is flushed or committed.
- Invalidated: The entity instance is invalidated, or is
scheduled to be invalidated, from the eXtreme Scale cache when the transaction
is flushed or committed.
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 exampleem.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 exampleOrder 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:
- 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 entities already in the managed
state, and any value changes are updated. If the transaction was rolled
back initially, the call to the persist method is equivalent to an
update operation.
- If the CascadeType value 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 eXtreme Scale cache. The persistence
is similar to an insert operation, which results in an exception because
of 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 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.
- To remove an entity, the entity must be in managed state.
- If the CascadeType value is REMOVE or ALL, the remove operation
is cascaded to the associations.
- If the CascadeType value is INVALIDATE or ALL, the invalidate
operation is cascaded to the associations.
- An IllegalArgumentException exception can result 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 the CascadeType value.
//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();