Module jakarta.data
Package jakarta.data.event

Class LifecycleEvent<E>

java.lang.Object
jakarta.data.event.LifecycleEvent<E>
Type Parameters:
E - the entity type
Direct Known Subclasses:
PostDeleteEvent, PostInsertEvent, PostUpdateEvent, PostUpsertEvent, PreDeleteEvent, PreInsertEvent, PreUpdateEvent, PreUpsertEvent
public abstract class LifecycleEvent<E> extends Object

Abstract supertype of events relating to lifecycle methods.

In Jakarta EE, a bean may observe such events via CDI:


 void onInsertBook(@Observes PostInsertEvent<Book> bookInsertion) {
     Book book = bookInsertion.entity();
     ...
 }

As usual for a CDI event, an observer of a LifecycleEvent is notified synchronously and immediately by default. An observer may elect to receive notifications during a phase of the transaction completion cycle by explicitly specifying a TransactionPhase, for example:

  • @Observes(during=BEFORE_COMPLETION) to be notified just before transaction completion, or
  • @Observes(during=AFTER_SUCCESS) to be notified after successful completion of the transaction.

An observer may choose to be notified asynchronously using @ObservesAsync. However, the mutable state held by the entity is not in general safe for concurrent access, and so portable applications must not use @ObservesAsync to observe a LifecycleEvent. If the state of an entity is accessed from an asynchronous observer method for a lifecycle event, the resulting behavior is undefined and unportable.

  • Constructor Details

    • LifecycleEvent

      public LifecycleEvent(E entity)

  • Method Details

    • entity

      public E entity()
      The entity which is being processed by the lifecycle method.
      • For a Pre event, this is always the instance which was passed as an argument to the lifecycle method, and its state reflects the state of the entity before execution of the lifecycle method.
      • For a Post event, it may or may not be identical to the object passed as an argument to the lifecycle method, and it may or may not be identical to the instance returned by the lifecycle method, if any. If the state of the entity changes as a result of execution of the lifecycle method, those changes may or may not be reflected in the entity returned by this method.

      Thus, a portable application should not assume that the state of the entity in a Post event faithfully reflects the current state of the corresponding record in the database.

      A portable application must not mutate the state of the entity instance returned by this method. If the state of the entity instance is mutated while event listeners are being notified, the resulting behavior is undefined and unportable.