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: All downstream synchronous replications have acknowledged that the message(s) have been delivered to their respective SOW Topic(s). 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 message

Description

AMPS returns a publish message to a client when a new message is published to AMPS that matches one of the subscriptions requested by the client. There are two ways that AMPS can generate publish messages:

• Single-origin messages. For subscriptions to topics where AMPS can identify a single source for a publish message, AMPS provides information from that publish message to the subscriber. This applies to subscriptions to unpersisted topics, SOW topics, and conflated topic replicas. This does not include subscriptions to views (or conflated topics based on views), since views provide the ability to join multiple topics and aggregate over multiple messages. For conflated topic replicas, the header information provided is the information provided with the message published to the subscriber. For messages produced by delta publish, AMPS will use the information provided on the delta publish except as noted in the table below.
• Synthetic messages. In some cases, AMPS must provide a message that is constructed by the server. This happens for views, and for status messages from AMPS.

AMPS provides different values in the header fields depending on the origin of the publish message. For synthetic messages, AMPS does not provide information on the origin of the message, since there may be multiple sources of the message or, in the case of status messages, no external source. Likewise, AMPS does not provide a CorrelationId, since that header is set by the publisher for a specific message.

Header Fields

Table 7.1 contains the header fields returned in a publish message.

Field	Description
Command	Type of message. Always publish, as encoded by the protocol.
Topic	The topic the message was published to.
CorrelationId	A publisher-provided string that is passed, verbatim, to subscribers. If this header is not present, or the message is a synthetic message as described above, subscribers receive no value for the CorrelationId. The contents of this header must consist of characters that are legal in Base64 encoding. For delta publishes, AMPS uses the CorrelationId of the delta publish if one is present. If no CorrelationId is present on the publish, AMPS uses the CorrelationId of the existing message, if one is present. If there is no CorrelationId on the publish, and there is no CorrelationId for the existing message, AMPS does not provide a CorrelationId.
UserId	The UserId of the client that published the message. An authentication module may choose whether to allow subscribers to receive this information.
SubIds	The set of subscription IDs that produced this message. When a message matches multiple subscriptions, AMPS may produce a list of subscription IDs for all matching subscriptions. This header is provided by AMPS. The AMPS Clients process this list and provide a single SubscriptionID for each message provided to message handlers.
Bookmark	The bookmark assigned to this message, if the message was persisted to a transaction log.
TransmissionTime	An ISO-8601 datetime that notes the time the message was processed by AMPS. This header is included if the client requested transmission time for the subscription.
LeasePeriod	For messages received from a queue, the ISO-8601 datetime that indicates when the lease expires.
SowKey	If the message was from a topic that uses a SOW, the message includes the SowKey that AMPS uses to uniquely identify the message within the SOW.

Table 7.1: Header fields returned in a publish response