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 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 this instance of AMPS. The header is included if the client requested a timestamp 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

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.