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.
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.
Entity life cycle callback methods
Entity life
cycle callback methods can be defined on the entity class and are
invoked when the entity state changes. These methods are useful for
validating entity fields and updating transient state that is not
usually persisted with the entity. Entity life cycle callback methods
can also be defined on classes that are not using entities. Such classes
are entity listener classes, which can be associated with multiple
entity types. life cycle callback methods can be defined using both
metadata annotations and a entity metadata XML descriptor file:
- Annotations: life cycle callback methods can be denoted
using the PrePersist, PostPersist, PreRemove, PostRemove, PreUpdate,
PostUpdate, and PostLoad annotations in an entity class.
- Entity XML descriptor : life cycle callback methods can
be described using XML when annotations are not available.
Entity listeners
An entity listener class is
a class that does not use entities that defines one or more entity
life cycle callback methods. Entity listeners are useful for general
purpose auditing or logging applications. Entity listeners can be
defined using both metadata annotations and a entity metadata XML
descriptor file:
- Annotation: The EntityListeners annotation can be used
to denote one or more entity listener classes on an entity class.
If multiple entity listeners are defined, the order in which they
are invoked is determined by the order in which they are specified
in the EntityListeners annotation.
- Entity XML descriptor: The XML descriptor can be used as
an alternative to specify the invocation order of entity listeners
or to override the order that is specified in metadata annotations.
Callback method requirements
Any subset or
combination of annotations can be specified on an entity class or
a listener class. A single class cannot have more than one life cycle
callback method for the same life cycle event. However, the same method
can be used for multiple callback events. The entity listener class
must have a public no-arg constructor. Entity listeners are stateless.
The life cycle of an entity listener is unspecified. eXtreme Scale does not support
entity inheritance, so callback methods can only be defined in the
entity class, but not in the superclass.
Callback method signature
Entity life cycle
callback methods can be defined on an entity listener class, directly
on an entity class, or both. Entity life cycle callback methods can
be defined using both metadata annotations and the entity XML descriptor.
The annotations used for callback methods on the entity class and
on the entity listener class are the same. The signatures of the callback
methods are different when defined on an entity class versus an entity
listener class. Callback methods defined on an entity class or mapped
superclass have the following signature:
void <METHOD>()
Callback
methods that are defined on an entity listener class have the following
signature:
void <METHOD>(Object)
The Object
argument is the entity instance for which the callback method is invoked.
The Object argument can be declared as a java.lang.Object object or
the actual entity type.
Callback methods can have public, private,
protected, or package level access, but must not be static or final.
The following annotations are defined to designate life cycle
event callback methods of the corresponding types:
- com.ibm.websphere.projector.annotations.PrePersist
- com.ibm.websphere.projector.annotations.PostPersist
- com.ibm.websphere.projector.annotations.PreRemove
- com.ibm.websphere.projector.annotations.PostRemove
- com.ibm.websphere.projector.annotations.PreUpdate
- com.ibm.websphere.projector.annotations.PostUpdate
- com.ibm.websphere.projector.annotations.PostLoad
See the API Documentation for more details. Each annotation
has an equivalent XML attribute defined in the entity metadata XML
descriptor file.
Life cycle callback method semantics
Each of
the different life cycle callback methods has a different purpose
and is called in different phases of the entity life cycle:
- PrePersist
- Invoked for an entity before the entity has been persisted to
the store, which includes entities that have been persisted due to
a cascading operation. This method is invoked on the thread of the
EntityManager.persist operation.
- PostPersist
- Invoked for an entity after the entity has been persisted to the
store, which includes entities that have been persisted due to a cascading
operation. This method is invoked on the thread of the EntityManager.persist
operation. It is called after the EntityManager.flush or EntityManager.commit
is called.
- PreRemove
- Invoked for an entity before the entity has been removed, which
includes entities that have been removed due to a cascading operation.
This method is invoked on the thread of the EntityManager.remove operation.
- PostRemove
- Invoked for an entity after the entity has been removed, which
includes entities that have been removed due to a cascading operation.
This method is invoked on the thread of the EntityManager.remove operation.
It is called after the EntityManager.flush or EntityManager.commit
is called.
- PreUpdate
- Invoked for an entity before the entity has been updated to the
store. This method is invoked on the thread of the transaction flush
or commit operation.
- PostUpdate
- Invoked for an entity after the entity has been updated to the
store. This method is invoked on the thread of the transaction flush
or commit operation.
- PostLoad
- Invoked for an entity after the entity has been loaded from the
store which includes any entities that are loaded through an association.
This method is invoked on the thread of the loading operation, such
as EntityManager.find or a query.
Duplicate life cycle callback methods
If multiple
callback methods are defined for an entity life cycle event, the ordering
of the invocation of these methods is as follows:
- life cycle callback methods defined in the entity listeners: The
life cycle callback methods that are defined on the entity listener
classes for an entity class are invoked in the same order as the specification
of the entity listener classes in the EntityListeners annotation or
the XML descriptor.
- Listener super class: Callback methods defined in the super
class of the entity listener are invoked before the children.
- Entity life cycle methods: WebSphere® eXtreme Scale does not support entity
inheritance, so the entity life cycle methods can only be defined
in the entity class.
Exceptions
Life cycle callback methods might
result in run time exceptions. If a life cycle callback method results
in a run time exception within a transaction, the transaction is rolled
back. No further life cycle callback methods are invoked after a runtime
exception results.