developerWorks: Wikis - WebSphere eXtreme Scale V6.1 User Guide - Entity listeners and life cycle callback methods

If you log in with your developerWorks ID, you can leave comments and feedback for the development team.

Applications can be notified when the state of an entity transitions from state to state. See the parent topic: Life cycle of an entity instance for details on the various entity states. ObjectGrid provides two callback mechanisms for state change events:

Life cycle callback methods are defined on an entity class and are invoked whenever the entity's state changes.
Entity listeners are more general in that they can be registered on several entities.

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. Such methods are useful for validating entity fields and updating transient state that isn't normally persisted with the entity. Entity life cycle callback methods can also be defined on non-entity classes. 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 non-entity class 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 may be used as an alternative to specify the invocation order of entity listeners or to override the order specified in metadata annotations.

Callback method requirements

Any subset or combination of annotations may be specified on an entity class or a listener class.

A single class may not have more than one life cycle callback method for the same life cycle event. However, The same method may 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.

ObjectGrid 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 and/or directly on an entity class.

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 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. It may be declared as java.lang.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. See the Entity metadata descriptor file topic for details.

Life cycle callback method semantics

This section describes when each of the the 7 different callback methods are invoked.

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 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.
ObjectGrid does not support entity inheritance, so the entity life cycle methods can only be defined in the entity class.

Exceptions

Life cycle callback methods may throw runtime exceptions. If a life cycle callback method throws a runtime exception within a transaction, that transaction will be rolled back. No further life cycle callback methods will be invoked after a runtime exception is thrown.

EntityListeners example using annotations

The following example shows the life cycle callback method invocations and order of the invocations.

Assume we have an entity class Employee and two entity listeners: EmployeeListener and EmployeeListener2.

@Entity
@EntityListeners(EmployeeListener.class, EmployeeListener2.class) 
public class Employee {
    @PrePersist
    public void checkEmployeeID() {
        .... 
    }
}

public class EmployeeListener {
    @PrePersist
    public void onEmployeePrePersist(Employee e) {
        .... 
    }
}

public class PersonListener {
    @PrePersist
    public void onPersonPrePersist(Object person) {
        .... 
    }
}

public class EmployeeListener2 {
    @PrePersist
    public void onEmployeePrePersist2(Object employee) {
        .... 
    }
}

If a PrePersist event occurs on an instance of Employee, the following methods are called in order:
onEmployeePrePersist
onPersonPrePersist
onEmployeePrePersist2
checkEmployeeID

Entity listeners example using XML

The following example shows how to set an entity listener on an entity using the entity descriptor XML file:

<entity
    class-name="com.ibm.websphere.objectgrid.sample.Employee"
    name="Employee" access="FIELD">
    <attributes>
        <id name="id" />
        <basic name="value" />
    </attributes>
    <entity-listeners>
        <entity-listener
            class-name="com.ibm.websphere.objectgrid.sample.EmployeeListener">
            <pre-persist method-name="onListenerPrePersist" />
            <post-persist method-name="onListenerPostPersist" />
        </entity-listener>
    </entity-listeners>
    <pre-persist method-name="checkEmployeeID" />
</entity>

The entity Employee is configured with an entity listener class "com.ibm.websphere.objectgrid.sample.EmployeeListener", which has two life cycle callback methods defined. The first method is onListenerPrePersist for the PrePersist event, and the second method is onListenerPostPersist for the PostPersist event. Also, the method checkEmployeeID in the Employee class is configured to listen for the PrePersist event.