1. 1 Entity Callbacks and Listeners When you execute EntityManager methods like persist( ), merge( ), remove( ), and find( ), or when you execute EJB QL queries, a predefined set of life cycle events are triggered. For instance, the persist( ) method triggers database inserts. Merging triggers updates to the database. The remove( ) method triggers database deletes. Querying entities triggers a load from the database.

2. 2 Entity Callbacks and Listeners Sometimes it is very useful to have your entity bean class be notified as these events happen. For instance, maybe you want to create an audit log of every interaction done on each row in your database. The Java Persistence specification allows you to set up callback methods on your entity classes so that your entity instances are notified when these events occur.

3. 3 Callback Events A certain annotation represents each phase of an entity's life cycle: @javax.persistence.PrePersist @javax.persistence.PostPersist @javax.persistence.PostLoad @javax.persistence.PreUpdate @javax.persistence.PostUpdate @javax.persistence.PreRemove @javax.persistence.PostRemove

4. 4 Callback Events The @PrePersist and @PostPersist events have to do with the insertion of an entity instance into the database. The @PrePersist event occurs immediately when the EntityManager.persist( ) call is invoked or whenever an entity instance is scheduled to be inserted into the database (as with a cascaded merge). The @PostPersist event is not triggered until the actual database insert.

5. 5 Callbacks on Entity Classes You can have an entity bean instance register for a callback on any of these life cycle events by annotating a public, private, protected, or package-protected method on the bean class. This method must return void, throw no checked exceptions, and have no arguments. @Entity public class Cabin {... @PostPersist void afterInsert( ) {... } @PostLoad void afterLoading( ) {... }

6. 6 Callbacks on Entity Classes If you are annotation-averse, you can hook into these events by using the,,,,,, and subelements of in the ORM mapping deployment descriptor: These subelements have one attribute called name that takes the name of the method you want to invoke when the callback event happens.

7. 7 Entity Listeners Entity listeners are classes that can generically intercept entity callback events. They are not entity classes themselves, but they can be attached to an entity class through a binding annotation or XML. You can assign methods on an entity listener class to intercept a particular life cycle event. The method is annotated with the callback in which it is interested. public class TitanAuditLogger { @PostPersist void postInsert(Object entity) { System.out.println("Inserted entity: " + entity.getClass().getName( )); } @PostLoad void postLoad(Object entity) { System.out.println("Loaded entity: " + entity.getClass().getName( )); }

8. 8 Entity Listeners The entity listener class must have a public no-arg constructor. It can be applied to an entity class by using the @javax.persistence.EntityListeners annotation: package javax.persistence; @Target(TYPE) @Retention(RUNTIME) public @interface EntityListeners { Class[] value( ); } You can specify one or more entity listeners that intercept the callback events of an entity class: @Entity @EntityListeners ({TitanAuditLogger.class, EntityJmxNotifier.class}) public class Cabin {...

9. 9 Entity Listeners @PostPersist void afterInsert( ) {... } @PostLoad void afterLoading( ) {... } Entity listeners can also be applied using XML:

10. 10 Entity Listeners Let's look at what would happen if we invoked the following operations: 1. EntityManager em = factory.createEntityManager( ); 2. em.getTransaction().begin( ); 3. Cabin cabin = new Cabin( ); 4. em.persist(cabin); 5. Cabin anotherCabin = em.find(Cabin.class, 5); 6. em.getTransaction().commit( ); Pretend this code executes on the examples we have shown in this chapter. The EntityJmxNotifier class is interested in a callback. The EntityJmxNotifier.beforeInsert( ) method is executed when the EntityManager.persist( ) method is invoked at Line 5.

11. 11 Entity Listeners At Line 7, the TitanAuditLogger.postLoad( ), EntityJmxNotifier.afterLoading( ), and Cabin.afterLoading( ) methods are invoked, in that order, as the @PostLoad event is triggered by the EntityManager.find( ) invocation. The Cabin.afterLoading( ) method is invoked on the same instance returned by the find( ) method. Our persistence provider has decided to delay the database insert of the newly persisted cabin until the transaction commits. In Line 9, the TitanAuditLogger.postPersist( ) and Cabin.afterInsert( ) methods are called, in that order. The Cabin.afterInsert( ) method is invoked on the same entity instance that we persisted in Line 5.

12. 12 Default Entity Listeners You can specify a set of default entity listeners that are applied to every entity class in the persistence unit by using the element under the top-level element in the ORM mapping file. For instance, if you wanted to apply the TitanAuditLogger to every entity class in a particular persistence unit, you would do the following:

13. 13 Default Entity Listeners If you want to turn off default entity listeners to a particular entity class, you can use the @javax.persistence.ExcludeDefaultListeners annotation: @Entity @ExcludeDefaultListeners public class Cabin {... } There is also an XML equivalent of this annotation: </entity If either the @ExcludeDefaultListeners annotation or its XML equivalent are applied to the Cabin entity, the TitanAuditLogger is turned off for that entity.

14. 14 Inheritance and Listeners If you have an inheritance entity hierarchy in which the base class has entity listeners applied to it, any subclass will inherit these entity listeners. If the subclass also has entity listeners applied to it, then both the base and the subclass's listeners will be attached. @Entity @EntityListeners(TitanAuditLogger.class) public class Person { @PostPersist void anotherCallback( ) {... } @Entity @EntityListeners(EntityJmxNotifier.class) public class Customer extends Person {... }

15. 15 Inheritance and Listeners In this example, the TitanAuditLogger entity listener and EntityJmxNotifier will be attached to the Customer entity. If all of these listeners have an @PostPersist callback, the order of callback execution will be as follows: TitanAuditLogger's @PostPersist method EntityJmxNotifier's @PostPersist method Person's @PostPersist anotherCallback( ) method Entity listeners applied to a base class happen before any listeners attached to a subclass. Callback methods defined directly in an entity class happen last. You can turn off inherited entity listeners by using @javax.persistence.ExcludeSuperclassListeners :

16. 16 Inheritance and Listeners @Entity @EntityListeners(TitanAuditLogger.class) public class Person { } @Entity @EntityListeners(EntityJmxNotifier.class) @ExcludeSuperclassListeners public class Customer extends Person {... } In this example, only the EntityJmxNotifier listener would be executed for Customer entity instances. @ExcludeSuperclassListeners has an XML equivalent in the element.