Provisioning
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.
Journal
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.
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 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:
| Property | Description |
|---|---|
advanceCursor | This 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. |
consumeCursor | This 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. |
consumeFilter | This is a boolean expression that determines if a journal entry is applicable to be consumed by this peer. |
consumeStartTime | The time that get_entry() next_for_consumer began. This property will only exist if cursorBeingConsumed property exists. |
currentCursor | This is the current cursor into the journal. |
description | Description of provisioning peer. |
lastContactTime | The last time the peer was successfully contacted. |
peerId | Id 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.