org.esbtools.eventhandler

Interface DocumentEvent

public interface DocumentEvent

Models an event which corresponds to a publishable document message.

Document events capture knowledge of how to construct a message for a particular document, as well as how this event compares to other document events such that other document events may be redundant (and can therefore be ignored), or if the events can be merged together such that one document can be looked up which satisfies a number of events. Checking for these conditions is a part of optimizing the amount of messages which are produced as a result of event processing.

Method Summary

Modifier and Type	Method and Description
boolean	couldMergeWith(DocumentEvent event) Determines if the entity looked up in this event and the provided event could be represented instead as a single event which refers to data for both events.
boolean	isSupersededBy(DocumentEvent event) If the provided event's entity is looked up, will it include whatever change that this event was intended to share?
Future<?>	lookupDocument() Immediately returns with a Future representing the document this event should publish.
DocumentEvent	merge(DocumentEvent event) If possible, returns an event that represents both this event and the provided event.

Method Detail

lookupDocument

Future<?> lookupDocument()

Immediately returns with a Future representing the document this event should publish.

The document format itself is deliberately implementation specific.

This method is expected to never throw an exception. Failures should be captured in the returned Future.

isSupersededBy

boolean isSupersededBy(DocumentEvent event)

If the provided event's entity is looked up, will it include whatever change that this event was intended to share?

Superseded events can be safely ignored as long as an event superseding it is processed.

This is a function of both the identity of the entity represented in this event, and the time of which the provided event may have been processed. For instance, if they both refer to the same entity, and this event occurred before the provided event was processed, then logically this event is superseded by the other. However, is this event occurred after the other was published, the other does not supersede this event, despite them referring to the same entity.

This is intended to be a quick optimization before other logic is performed.

couldMergeWith

boolean couldMergeWith(DocumentEvent event)

Determines if the entity looked up in this event and the provided event could be represented instead as a single event which refers to data for both events.

If two events are equivalent, they cannot be merged. The result of a merge is a new event, and it is expected that this new event be published instead of both merged events. Therefore, an event that is equivalent to another should be determined to be superseded, marked at such, and ignored, simply choosing one event over the other. A merge results in two events being ignored, and a new, slightly different one to take both of their places.

See Also:

merge(DocumentEvent)

merge

DocumentEvent merge(DocumentEvent event)

If possible, returns an event that represents both this event and the provided event. That is, looking up the entity for the result of the merge will include all of the data that would have been in both events.

Intended as an optimization that turns two data lookups with some redundant data, some different, into one data lookup that would include both events' entity data.

Returns:

A new event which represents both this and the provided event.

Throws:

UnsupportedOperationException - if the two events could not be merged. Check if two events can be merged first by calling couldMergeWith(DocumentEvent).