Annotations and interfaces relating to events.
Beans may produce and consume events. Events allows beans to interact in a completely decoupled fashion, with no compile-time dependency between the interacting beans. Most importantly, it allows stateful beans in one architectural tier of the application to synchronize their internal state with state changes that occur in a different tier.
Events may be fired synchronously or asynchronously.
An event comprises:
- A Java object, called the event object
- A (possibly empty) set of instances of qualifier types, called the event qualifiers
Event interface is used to
Event objects and event types
The event object acts as a payload, to propagate state from producer to consumer. An event object is an instance of a concrete Java class with no type variables.
The event types of the event include all superclasses and interfaces of the runtime class of the event object. An event type may not contain a type variable.
The event qualifiers act as topic selectors, allowing the consumer to narrow the set of events it observes. An event qualifier may be an instance of any qualifier type.
An observer method allows the application to receive and respond synchronously to event notifications. And an async observer method allows the application to receive and respond asynchronously to event notifications. they both act as event consumers, observing events of a specific type, with a specific set of qualifiers. Any Java type may be observed by an observer method.
An observer method will be notified of an event if:
- the event object is assignable to the type observed by the observer method,
- the observer method has all the event qualifiers of the event, and
- either the event is not a container lifecycle event, or the observer method belongs to an extension.
If a synchronous observer method is a transactional observer method and there is a JTA transaction in progress when the event is fired, the observer method is notified during the appropriate transaction completion phase. Otherwise, the observer is notified when the event is fired.
The order in which observer methods are called depends on the value of the @Priority applied to the observer.
If no priority is defined on a observer, its priority is jakarta.interceptor.Interceptor.Priority.APPLICATION+500.
If two observer have the same priority their relative order is undefined.
Observer methods may throw exceptions:
- If the observer method is a transactional observer method, any exception is caught and logged by the container.
- If the observer method is asynchronous, any exception is caught by the container and added as a suppressed exception
CompletionExceptionthat could be handle by the application
- Otherwise, the exception aborts processing of the event.
No other observer methods of that event will be called. The
exception is rethrown. If the exception is a checked exception,
it is wrapped and rethrown as an (unchecked)
Interface Summary Interface Description Event<T>Allows the application to fire events of a particular type. NotificationOptionsNotification options are used to configure observer notification. NotificationOptions.BuilderNotification options builder.
Class Summary Class Description Shutdown Startup
Enum Summary Enum Description ReceptionDistinguishes conditional observer methods from observer methods which are always notified. TransactionPhaseDistinguishes the various kinds of transactional observer methods from regular observer methods which are notified immediately.
Exception Summary Exception Description ObserverExceptionIndicates that a checked exception was thrown by an observer method during event notification.
Annotation Types Summary Annotation Type Description ObservesIdentifies the event parameter of an observer method. ObservesAsyncIdentifies the event parameter of an asynchronous observer method.