Weld 6.0.0.Beta1 - CDI Reference Implementation

Events

Dependency injection enables loose-coupling by allowing the implementation of the injected bean type to vary, either at deployment time or runtime. Events go one step further, allowing beans to interact with no compile time dependency at all. Event producers raise events that are delivered to event observers by the container.

This basic schema might sound like the familiar observer/observable pattern, but there are a couple of twists:

  • not only are event producers decoupled from observers; observers are completely decoupled from producers,

  • observers can specify a combination of "selectors" to narrow the set of event notifications they will receive, and

  • observers can be notified immediately, or can specify that delivery of the event should be delayed until the end of the current transaction.

The CDI event notification facility uses more or less the same typesafe approach that we’ve already seen with the dependency injection service.

Event payload

The event object carries state from producer to consumer. The event object is nothing more than an instance of a concrete Java class. (The only restriction is that an event type may not contain type variables). An event may be assigned qualifiers, which allows observers to distinguish it from other events of the same type. The qualifiers function like topic selectors, allowing an observer to narrow the set of events it observes.

An event qualifier is just a normal qualifier, defined using @Qualifier. Here’s an example:

@Qualifier
@Target({METHOD, FIELD, PARAMETER, TYPE})
@Retention(RUNTIME)
public @interface Updated {}

Event observers

An observer method is a method of a bean with a parameter annotated @Observes or @ObservesAsync.

public void onAnyDocumentEvent(@Observes Document document) { ... }

or in asynchronous version

public void onAnyDocumentEvent(@ObservesAsync Document document) { ... }

The annotated parameter is called the event parameter. The type of the event parameter is the observed event type, in this case Document. The event parameter may also specify qualifiers.

public void afterDocumentUpdate(@Observes @Updated Document document) { ... }

An observer method need not specify any event qualifiers—in this case it is interested in every event whose type is assignable to the observed event type. Such observer will trigger on both events shown below:

@Inject @Any Event<Document> documentEvent;
@Inject @Updated Event<Document> anotherDocumentEvent;

If the observer does specify qualifiers, it will be notified of an event if the event object is assignable to the observed event type, and if the set of observed event qualifiers is a subset of all the event qualifiers of the event.

The observer method may have additional parameters, which are injection points:

public void afterDocumentUpdate(@Observes @Updated Document document, User user) { ... }

Event producers

Event producers fire events either synchronously or asynchronously using an instance of the parameterized Event interface. An instance of this interface is obtained by injection:

@Inject @Any Event<Document> documentEvent;

Synchronous event producers

A producer raises synchronous events by calling the fire() method of the Event interface, passing the event object:

documentEvent.fire(document);

This particular event will only be delivered to synchronous observer method that:

  • has an event parameter to which the event object (the Document) is assignable, and

  • specifies no qualifiers.

The container simply calls all the synchronous observer methods, passing the event object as the value of the event parameter. If any observer method throws an exception, the container stops calling observer methods, and the exception is rethrown by the fire() method.

Asynchronous event producers

A producer raises asynchronous events by calling the fireAsync() method of the Event interface, passing the event object:

documentEvent.fireAsync(document);

This particular event will only be delivered to asynchronous observer method that:

  • has an event parameter to which the event object (the Document) is assignable, and

  • specifies no qualifiers.

fireAsync method returns immediately and all the resolved asynchronous observers are notified in one or more different threads. If any observer method throws an exception, the container will suppress it and notify remaining observers. The resulting CompletionStage will then finish exceptionally with CompletionException containing all previously suppressed exceptions.

Notification options

The Event.fireAsync() method may be called with a NotificationOptions parameter to configure the notification of asynchronous observer methods , e.g. to specify an Executor object to be used for asynchronous delivery. Weld defines the following non-portable notification options (see WeldNotificationOptions):

Key Value type Description

weld.async.notification.mode

String

The notification mode. Possible values are: SERIAL (default), PARALLEL. See also Notification modes.

weld.async.notification.timeout

Long or String which can be parsed as a long

The notification timeout (in milliseconds) after which the returned completion stage must be completed. If the time expires the stage is completed exceptionally with a CompletionException holding the java.util.concurrent.TimeoutException as its cause. The expiration does not abort the notification of the observers.
Note
 It is also possible to use the key constants and static convenient methods declared on org.jboss.weld.events.WeldNotificationOptions from Weld API, e.g. WeldNotificationOptions.TIMEOUT or WeldNotificationOptions.withParallelMode().
Table 1. Notification modes
Mode Description

SERIAL

Asynchronous observers are notified serially in a single worker thread (default behavior).

PARALLEL

Asynchronous observers are notified in parallel assuming that the java.util.concurrent.Executor used supports parallel execution.

Applying qualifiers to event

Qualifiers can be applied to an event in one of two ways:

  • by annotating the Event injection point, or

  • by passing qualifiers to the select() of Event.

Specifying the qualifiers at the injection point is far simpler:

@Inject @Updated Event<Document> documentUpdatedEvent;

Then, every event fired via this instance of Event has the event qualifier @Updated. The event is delivered to every observer method that:

  • has an event parameter to which the event object is assignable, and

  • does not have any event qualifier except for the event qualifiers that match those specified at the Event injection point.

The downside of annotating the injection point is that we can’t specify the qualifier dynamically. CDI lets us obtain a qualifier instance by subclassing the helper class AnnotationLiteral. That way, we can pass the qualifier to the select() method of Event.

documentEvent.select(new AnnotationLiteral<Updated>(){}).fire(document);

Events can have multiple event qualifiers, assembled using any combination of annotations at the Event injection point and qualifier instances passed to the select() method.

Conditional observer methods

By default, if there is no instance of an observer in the current context, the container will instantiate the observer in order to deliver an event to it. This behavior isn’t always desirable. We may want to deliver events only to instances of the observer that already exist in the current contexts.

A conditional observer is specified by adding receive = IF_EXISTS to the @Observes annotation.

public void refreshOnDocumentUpdate(@Observes(receive = IF_EXISTS) @Updated Document d) { ... }
Note
 A bean with scope @Dependent cannot be a conditional observer, since it would never be called!

Event qualifiers with members

An event qualifier type may have annotation members:

@Qualifier
@Target({METHOD, FIELD, PARAMETER, TYPE})
@Retention(RUNTIME)
public @interface Role {
   RoleType value();
}

The member value is used to narrow the messages delivered to the observer:

public void adminLoggedIn(@Observes @Role(ADMIN) LoggedIn event) { ... }

Event qualifier type members may be specified statically by the event producer, via annotations at the event notifier injection point:

@Inject @Role(ADMIN) Event<LoggedIn> loggedInEvent;

Alternatively, the value of the event qualifier type member may be determined dynamically by the event producer. We start by writing an abstract subclass of AnnotationLiteral:

abstract class RoleBinding
   extends AnnotationLiteral<Role>
   implements Role {}

The event producer passes an instance of this class to select():

documentEvent.select(new RoleBinding() {
   public void value() { return user.getRole(); }
}).fire(document);

Multiple event qualifiers

Event qualifiers may be combined, for example:

@Inject @Blog Event<Document> blogEvent;
...
if (document.isBlog()) blogEvent.select(new AnnotationLiteral<Updated>(){}).fire(document);

The above shown event is fired with two qualifiers - @Blog and @Updated. An observer method is notified if the set of observer qualifiers is a subset of the fired event’s qualifiers. Assume the following observers in this example:

public void afterBlogUpdate(@Observes @Updated @Blog Document document) { ... }
public void afterDocumentUpdate(@Observes @Updated Document document) { ... }
public void onAnyBlogEvent(@Observes @Blog Document document) { ... }
public void onAnyDocumentEvent(@Observes Document document) { ... }}}

All of these observer methods will be notified.

However, if there were also an observer method:

public void afterPersonalBlogUpdate(@Observes @Updated @Personal @Blog Document document) { ... }

It would not be notified, as @Personal is not a qualifier of the event being fired. Or to put it more formally, @Updated and @Personal do not form a subset of @Blog and @Updated.

Transactional observers

Transactional observers receive their event notifications during the before or after completion phase of the transaction in which the event was raised. For example, the following observer method needs to refresh a query result set that is cached in the application context, but only when transactions that update the Category tree succeed:

public void refreshCategoryTree(@Observes(during = AFTER_SUCCESS) CategoryUpdateEvent event) { ... }

There are five kinds of transactional observers:

  • IN_PROGRESS observers are called immediately (default)

  • AFTER_SUCCESS observers are called during the after completion phase of the transaction, but only if the transaction completes successfully

  • AFTER_FAILURE observers are called during the after completion phase of the transaction, but only if the transaction fails to complete successfully

  • AFTER_COMPLETION observers are called during the after completion phase of the transaction

  • BEFORE_COMPLETION observers are called during the before completion phase of the transaction

Transactional observers are very important in a stateful object model because state is often held for longer than a single atomic transaction.

Imagine that we have cached a JPA query result set in the application scope:

import jakarta.ejb.Singleton;
import jakarta.enterprise.inject.Produces;

@ApplicationScoped @Singleton
public class Catalog {

   @PersistenceContext EntityManager em;

   List<Product> products;

   @Produces @Catalog
   List<Product> getCatalog() {
      if (products==null) {
         products = em.createQuery("select p from Product p where p.deleted = false")
            .getResultList();
      }
      return products;
   }

}

From time to time, a Product is created or deleted. When this occurs, we need to refresh the Product catalog. But we should wait until after the transaction completes successfully before performing this refresh!

The bean that creates and deletes `Product`s could raise events, for example:

import jakarta.enterprise.event.Event;

@Stateless
public class ProductManager {
   @PersistenceContext EntityManager em;
   @Inject @Any Event<Product> productEvent;

   public void delete(Product product) {
      em.delete(product);
      productEvent.select(new AnnotationLiteral<Deleted>(){}).fire(product);
   }

   public void persist(Product product) {
      em.persist(product);
      productEvent.select(new AnnotationLiteral<Created>(){}).fire(product);
   }
   ...
}

And now Catalog can observe the events after successful completion of the transaction:

import jakarta.ejb.Singleton;

@ApplicationScoped @Singleton
public class Catalog {
   ...
   void addProduct(@Observes(during = AFTER_SUCCESS) @Created Product product) {
      products.add(product);
   }

   void removeProduct(@Observes(during = AFTER_SUCCESS) @Deleted Product product) {
      products.remove(product);
   }
}

Enhanced version of jakarta.enterprise.event.Event

Weld API offers slight advantage when dealing with events - org.jboss.weld.events.WeldEvent, an augmented version of jakarta.enterprise.event.Event.

Currently there is only one additional method, select(Type type, Annotation…​ qualifiers). This method allows to perform well-known selection with java.lang.reflect.Type as parameter which means things can get pretty generic. While there are no limitations to what you can select, there are limitation to the WeldEvent instance you perform selection on. In order to preserve type-safety, you have to invoke this method on WeldInstance<Object>. Using any other parameter will result in IllegalStateException. Usage looks just as you would except:

@Inject
WeldEvent<Object> event;

public void selectAndFireEventForType(Type type) {
  event.select(type).fire(new Payload());
}