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.

Acknowledgment Description
none No ack message is returned. This is the default behavior.
completed Not supported at this time.
persisted

When AMPS returns an acknowledgment message of persisted, it guarantees that:

  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.
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.
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.

Acknowledgment Description
none No ack message is returned. This is the default behavior.
completed Not supported at this time.
persisted

When AMPS returns an acknowledgment message of persisted, it guarantees that:

  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.
processed AMPS has processed the publish message.
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.