CDI Events solve fancy problems elegantly (Part 2)

Problem: Does your application have a heartbeat?

I used to spread the phrase "every decent application needs a timer bean". Since JEE6, I have rephrased it to "every decent application needs a heart beat".

Whaddaya?

The @Schedule annotation improves upon the old timer service because it has zero admin effort. However, it has issues:

The configuration of @Schedule is in the static code, you cannot modify it at runtime, for example with values from a configuration file outside the deployment package.

Further, I think most timed routine jobs in an application are of the simple sort every minute, every quarter hour, every hour, at time x every day. I rarely find a reason to be more granular than this.

@Scheduled has been inspired by cron, which is flexibly configured with a text file. This is way different to compiling the static config into a class file in an EAR and not being able to modify it in the deployed application. That's very "un-cronish".

How about this idea: a heartbeat event is fired every minute and subscribers can observe it. The event has inspection methods to find out about the event time properties. The observer can be configured at runtime using data from an external config file.

The HeartbeatEvent has a bunch of inquiry methods. isTime(), isMinuteInterval, isHourInterval() take parameters, which can be fetched from a configuration, for example. Having the Calendar at hand, it is possible to invent all kinds of inquiries. Those are the ones that I find most useful.

public class HeartbeatEvent {
    private Calendar calendar;
    public HeartbeatEvent() {
        this.calendar = new GregorianCalendar();
    }
    /**
     * "at x hour and y minutes"
     * Use minute == 0 to test against a specific full hour.
     * @param hour 0-23
     * @param minute 0-59
     * @return true if match
     */
    public boolean isTime(int hour, int minute) {
        return calendar.get(Calendar.HOUR_OF_DAY) == hour && calendar.get(Calendar.MINUTE) == minute;
    }
    /**
     * "every n minutes"
     * @param minutes minute interval 0-59
     * @return true if match
     */
    public boolean isMinuteInterval(int minutes) {
        return calendar.get(Calendar.MINUTE) % minutes == 0;
    }
    /**
     * "every n hours"
     * @param hour 0-23
     * @return true if match
     */
    public boolean isHourInterval(int hour) {
        return calendar.get(Calendar.HOUR_OF_DAY) % hour == 0 && isFullHour();
    }
    public boolean isFullHour() {
        return calendar.get(Calendar.MINUTE) == 0;
    }
    public boolean isHalfHour() {
        return isMinuteInterval(30);
    }
    public boolean isQuarterHour() {
        return isMinuteInterval(15);
    }
}

The HeartbeatEmitter:

@Singleton
public class HeartbeatEmitter {
    @Inject
    private Event<HeartbeatEvent> heartbeat;

    @Schedule(hour="*", minute="*", persistent = false)
    public void emit() {
        heartbeat.fire(new HeartbeatEvent());
    }
}

Example heartbeat observer:

public void fileCleanup(@Observes HeartbeatEvent heartbeat) {
  if (heartbeat.isFullHour()) {
      // do file cleanup every full hour
  }
}

CDI Events solve fancy problems elegantly (Part 1)

Events are a sweet spot in CDI. I have done a lot of enterprise application integration (EAI) with queuing systems and I am happy to find that message passing (aka events) has arrived at JEE6 in a nicely integrated fashion.

Problem: Arbitrary-time-delayed execution of operations

Imagine an application where user A triggers an operation, which needs the confirmation of another user B before it can be executed. The point of time when B decides to confirm is not known in advance and arbitrary.

Possible scenario: the request for confirmation is sent from A to B via the internal notification system of the application. B opens the notification, clicks on the "Confirm" button, and executes the operation on behalf of A.

"I need a workflow system!" some enterprise architects blurb immediately.
"I need Lotus Notes!" ...no comment :-)

No you don't. With CDI it is surprisingly little code.

With CDI you can go about like this:

• (user A) Create an event (more on that later) and serialize it to a format, which can be stored easily. I've used JSON for that purpose.
• (user A) Transport the serialized event to user B in the application. Store it in a DB for example, where B can pick it up later.
• (user B much later) Deserialize the event and fire it.
• (system) Observe the event and carry out the operation associated with it. It behaves as if user A had started the operation directly.

From an architectural view, there are some nice aspects to mention:

• The inversion of dependency with events decouples the creator of the event from the implementation of the operation. This is analogous to putting an interface between caller and implementation
• The event observer has no knowledge about the mechanism how the event is transported from A to B, nor how the event has been created. All it knows is what event to observe and what method to call with the data from the event.
• In a publish-subscribe fashion, more observers can be added non-invasively.
• The same observer can be used without time delay when the event creator fires the event immediately, without prior serialization.

Now let's look at a sketchy example, which I have simplified to concentrate on the main concepts.

To define an Event in CDI you need two things:

• A class, which represents the event (actually the message payload) an Observer listens to.
• An Event instance, which is used to fire (publish) the event object.

The event looks as follows:

public class HelloEvent {
   public String greetings;
   public HelloEvent(String greetings) //... as usual
   // to hide the preferred (de)serialization format
   // the event has two methods to take care of that.
   // XML or JSON are possible choices.
   public String toString() // ...
   public static HelloEvent fromString(String s) //...
}

Designing the Hello event service

The event producer must be injected into a class. An event service is a good place. It's job is to encapsulate the event mechanism.

@Inject private Event<HelloEvent> helloEventProducer;

To allow clients to fire a HelloEvent without knowing the plumbing, the event service exposes a method like this:

public void sendHello(HelloEvent event) {
    helloEventProducer.fire(event);
}

The observer listens to HelloEvents. It also lives in the event service. This keeps all the event business in one place.

public void receiveHello(@Observes HelloEvent event) {
  // How the hello greetings are actually processed
  // is not important here. Some imaginary HelloProcessor
  // is responsible for that. It does not know about the
  // Event business and only cares for the greeting text.
  helloProcessor(event.greetings);
}

I needed a transactional event service, so I chose a stateless EJB:

@Stateless
public class HelloEventService {
   @Inject private Event<HelloEvent> helloEventProducer;
   public void sendHello(HelloEvent event) //...
   public void receiveHello(@Observes HelloEvent event) //...
}

We are done plumbing the CDI events.

Designing the Hello confirmation service

Next is a rough sketch of a HelloService, which encapsulates the time-delayed confirmation process.

@Stateless
public class HelloService {
  @EJB
  private HelloEventService eventSvc;
  public void sendHelloConfirmed(String greeting) {
     // Extremely simplified: store the event
     // serialized for later retrieval.
     storeSomewhere(new HelloEvent(greeting).toString());
  }

  public void executeHello(String serializedEvent) {
    eventSvc.sendHello(HelloEvent.fromString(serializedEvent));
  }
}

The HelloService has no dependency to CDI event handling, nor has it any clue about the event (de)serialization format. It only knows the HelloEvent and the HelloEventService.

How the serialized event string is passed around is not relevant for the concept. I think you get the idea. To wrap up, let's look at the client code, which is executed by user A (the sender) and user B (the guy who confirms A's intended operation).

The client code

Code executed by user A:
@EJB HelloService hello;
...
hello.sendHelloConfirmed("My goodness, you became fat!");

User B code executed at some later time:
@EJB HelloService hello;
...
String serializedEvent = ... // comes from some storage
hello.executeHello(serializedEvent);

Neither EventService, HelloEvent, nor any CDI Event artifacts appear in the client code. The mechanism of the confirmation process is encapsulated.

The concept as such is not exclusive to CDI events, of course, and could have been realized with JMS and message-driven beans as well. However, the simple and elegant integration with CDI makes the message passing (aka event) architectural pattern easier accessible than before.

---

Sidenote: JSON Serialization

I like JSON for its natural mapping of composed objects, lists, arrays, and maps. As with XML, with JSON mapping libraries there is a choice between comfort and flexibility.

XStream for example can (de)serialize instances, but is sensitive to versioning issues. It dies when it hits content during deserialization, which it cannot bind. This is typical for tight language bindings and I've seen that with XML already.

json-simple is totally generic, handles any valid JSON, but you need to know how to find things in the nested Maps and Arrays, and you need to map values yourself.

I think JXPath + json-simple is a very flexible and powerful combination for nested structures.