Adaptive Framework 0.9.0


When Adaptive Objects are committed to an adaptor store, a record of the event, may optionally be recorded by a Journal Adaptor in order to maintain a chronological ordering of events, which may be used to notify external clients. Provisioning describes the process by which Adaptive Objects may be synchronized between an adaptor and one or more clients, or Provisioning Peers.


Any adaptor may be configured with an optional journalAdaptorId, which references an adaptor that supports the Journaling of object events. When an object is modified through the adaptor interface methods (add, delete, modify, replace, update), a Journal Entry of the event is created and sent to the provided Journal Adaptor. This Journal Entry contains information about the event, including the Request and Source information about the entry. The Journal Entry is added to an event queue, and each entry is referenced by a Journal Cursor. Cursors are used to uniquely identify an Journal Entry and entries may be fetched from the queue in chronological order, using these chain of cursors. The cursors may be used by both the Provisioning Peer and Journal Adaptor to replay a series of events that have occurred from any range within the Journal.

A Journal Entry is produced for the Journal Adaptor, by a single Provisioning Peer. The Journal Entry may then be consumed by one or more Provisioning Peers. The Journal Interface routines provide all of the necessary functions to provision in and out of the Journal. For more details on the Journal interface functions, see Journal.

A Producer is anything that produces an event that will be journaled. In the following diagram, we illustrate how a Provisioning Peer may produce an event simply by calling the add_object() routine to an adaptor. The adaptor, in turn, is configured with a Journal Adaptor, which knows to take the object and add it to its queue of Journal Entries.

Provisioning Producer creates an object to be journaled.
Provisioning Producer creates an object to be journaled.

By contrast, an Consumer is a client that consumes events from the Journal. These clients interact directly with the Journal Adaptor itself by calling Journal routines that can fetch the first event, or an event after a positional cursor. When consumed, the event is removed from the Journal through a request to mark it consumed.

Provisioning Consumer consumes an object from the Journal.
Provisioning Consumer consumes an object from the Journal.

Provisioning Peers

A Provisioning Peer is a client, external to the Journal, which may produce and/or consume Journal Entries. Provisioning Peers are uniquely identified by a peerId, which associates a peer with the following Provisioning Peer object properties:

advanceCursorThis property set by get_entry() option advance_cursor_for_consumer. If set, get_entry() option next_for_consumer will removed it and use it as the cursor to begin looking for the next applicable entry. The intent of cursorNext is to be set by a background process/thread that examines journal entries from the cursorNext/cursorCurrent forward looking for a entry that passes the consumer filter. Once cursorNext is used by get_entry() next_for_consumer, the property is removed.
consumeCursorThis is the current cursor being consumed. This property only exists between a get_entry() option next_for_consumer and the corresponding mark_entry_consumed(). If this property exists, it should have exactly the same value as property cursorCurrent. Anything else is and error.
consumeFilterThis is a boolean expression that determines if a journal entry is applicable to be consumed by this peer.
consumeStartTimeThe time that get_entry() next_for_consumer began. This property will only exist if cursorBeingConsumed property exists.
currentCursorThis is the current cursor into the journal.
descriptionDescription of provisioning peer.
lastContactTimeThe last time the peer was successfully contacted.
peerIdId used to identify this peer. This may also be referred to as the consumerId or producerId, depending on the perspective.

When Provisioning Peers call journal functions, the peerId that is specified by the peering client, should be authenticated and authorized in order to deliver the appropriate data to the Provisioning Peer. While anyone can produce events to be journaled, or consume events from a Journal, the concept of a Provisioning Peer allows you to pre-define and centrally-manage producers and consumers in order to support filters, maintain cursors, and additional information about the peer. Additionally, when a Provisioning Peer produces an event, the peerId should be provided in order to avoid event loopback situations, where a consumer could consume the very event it produced.