JPA Lifecycle Events

Callback methods are user-defined methods that are attached to entity lifecycle events. JPA invokes these methods automatically when the corresponding events occur.

This page covers the following topics:

Internal callback methodsImplementation restrictionsListeners and external callback methodsDefault entity listenersCallback invocation order

Internal callback methods

Internal callback methods are defined within an entity class. For example, the following entity class defines all supported callback methods with empty implementations:

@Entityjakarta.persistence.EntityDeclares that the annotated class is an entity.
public static class MyEntityWithCallbacks {
    @PrePersistjakarta.persistence.PrePersistSpecifies a callback method for the corresponding lifecycle event. void onPrePersist() {}
    @PostPersistjakarta.persistence.PostPersistSpecifies a callback method for the corresponding lifecycle event. void onPostPersist() {}
    @PostLoadjakarta.persistence.PostLoadSpecifies a callback method for the corresponding lifecycle event. void onPostLoad() {}
    @PreUpdatejakarta.persistence.PreUpdateSpecifies a callback method for the corresponding lifecycle event. void onPreUpdate() {}
    @PostUpdatejakarta.persistence.PostUpdateSpecifies a callback method for the corresponding lifecycle event. void onPostUpdate() {}
    @PreRemovejakarta.persistence.PreRemoveSpecifies a callback method for the corresponding lifecycle event. void onPreRemove() {}
    @PostRemovejakarta.persistence.PostRemoveSpecifies a callback method for the corresponding lifecycle event. void onPostRemove() {}
}

Internal callback methods must return void and take no arguments. They can have any name and any access level (public, protected, package, or private) but must not be static.

The annotation on a method specifies when the callback method is invoked:

An entity class can define callback methods for any combination of lifecycle events, but it can have only one callback method for each event. However, the same method can handle multiple callback events if it is marked with more than one callback annotation.

By default, callback methods in a superclass are also invoked for entities of its subclasses, unless a subclass overrides the method.

Implementation restrictions

To avoid conflicts with the database operation that triggers the event, callback methods must not call EntityManagerjakarta.persistence.EntityManagerInterface used to interact with the persistence context. or Queryjakarta.persistence.QueryInterface used to control query execution. methods or access other entities.

If a callback method throws an exception during a transaction, the transaction is marked for rollback, and no more callback methods for that operation are invoked.

Listeners and external callback methods

Instead of defining callback methods inside an entity class, you can define them in a separate listener class:

public class MyListener {
    @PrePersistjakarta.persistence.PrePersistSpecifies a callback method for the corresponding lifecycle event. void onPrePersist(Object o) {}
    @PostPersistjakarta.persistence.PostPersistSpecifies a callback method for the corresponding lifecycle event. void onPostPersist(Object o) {}
    @PostLoadjakarta.persistence.PostLoadSpecifies a callback method for the corresponding lifecycle event. void onPostLoad(Object o) {}
    @PreUpdatejakarta.persistence.PreUpdateSpecifies a callback method for the corresponding lifecycle event. void onPreUpdate(Object o) {}
    @PostUpdatejakarta.persistence.PostUpdateSpecifies a callback method for the corresponding lifecycle event. void onPostUpdate(Object o) {}
    @PreRemovejakarta.persistence.PreRemoveSpecifies a callback method for the corresponding lifecycle event. void onPreRemove(Object o) {}
    @PostRemovejakarta.persistence.PostRemoveSpecifies a callback method for the corresponding lifecycle event. void onPostRemove(Object o) {}
}

External callback methods must return void and accept a single argument: the entity that is the source of the event. The argument's type can be Object or a more specific entity type. The listener class must be stateless and have a public, no-argument constructor to allow JPA to instantiate it.

To attach a listener to an entity, use the @EntityListenersjakarta.persistence.EntityListenersSpecifies the callback listener classes to be used for an entity or mapped superclass. annotation:

@Entityjakarta.persistence.EntityDeclares that the annotated class is an entity. @EntityListenersjakarta.persistence.EntityListenersSpecifies the callback listener classes to be used for an entity or mapped superclass.(MyListener.class)
    public class MyEntityWithListener {
}

You can attach multiple listener classes to a single entity:

@Entityjakarta.persistence.EntityDeclares that the annotated class is an entity. @EntityListenersjakarta.persistence.EntityListenersSpecifies the callback listener classes to be used for an entity or mapped superclass.({MyListener1.class, MyListener2.class})
    public class MyEntityWithTwoListeners {
}

Listeners attached to an entity class are inherited by its subclasses. To prevent this inheritance, add the @ExcludeSuperclassListenersjakarta.persistence.ExcludeSuperclassListenersSpecifies that the invocation of superclass listeners is to be excluded for the entity class (or mapped superclass) and its subclasses. annotation to the subclass:

@Entityjakarta.persistence.EntityDeclares that the annotated class is an entity. @ExcludeSuperclassListenersjakarta.persistence.ExcludeSuperclassListenersSpecifies that the invocation of superclass listeners is to be excluded for the entity class (or mapped superclass) and its subclasses.
    public class EntityWithNoListener extends EntityWithListener {
}

Default entity listeners

Default entity listeners are applied automatically to all entities in a persistence unit. You can define default listeners only in a mapping XML file, such as orm.xml; there is no equivalent annotation:

<entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm
http://java.sun.com/xml/ns/persistence/orm_1_0.xsd" version="1.0">
  <persistence-unit-metadata>
    <persistence-unit-defaults>
      <entity-listeners>
        <entity-listener class="samples.MyDefaultListener1" />
        <entity-listener class="samples.MyDefaultListener2" />
      </entity-listeners>
    </persistence-unit-defaults>
  </persistence-unit-metadata>
</entity-mappings>

This mapping file must be in the default location, META-INF/orm.xml, or in a location specified in your persistence unit definition in persistence.xml.

To exclude an entity class and its subclasses from using the default listeners, use the @ExcludeDefaultListenersjakarta.persistence.ExcludeDefaultListenersSpecifies that the invocation of default listeners is to be excluded for the entity class (or mapped superclass) and its subclasses. annotation:

@Entityjakarta.persistence.EntityDeclares that the annotated class is an entity. @ExcludeDefaultListenersjakarta.persistence.ExcludeDefaultListenersSpecifies that the invocation of default listeners is to be excluded for the entity class (or mapped superclass) and its subclasses.
public class NoDefaultListenersForThisEntity {
}
@Entityjakarta.persistence.EntityDeclares that the annotated class is an entity.
public class NoDefaultListenersForThisEntityEither
    extends NoDefaultListenersForThisEntity {
}

Callback invocation order

When multiple callback methods are defined for a single lifecycle event, JPA invokes them in the following order:

  • External callback methods, defined in listeners, are invoked before internal callback methods, defined in entity classes.
  • The invocation order for listeners is as follows: default listeners, listeners on superclasses (from the top of the inheritance hierarchy down), and finally, listeners on the entity class itself. If multiple listeners are defined at the same level, they are invoked in the order in which they are specified.
  • Internal callback methods are invoked in order of inheritance, from the highest-level superclass down to the entity class.
< Locking^ Advanced TopicsShared L2 Cache >