org.esbtools.eventhandler

Interface DocumentEventRepository

public interface DocumentEventRepository

Abstracts a transactional backing store and staging area for events.

A repository is responsible for handling CRUD and data parsing operations around these objects, in whatever scheme necessary.

Production implementations are expected to be thread safe, even across a network.

Method Summary

Modifier and Type	Method and Description
void	addNewDocumentEvents(Collection<? extends DocumentEvent> documentEvents) Persists new document events.
void	ensureTransactionActive(DocumentEvent event) Throws a descriptive exception if the provided event is not in an active transaction, or if the current state of its transaction is unknown.
void	markDocumentEventsPublishedOrFailed(Collection<? extends DocumentEvent> events, Collection<FailedDocumentEvent> failures) Ends the active transactions with the provided events, providing failure information if any were not able to be published.
List<? extends DocumentEvent>	retrievePriorityDocumentEventsUpTo(int maxEvents) Retrieve the top maxEvents document events in priority order.

Method Detail

addNewDocumentEvents

void addNewDocumentEvents(Collection<? extends DocumentEvent> documentEvents)
                   throws Exception

Persists new document events.

The document events are retrievable from retrievePriorityDocumentEventsUpTo(int).

Throws:

Exception

retrievePriorityDocumentEventsUpTo

List<? extends DocumentEvent> retrievePriorityDocumentEventsUpTo(int maxEvents)
                                                          throws Exception

Retrieve the top maxEvents document events in priority order. Document events are created by calling addNewDocumentEvents(Collection).

Document events are expected to be fully optimized and ready to be published immediately. That is, the returned list should contain only unique, merged events, in priority order. Events which were superseded or made obsolete by a merge operation should not be included.

Subsequent calls should do their best to return unique sets, even among multiple threads.

Retrieved document events begin a transaction with those events. Calling markDocumentEventsPublishedOrFailed(Collection, Collection) ends this transaction on the provided events. This transaction may end for other reasons, such as a distributed lock failure or timeout, which would cause subsequent calls to retrieve these same events again. To determine if a transaction is still active around this, before documents are published, ensureTransactionActive(DocumentEvent) should be called in order to determine if that event's transaction is lost or has otherwise ended prematurely.

Throws:

Exception

ensureTransactionActive

void ensureTransactionActive(DocumentEvent event)
                      throws Exception

Throws a descriptive exception if the provided event is not in an active transaction, or if the current state of its transaction is unknown.

Transactions are started when an event is retrieved from retrievePriorityDocumentEventsUpTo(int).

Transactions can end before published or failure confirmation for a variety of reasons, such as network failure or timeout, depending on the implementation.

Throws:

Exception - if the event does not have an active transaction, and therefore is available for processing from retrievePriorityDocumentEventsUpTo(int).

markDocumentEventsPublishedOrFailed

void markDocumentEventsPublishedOrFailed(Collection<? extends DocumentEvent> events,
                                         Collection<FailedDocumentEvent> failures)
                                  throws Exception

Ends the active transactions with the provided events, providing failure information if any were not able to be published.

Events marked as published should not be retrievable ever again. Implementations can decided if failed events should be retrievable again or not.

Throws:

Exception