delta_subscribe
The delta_subscribe command is like the subscribe command except that subscriptions placed through delta_subscribe will receive only messages that have changed between the SOW record and the new update.
If delta_subscribe is used on a topic which does not have a SOW store defined, then delta_subscribe behaves like a subscribe command.
Header Fields
The following table contains the header fields available to a delta_subscribe command.
Field
Description
Command
Command to be executed.
Value: delta_publish
Topic
Topic with which to place a subscription.
AckType
Acknowledgment type for the delta_subscribe 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 requesting an acknowledgment message, all requested acknowledgment messages will contain the CommandId in the acknowledgment response header.
DataOnly
A Boolean (true or false) used to determine the type of data sent to the subscriber.
A value of true will, for example, not include a SOAP envelope.
Filter
String which is used as a content filter expression.
When using XML, the filter must be wrapped in a CDATA.
Options
A comma separated list of flags available to the subscribe command.
SendEmpty
Boolean (true or false) value used to determine whether empty messages which are published will be forwarded to matching subscriptions.
Default: true
SendSubscriptionIds
Boolean (true or false) subscription identifiers will not be sent for all matched messages if set to false.
SubscriptionId
The subscription ID for this command. When provided with a new subscription, this is the identifier that AMPS will use for the subscription.
When provided with the replace option, this field specifies the subscription to replace.
When provided with a pause or resume option, this field specifies the subscriptions to pause or resume.
For a new subscription, the AMPS clients will generate a subscription ID if one is not provided.
Bookmark
A bookmark specifying the point in the transaction log at which to start the subscription.
If the topic provided is not recorded in a transaction log, AMPS enters the subscription without replaying messages.
You can provide a single bookmark, or a comma-delimited list of bookmarks.
When a list is provided, AMPS starts the subscription at the earliest bookmark in the list.
Options Field
The following table contains a list of the Options available and their definitions when used in the AMPS sow_and_delta_subscribe command.
Option
Description
none
This is the default Options type.
bookmark
Specifies that the subscription should return bookmarks, if available, on each publish message. Bookmarks are only available if the topic that is subscribed to is recorded in the transaction log.
Notice that this option does not set the starting point for a bookmark subscription: use the Bookmark header for that purpose.
This option is not required to receive bookmarks for a bookmark subscription. Those subscriptions always include bookmarks on each publish message.
conflation=n
Specifies whether to conflate this subscription.
The value provided can be a time interval, auto, or none.
When present and set to a value other than none, enables conflation for the subscription.
Can also be set to auto, which requests that AMPS attempt to determine an appropriate conflation interval based on client consumption.
Recognizes the same time specifiers used in the AMPS configuration file (for example, 100ms or 1s or 1m).
Default: none
conflation_key=[key]
When conflation is enabled, specifies the fields to use to determine message uniqueness.
The format of this option is a comma-delimited list of XPath identifiers within brackets.
For example, to conflate based on the value of the /tickerId and /customerId within a message, the value of this option would be:
[/tickerId,/customerId]
Defaults to the SOW key fields for SOW topics.
No default for non-SOW topics. This option is required for non-SOW topics.
This option is not valid with the oof option unless the keys provided are identical to the keys for the topic.
live
Tells AMPS to send messages to subscribing clients before they have been persisted to the transaction log.
This option has no effect on subscriptions that are not replays from the transaction log (that is, this option only applies to bookmark subscriptions).
max_backlog=n
When subscribing to a queue, the number of unacknowledged messages the client is willing to accept at a time.
AMPS will not exceed this number, but may choose a smaller number depending on the queue configuration.
no_empties
Tells AMPS not to send empty publish messages to matching subscriptions.
This can be useful for suppressing messages where no fields have changed.
no_sowkey
Tells AMPS not to send the AMPS-generated SowKey for messages.
non_regex_topic
Specifies that the topic name should be a literal match, even if the topic name contains regular expression characters.
oof
Send an OOF message for records which have fallen out of focus from the original subscription.
When focus tracking is enabled, AMPS will also deliver the full message to a subscription when a previously out-of-focus message comes into focus.
pause
Pause a bookmark subscription.
This option is only valid for bookmark subscriptions that do not use the live option. When this option is present, AMPS pauses the subscription or subscriptions provided in the SubId of the command.
rate=n
Set the maximum message delivery rate for a bookmark subscription.
This option is only valid for bookmark subscriptions that do not use the live option.
The rate can be specified as either the number of messages per second (for example, 1000), the number of bytes per second (for example, 100KB), or a multiple of the original replay rate (for example, 1.5X).
replace
Replace the subscription associated with CmdId with another subscription. When provided as part of sow_and_subscribe, AMPS runs a SOW query for the new subscription.
resume
Resume a bookmark subscription. This option is only valid for bookmark subscriptions that do not use the live option.
When this option is present, AMPS resumes the subscription or subscriptions provided in the SubId of the command.
send_keys
AMPS will send the SOW keys fields back with messages from the SOW.
Notice that without this option, messages will never contain these fields (since, by definition, they do not change from update to update).
timestamp
AMPS will include a header with the time at which this instance of AMPS processed the incoming publish command for this message.
Returns
A delta_subscribe command returns the following command types:
Command
Description
publish
A message published to AMPS.
oof
Returned when the oof option is requested on the command, the subscription is to a topic in the SOW, and the subscription is not a bookmark subscribe.
ack
Acknowledgments requested, as described in the following section.
For a delta_subscribe message, AMPS will send acknowledgment messages for the following AckType fields: received, processed, persisted and stats along with a populated Status header field describing the acknowledgment.
The following table contains the AckType messages which can be returned by a delta_subscribe.
Acknowledgment
Description
none
No ack is returned.
This is the default behavior.
completed
When a bookmark is present on the subscribe request and this acknowledgment is requested, AMPS sends a completed acknowledgment message to indicate that bookmark replay is complete. Further messages on this subscription are from new publishes.
persisted
When a bookmark is present and this acknowledgment is requested, AMPS periodically sends a persisted acknowledgment message to indicate the most recent bookmark in the server's transaction log.
processed
AMPS has compiled the filters for the delta_subscribe message(s).
received
The delta_subscribe message has been received.
stats
Returns an acknowledgment message with Matches, TopicMatches and RecordsReturned.
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 requested by including processed in the AckType field of the delta_subscribe message header.
Last updated