3. Publishing to AMPS¶
delta_publish¶
Description¶
The delta_publish
command is a way of publishing an incremental
update to a record. If a client uses delta_publish
to publish an
update, AMPS first extracts the key fields from the record and does a
look up for the record in the SOW. AMPS will then apply the update to
the SOW record overwriting any field that has a newer value in the
update and appending to the record any new fields that were not
previously in the SOW record.
If delta_publish
is used on a record that does not currently exist
in the SOW or if it is used on a topic that does not have a SOW-topic
store defined, then delta_publish
will behave like a standard
publish
command.
A delta_publish
is transparent to other clients and the merged
record will be forwarded to matching subscriptions.
Header Fields¶
Table 3.1
contains the header fields available to a delta_publish
command.
Field | Description |
---|---|
Command
|
Command to be executed. Value: delta_publish |
Topic
|
The SOW topic to publish the message to. |
AckType |
Acknowledgment type for the given command. Value
is a comma separated list of one or more of the
following: none , received ,
processed , completed or stats . |
CommandId |
If specified with an AMPS command which requests
an acknowledgment message, all requested
acknowledgment messages will contain the
CommandId in the ack response header. |
Expiration |
An interval used to define the lifetime of a
delta_message message. Time period is in
seconds. |
Sequence |
A monotonically increasing number used to identify published messages in a high availability environment. |
CorrelationId |
A user-provided string that will be passed,
verbatim, to subscribers. If this header is not
present, subscribers receive no value for the
CorrelationId . The contents of this header
must consist of characters that are legal in
Base64 encoding. |
SowKey |
For SOW topics that use an explicit key, the SOW key to use for the message. The contents of this header must consist of characters that are legal in Base64 encoding. |
Table 3.1: Header fields used in a delta_publish
Returns¶
For a delta_publish
message, AMPS will send acknowledgment messages
for the following AckType
fields: received
, processed
and
persisted
along with a populated Status
header field describing
the acknowledgment.
Table 3.2
contains the acknowledgment messages that can be returned by a delta_publish
.
In general, 60East recommends only requesting persisted
acknowledgements
for delta_publish
commands, since these acknoweldgements can be conflated
when commands succeed.
Acknowledgment | Description |
---|---|
none |
No ack message is returned. This is the
default behavior. |
completed |
AMPS has processed the message and, if necessary enqueued the message for persistence and replication. This acknowledgement includes the steps
acknowledged by the |
persisted |
When AMPS returns an acknowledgment message of
If no replication is configured for this topic, this acknowledgement applies only to local persistence. If no persistence is configured for this topic, this acknowledgement is still provided when requested. |
processed |
AMPS has processed the message(s) to be published to the SOW. Any errors which occur in the message will be returned to the client in this acknowledgment message. This includes processing entitlement checks, and parsing the message but does not guarantee that the message has been replicated or persisted. |
received |
The delta_publish message has been received. |
stats |
Not supported at this time. |
Table 3.2: Acknowledgment messages supported by delta_publish
Errors¶
Any errors that occur during this command will be returned in the status
of a processed
acknowledgment message and logged to the log file.
Regardless of success or failure, the processed
acknowledgment
message will be returned only if requested by specifying processed
in the AckType
field.
publish¶
Description¶
The publish
command is the primary way to inject messages into the
AMPS processing stream. A publish
command received by AMPS will be
forwarded to other connected clients with matching subscriptions.
Header Fields¶
Table 3.3
contains the header fields available to a publish
command.
Field | Description |
---|---|
Command
|
Command to be executed. Value: publish . |
Topic
|
The topic to publish the message to. |
AckType |
Acknowledgment type for the given command. Value
is a comma separated list of one of more of the
following: none , received , persisted
or processed . |
CommandId |
If specified with an AMPS command requesting an
acknowledgment message in response to the
publish command, all requested
acknowledgment messages will contain the
CommandId in the response header. |
Expiration |
An interval in seconds, used to define the
lifetime of a publish message. |
SequenceId |
A monotonically increasing identifier used in high availability configurations to determine message uniqueness across replicas. |
CorrelationId |
A user-provided string that will be passed,
verbatim, to subscribers. If this header is not
present, subscribers receive no value for the
CorrelationId . The contents of this header
must consist of characters that are legal in
Base64 encoding. |
SowKey |
For SOW topics that use an explicit key, the SOW key to use for the message. The contents of this header must consist of characters that are legal in Base64 encoding. |
Table 3.3: Header fields supported by publish
Returns¶
A client which issues a publish
can request a processed
acknowledgment message; however this is not recommended as there is a
significant performance overhead associated with this.
Table 3.4
contains the AckType
messages which can be returned by a publish
.
In general, 60East recommends only requesting persisted
acknowledgements
for publish
commands, since these acknowledgements can be conflated
when commands succeed.
Acknowledgment | Description |
---|---|
none |
No ack message is returned. This is the
default behavior. |
completed |
AMPS has processed the message and, if necessary, enqueued the message for persistence and replication. This acknowledgement includes the steps
acknowledged by the |
persisted |
When AMPS returns an acknowledgment message of
If no replication is configured for this topic, this acknowledgement applies only to local persistence. If no persistence is configured for this topic, this acknowledgement is still provided when requested. |
processed |
AMPS has processed the This includes processing entitlement checks, and parsing the message if parsing is necessary, but does not guarantee that the message has been replicated or presisted. |
received |
The publish message has been received. |
stats |
Not supported at this time. |
Table 3.4: Acknowledgment messages supported by publish
Errors¶
Any errors that occur during this command will be returned in the status
of a processed
acknowledgment and logged to the log file. Regardless
of success or failure, the processed
acknowledgment will be returned
only if the request includes the processed
in the AckType
field.