7. Content Messages

AMPS provides three types of message that contain message content

  • publish messages return data from a topic as it is published, in order, whether the data is being published live, or is the result of a replay
  • sow messages return data from a SOW query. These messages return the state of messages that are current as of the time for the query. By default, the messages are returned without regard to the order in which the messages were published. A query can specify the order of the returned messages based on the data within the message by including the OrderBy header on the SOW query.
  • oof messages indicate that a content message no longer matches a subscription. These messages are sent to a client in order.

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.

sow message

Description

The sow message returns a record from the SOW. For more information, see the State of the World and SOW Queries chapters in the AMPS User Guide

Header Fields

Field Description
Command Type of message. Always sow, as encoded by the protocol.
Topic
The topic from which the records were produced.
SowKey An AMPS-created identifier for this message.
BatchSize The number of records returned in a single sow batch.
Timestamp The time at which AMPS generated this message.
QueryId The QueryId of the query that produced this message.
MsgLen The length of the first SOW message in the data portion of this message.

Table 7.2: Header fields supported by sow

Data

The sow message contains data. The data for the message consists of up to BatchSize messages, formatted as expected by the protocol. Each message contains its own header, with the following fields:

Field Description
SowKey An AMPS-created identifier for this message.
CorrelationId A user-provided string that will be passed, verbatim, to subscribers. If this header is not present on the SOW record, subscribers receive no value for the CorrelationId. The contents of this header must consist of characters that are legal in Base64 encoding.
MsgLen The length of the next SOW message in the data portion of this message.

Table 7.3: Header fields for messages in sow data

oof message

Description

The oof message indicates that a previously-received message is no longer in focus. For more information, see the State of the World and SOW Queries chapters in the AMPS User Guide

Header Fields

Field Description
Command Type of message. Always oof, as encoded by the protocol.
Topic The topic which contained the message that has gone out of focus.
SowKey An AMPS-created identifier for the message that has gone out of focus.
Reason The reason the message has gone out of focus. Valid reasons include deleted, expired, filter, and entitlement.
SubIds The Subscription Ids of the subscriptions that produced this message. The AMPS clients will provide this message to the handler registered for each of the subscriptions specified.
CorrelationId A user-provided string that will be passed, verbatim, to subscribers. If this header is not present on the SOW record that was deleted, subscribers receive no value for the CorrelationId. The contents of this header must consist of characters that are legal in Base64 encoding.

Table 7.4: Header fields provided in oof

Data

The oof message contains the updated message that caused the message to go out of focus, except if the reason is entitlement.