CDI APIs 2.0 · javax.enterprise.event.Event

Allows the application to fire events of a particular type.

Beans fire events via an instance of the Event interface, which may be injected:

@Inject
@Any
Event<LoggedInEvent> loggedInEvent;

The fire() method accepts an event object:

public void login() { 
   ...
   loggedInEvent.fire( new LoggedInEvent(user) );
}

Any combination of qualifiers may be specified at the injection point:

@Inject
@Admin
Event<LoggedInEvent> adminLoggedInEvent;

Or, the @Any qualifier may be used, allowing the application to specify qualifiers dynamically:

@Inject
@Any
Event<LoggedInEvent> loggedInEvent;

For an injected Event:

the specified type is the type parameter specified at the injection point, and
the specified qualifiers are the qualifiers specified at the injection point.

Events may also be fired asynchronously with fireAsync(Object) and fireAsync(Object, NotificationOptions) methods

Method Summary

Modifier and Type	Method and Description
public void	fire(T the event object event) Fires an event with the specified qualifiers and notifies observers.
public <U extends T> CompletionStage<U>	Returns: a `CompletionStage` allowing further pipeline composition on the asynchronous operation. Default asynchronous execution facility is container specific. If any observer notified by this event throws an exception then the resulting CompletionStage is completed exceptionally with `java.util.concurrent.CompletionException` that wraps all the exceptions raised by observers as suppressed exception. If no exception is thrown by observers then the resulting CompletionStage is completed normally with the event payload. fireAsync(U the event object event) Fires an event asynchronously with the specified qualifiers and notifies asynchronous observers.
public <U extends T> CompletionStage<U>	Returns: a `CompletionStage` allowing further pipeline composition on the asynchronous operation. Default asynchronous execution facility is container specific. If any observer notified by this event throws an exception then the resulting CompletionStage is completed exceptionally with `java.util.concurrent.CompletionException` that wraps all the exceptions raised by observers as suppressed exception. If no exception is thrown by observers then the resulting CompletionStage is completed normally with the event payload. fireAsync(U the event object event, NotificationOptions the notification options options) Fires an event asynchronously with the specified qualifiers and notifies asynchronous observers.
public Event<T>	Returns: the child `Event` select(Annotation... the additional specified qualifiers qualifiers) Obtains a child `Event` for the given additional required qualifiers.
public < the specified type U extends T> Event<U>	Returns: the child `Event` select(Class<U> a `java.lang.Class` representing the specified type subtype, Annotation... the additional specified qualifiers qualifiers) Obtains a child `Event` for the given required type and additional required qualifiers.
public < the specified type U extends T> Event<U>	Returns: the child `Event` select(TypeLiteral<U> a `javax.enterprise.util.TypeLiteral` representing the specified type subtype, Annotation... the additional specified qualifiers qualifiers) Obtains a child `Event` for the given required type and additional required qualifiers.

Method Detail

fire back to summary

fire	back to summary
public void fire(T event) Fires an event with the specified qualifiers and notifies observers. Parameters event:T the event object Exceptions IllegalArgumentException: if the runtime type of the event object contains a type variable ObserverException: if a notified observer throws a checked exception, it will be wrapped and rethrown as an (unchecked) `ObserverException`

public void fire(T event)

Fires an event with the specified qualifiers and notifies observers.

Parameters

event:T: the event object

Exceptions

IllegalArgumentException:: if the runtime type of the event object contains a type variable
ObserverException:: if a notified observer throws a checked exception, it will be wrapped and rethrown as an (unchecked) ObserverException

fireAsync back to summary

fireAsync	back to summary
public <U extends T> CompletionStage<U> fireAsync(U event) Fires an event asynchronously with the specified qualifiers and notifies asynchronous observers. Parameters event:U the event object Returns:CompletionStage<U> a `CompletionStage` allowing further pipeline composition on the asynchronous operation. Default asynchronous execution facility is container specific. If any observer notified by this event throws an exception then the resulting CompletionStage is completed exceptionally with `java.util.concurrent.CompletionException` that wraps all the exceptions raised by observers as suppressed exception. If no exception is thrown by observers then the resulting CompletionStage is completed normally with the event payload. Exceptions IllegalArgumentException: if the runtime type of the event object contains a type variable Since 2.0

public CompletionStage fireAsync(U event)

Fires an event asynchronously with the specified qualifiers and notifies asynchronous observers.

Parameters

event:U: the event object

Returns:CompletionStage

a CompletionStage allowing further pipeline composition on the asynchronous operation. Default asynchronous execution facility is container specific. If any observer notified by this event throws an exception then the resulting CompletionStage is completed exceptionally with java.util.concurrent.CompletionException that wraps all the exceptions raised by observers as suppressed exception. If no exception is thrown by observers then the resulting CompletionStage is completed normally with the event payload.

Exceptions

IllegalArgumentException:: if the runtime type of the event object contains a type variable

Since

2.0

fireAsync back to summary

fireAsync	back to summary
public <U extends T> CompletionStage<U> fireAsync(U event, NotificationOptions options) Fires an event asynchronously with the specified qualifiers and notifies asynchronous observers. A custom `Executor` will be used to make asynchronous calls Parameters event:U the event object options:NotificationOptions the notification options Returns:CompletionStage<U> a `CompletionStage` allowing further pipeline composition on the asynchronous operation. Default asynchronous execution facility is container specific. If any observer notified by this event throws an exception then the resulting CompletionStage is completed exceptionally with `java.util.concurrent.CompletionException` that wraps all the exceptions raised by observers as suppressed exception. If no exception is thrown by observers then the resulting CompletionStage is completed normally with the event payload. Exceptions IllegalArgumentException: if the runtime type of the event object contains a type variable Since 2.0

public CompletionStage fireAsync(U event, NotificationOptions options)

Fires an event asynchronously with the specified qualifiers and notifies asynchronous observers. A custom Executor will be used to make asynchronous calls

Parameters

event:U: the event object
options:NotificationOptions: the notification options

Returns:CompletionStage

Exceptions

IllegalArgumentException:: if the runtime type of the event object contains a type variable

Since

2.0

select back to summary

select	back to summary
public Event<T> select(Annotation... qualifiers) Obtains a child `Event` for the given additional required qualifiers. Parameters qualifiers:Annotation[] the additional specified qualifiers Returns:Event<T> the child `Event` Exceptions IllegalArgumentException: if passed two instances of the same non repeating qualifier type, or an instance of an annotation that is not a qualifier type

public Event<T> select(Annotation... qualifiers)

Obtains a child Event for the given additional required qualifiers.

Parameters

qualifiers:Annotation[]: the additional specified qualifiers

Returns:Event<T>

the child Event

Exceptions

IllegalArgumentException:: if passed two instances of the same non repeating qualifier type, or an instance of an annotation that is not a qualifier type

select back to summary

select	back to summary
public <U extends T> Event<U> select(Class<U> subtype, Annotation... qualifiers) Obtains a child `Event` for the given required type and additional required qualifiers. Parameters <U> the specified type subtype:Class<U> a `java.lang.Class` representing the specified type qualifiers:Annotation[] the additional specified qualifiers Returns:Event<U> the child `Event` Exceptions IllegalArgumentException: if passed two instances of the same non repeating qualifier type, or an instance of an annotation that is not a qualifier type

public Event select(Class subtype, Annotation... qualifiers)

Obtains a child Event for the given required type and additional required qualifiers.

Parameters

: the specified type
subtype:Class: a java.lang.Class representing the specified type
qualifiers:Annotation[]: the additional specified qualifiers

Returns:Event

the child Event

Exceptions

IllegalArgumentException:: if passed two instances of the same non repeating qualifier type, or an instance of an annotation that is not a qualifier type

select back to summary

select	back to summary
public <U extends T> Event<U> select(TypeLiteral<U> subtype, Annotation... qualifiers) Obtains a child `Event` for the given required type and additional required qualifiers. Parameters <U> the specified type subtype:TypeLiteral<U> a `javax.enterprise.util.TypeLiteral` representing the specified type qualifiers:Annotation[] the additional specified qualifiers Returns:Event<U> the child `Event` Exceptions IllegalArgumentException: if passed two instances of the same non repeating qualifier type, or an instance of an annotation that is not a qualifier type

public Event select(TypeLiteral subtype, Annotation... qualifiers)

Obtains a child Event for the given required type and additional required qualifiers.

Parameters

: the specified type
subtype:TypeLiteral: a javax.enterprise.util.TypeLiteral representing the specified type
qualifiers:Annotation[]: the additional specified qualifiers

Returns:Event

the child Event

Exceptions

IllegalArgumentException:: if passed two instances of the same non repeating qualifier type, or an instance of an annotation that is not a qualifier type

public Interface Event<T>

Method Summary

Method Detail