3. Publishing to AMPS¶
This section describes commands used to send data to AMPS.
Notice that, for topics in the state of the world, AMPS treats these commands as inserting a new message if one does not already exist, and updating the existing message if a message already exists.
For topics in the transaction log,
each publish or delta_publish will
store the current message in the
transaction log, just as it
would be delivered to subscribers.
delta_publish¶
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¶
The following table
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. |
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.
The following table
contains the acknowledgment messages that can be returned by a delta_publish.
In general, 60East recommends only requesting persisted acknowledgments
for delta_publish commands, since these acknowledgments 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
1. All downstream synchronous replications have acknowledged that the message(s) have been delivered to their respective SOW Topic(s). 2. When the publish message has been sent to all available downstream asynchronous replications. 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. |
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¶
The publish command is the primary way to insert messages into the
AMPS processing stream. A publish command received by AMPS will be
forwarded to other connected clients with matching subscriptions.
Depending on the server configuration, a publish command may
also be used to update the State of the World, written to the
transaction log, replicated to other instances, and so on.
In AMPS, the publisher is only responsible for delivering the message to AMPS reliably. The AMPS server configuration manages routing the message to subscribers, determining if the message should be persisted, updating any state that the message affects, and so on.
Header Fields¶
The following table
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. |
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.
The following table
contains the AckType messages which can be returned by a publish.
In general, 60East recommends only requesting persisted acknowledgments
for publish commands, since these acknowledgments 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 acknowledgment includes the steps
acknowledged by the |
persisted |
When AMPS returns an acknowledgment message of
1. All downstream synchronous replications have acknowledged that the message(s) have been delivered to their respective SOW Topic(s). 2. When the If no replication is configured for this topic, this acknowledgment applies only to local persistence. If no persistence is configured for this topic, this acknowledgment 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 persisted. |
received |
The publish message has been received. |
stats |
Not supported at this time. |
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.