Domain Event

How it Works

The essence of a Domain Event is that you use it to capture things that can trigger a change to the state of the application you are developing. These event objects are then processed to cause changes to the system, and stored to provide an Audit Log.

Figure 1: Events funnel inputs into a single source.

Figure 1 helps illustrate the point. Here we have a system with inputs from a user interface, messaging system, and some direct manipulation of database tables. In order to resolve these to Domain Event we have components that interact with each of these input streams and convert the inputs into a stream of Domain Event which are stored in a persistent log. An event processor then reads the events from the log and processes them triggering our application to do whatever it's supposed to do.

In this stream the first input layer of the system takes no action to the stimulus other than to create and log an event. The second layer can then be ignorant of the actual input source, it just reacts to the event and processes it.

For this example I've shown just the one event log. In practice it often makes sense to separate the logs if the events have different response requirements. A user interface will typically want a much faster response time than many remote messaging systems, so it makes sense to put user interface traffic into a different log and use a separate processor for them.

The diagram implies an asynchronous pipes and filters style of interaction, but this isn't an essential part of the approach. Indeed a common approach, particularly with user interface stimuli, is to have the UI handler invoke the event processor directly in a synchronous interaction.

Each Domain Event captures information from the external stimulus. Since this is logged and we want to use the log as an audit trail, it's important that this source data is immutable. That is once you've created the event object this source data cannot be changed. However there is also another kind of data on the event that records what a system has done with it - I call this the processing data. I characterize the data on a Domain Event as immutable source data that captures what the event is about and mutable processing data that records what the system does in response to it. Source data on a credit card charge would include how much the charge was for, who the vendor was, etc. Processing data might include which statement it appeared on. If your platform has particular support for immutable objects it may be worth splitting the event into two objects to take advantage of this.

Although the source data can never change, it may be that the system needs to handle a change - typically because the original event was incorrect. You can handle this by receiving this change as a separate Retroactive Event. The processor then handles the retroactive event to correct the consequences of the earlier erroneous event. Often this processing can be done at a very generic level.

A third, but only occasional, category of event data is cached data from derivations from other data on the event stream. In these cases the event processor summarizes information from past events while processing the current event and adds that summarized data to the current event to speed up future processing. Like any cache, it's important to signal the fact that this data is free to be removed and recalculated should any adjustments occur.

Different events occur for different reasons, so it's common to use different types of events. The event processor will then use the event type as part of its dispatch mechanism. The type of event can be represented by using subtypes of events, or a separate event type object, or a mixture of both.

It's quite common that different types of event carry different data, so using subtypes of event for the event types fits in well with that. The problem with subtypes is that this leads to a proliferation of types, that is particularly frustrating if much of the data is the same. A hybrid approach uses subtypes to handle different data and event type objects to signal dispatching.

Events are about something happening at a point in time, so it's natural for events to contain time information. When doing this it's important to consider two Time Point that could be stored with the event: the time the event occurred in the world and the time the event was noticed . These Time Points correspond to the notions of actual and record time.

Of course you don't always need both Time Points, but you should always consider whether you need both. The danger is picking one Time Point, and not being clear which Time Point you picked, either at the time or later. So I also suggest you name the Time Point clearly to indicate which one it is.

It's possible you may need multiple record Time Points to record when the event was noticed by various different systems.