javax.enterprise.event.package-info Maven / Gradle / Ivy
/**
* Annotations and interfaces relating to events.
*
*
{@linkplain javax.enterprise.inject 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.
*
* An event comprises:
*
*
* - A Java object, called the event object
* - A (possibly empty) set of instances of qualifier types, called
* the event qualifiers
*
*
* The {@link javax.enterprise.event.Event} interface is used to
* fire events.
*
* 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.
*
* Event qualifiers
*
* The event qualifiers act as topic selectors, allowing the consumer
* to narrow the set of events it observes. An event qualfier may be an
* instance of any {@linkplain javax.inject.Qualifier qualifier type}.
*
* Observer methods
*
* An {@linkplain javax.enterprise.event.Observes observer method}
* allows the application to receive and respond to event notifications.
* It acts as event consumer, 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 is a method of a bean class or
* {@linkplain javax.enterprise.inject.spi.Extension extension} with a
* parameter annotated {@link javax.enterprise.event.Observes @Observes}.
*
* 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
* {@linkplain javax.enterprise.inject.spi container lifecycle event}, or
* the observer method belongs to an
* {@linkplain javax.enterprise.inject.spi.Extension extension}.
*
*
* If the observer method is a
* {@linkplain javax.enterprise.event.TransactionPhase 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 is not defined, and
* so portable applications should not rely upon the order in which
* observers are called.
*
* Observer methods may throw exceptions:
*
*
* - If the observer method is a
* {@linkplain javax.enterprise.event.TransactionPhase transactional
* observer method}, any exception is caught and logged by the container.
* - 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)
* {@link javax.enterprise.event.ObserverException}.
*
*
* @see javax.enterprise.inject
*
* @see javax.enterprise.event.Observes
* @see javax.enterprise.event.Event
* @see javax.inject.Qualifier
*/
package javax.enterprise.event;