Proxy to access session information and output message queues.
- Source:
Extends
Methods
begin() → {sessionBeginType}
- Source:
Starts a persistent session associated with the current logical session.
begin() creates a fresh nonce to tie together all the interactions
within a persistent session. This solves the issue of delayed
messages in the network from previous persistent sessions
interfering with the current session.
begin() returns the last memento if the previous session was
not properly ended, and this allows a stateless client to
provide exactly-once delivery guarantees for requests in the presence
of failures.
The type of caf.sessionBegin is
{nonce: string, memento: jsonType=}
Returns:
A unique instance identifier for this persistent session, and an optional memento if the previous session was not properly ended.
- Type
- sessionBeginType
end(nonce) → {boolean}
- Source:
Ends a persistent session associated with the current logical session.
It deletes the memento associated with this logical session.
Parameters:
| Name | Type | Description |
|---|---|---|
nonce |
string | An identifier for this persistent session. |
Returns:
True if the session has ended. False if a different persistent session is in progress, and the nonce did not match.
- Type
- boolean
getAllSessionIds() → {Array.<string>}
- Source:
Gets the names of all the logical sessions of this CA.
Returns:
The names of all the logical sessions.
- Type
- Array.<string>
getSessionId() → {string}
- Source:
Gets the name of the current logical session.
Returns:
The name of the current logical session.
- Type
- string
limitQueue(maxMsgs, optSessionIdopt)
- Source:
Bounds the length of the output queue by discarding old messages.
Setting a limit ensures that the session will not be garbage collected.
If no session name is provided we use the current session.
By convention we reserve default as the name of the unnamed
logical session.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
maxMsgs |
number | Maximum number of messages in queue. |
|
optSessionId |
string |
<optional> |
An optional logical session name identifying the output queue. |
notify(argsArray, optSessionIdopt, customizerFopt)
- Source:
Queues a notification message.
If no session name is provided we use the current session.
It also supports regular expressions to queue the message in multiple queues.
The type of a notification, caf.notif is:
Array.<caf.json>
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
argsArray |
notificationType | An array with the arguments in the notification. |
|
optSessionId |
string | Object |
<optional> |
An optional logical session name identifying the output queue. It can also be a regular expression matching several queues. |
customizerF |
customizerType |
<optional> |
A function to personalize notifications based on the session id. |
outq(optSessionIdopt) → {Array.<notificationType>}
- Source:
Gets a read-only snapshot of the output notification queue.
If no session name is provided we use the current session.
By convention we reserve default as the name of an
unnamed logical session.
The type of an entry in the notification queue, caf.notif is:
Array.<caf.json>
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
optSessionId |
string |
<optional> |
An optional logical session name identifying the output queue. Defaults to the current session. |
Returns:
A frozen array with a snapshot of the output queue.
- Type
- Array.<notificationType>
remember(nonce, memento) → {boolean}
- Source:
Replaces a memento associated with this logical session.
Mementos can maintain client state across failures. This is important for clients that want to switch devices, or cannot rely on reliable local storage.
remember() is transactional with the processing of the
message, and when it fails by returning
false, your code should return an application error so that CAF
aborts the transaction.
Well-behaved clients should handle errors (or timeouts) by
starting a new persistent session. When they call begin() they
will learn the last successful action (and/or its own state)
before the failure.
Parameters:
| Name | Type | Description |
|---|---|---|
nonce |
string | Identifier for this persistent session. |
memento |
jsonType | Client state to be checkpointed. |
Returns:
True if the memento changed. False if the nonce did not match, and this CA must abort the processing of the message by returning an application error.
- Type
- boolean