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