2010/12/15 - Apache Excalibur has been retired.

For more information, please explore the Attic.

Why Event Was Created

Event was created out of a desire to express the Staged Event Driven Architecture (SEDA) design in an Avalon way. It has grown to be a robust event pipelining library. We maintained the core concepts from the SandStorm server, and cleaned up the API to have Queues operate in a more transactional way.

When To Use Event

Most of the time, your use of the Event package is only to interface to other subsystems. For instance, the Command Manager uses the Event Queues to receive commands from multiple threads simultaneously.

You can also use Event when you are developing new systems that have loosely coupled, disjunct pieces. One of the core benefits of using event pipelines is that we can easily reroute the Queues while the system is running, and not lose any events.

Core Concepts

An Event Pipeline has a set of Sources and Sinks. A Source is where you get more events, or the "dequeue" side of an event Queue. A Sink is where you send events on to the next stage, or the "enqueue" side of an event Queue.

Source

The Source can be blocking or non-blocking. A blocking Source will stop the current thread from processing until there are new events to give to it. A non-blocking Source will return an empty set of events immediately if there are no more events.

Sink

The Sink allows you to add events in a variety of ways. You can simply add them one at a time, or you can add a whole group of events at one time. The Sink also supports a transactional enqueue which means we can push some events on to the Sink, but wait to commit or cancel the events at a later time. The Sink will make room for the events, but it will not let them pass through until they are officially committed.

Queue

A Queue is merely the union of a Sink and a Source. A Queue will manage the throughput of the events from Sink to Source.

Signals and Messages

Signals and Messages are special events that provide contextual information. A message will have a string and/or an object attached to it. They are used mainly for reporting purposes, or for the begginings of a Messaging Oriented Middleware (MOM) implementation. A Signal is a control event that the Queue, and the system react to.