Cookbook: Subscribe

This section presents common recipes for subscribing to a topic in AMPS using the Command or Message interfaces. This section provides information on how to configure the request to AMPS. You can adapt this information to your application and the specific interface you are using.

Command: subscribe

Basic Subscription

In its simplest form, a subscription needs only the topic to subscribe to.

Header	Comment
Topic (required)	Sets the topic to subscribe to. All messages from the topic will be delivered on this subscription. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.

Subscription with Options

In its simplest form, a subscription needs only the topic to subscribe to. To add options to the subscription, set the Options header on the Command.

Header	Comment
Topic (required)	Sets the topic to subscribe to. All messages from the topic will be delivered on this subscription. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Options	A comma-delimited set of options for this command. See the subscribe section for a description of supported options.

Subscription with Select List

In its simplest form, a subscription needs only the topic to subscribe to. To use a select list with the subscription, set the Options header on the Command to the select list specifier.

Header	Comment
Topic (required)	Sets the topic to subscribe to. All messages from the topic will be delivered on this subscription. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Options	A comma-delimited set of options for this command. See the subscribe section for a description of supported options. For example, to remove all fields except for /id and /ticker, you might use an option string of select=[-/,+/id,+/ticker].

Subscription with Content Filter

To provide a content filter on a subscription, set the Filter property on the command. The AMPS User Guide provides details on the filter syntax.

Header	Comment
Topic (required)	Sets the topic to subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Filter	Sets the content filter to be applied to the subscription. Only messages that match the content filter will be provided to the subscription.

Conflated Subscription to a SOW Topic

To request conflation on a subscription, set the Options property on the command to specify the conflation interval. When the topic has a SOW (including a view or a conflated topic), there is no need to provide a conflation_key.

Header	Comment
Topic (required)	Sets the topic to subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Options	A comma-separated list of options for the command. Set the conflation interval in the options. For example, to set a conflation interval of 250 milliseconds, provide the following option: conflation=250ms. To set the conflation interval to 1 minute, provide an option of: conflation=1m .

Conflated Subscription to a Topic with No SOW

To request conflation on a subscription, set the Options property on the command to specify the conflation interval. When the topic does not have a SOW, you must provide a conflation_key.

Header	Comment
Topic (required)	Sets the topic to subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Options	A comma-separated list of options for the command. Set the conflation interval and the fields that determine a unique message in the options. For example, to set a conflation interval of 250 milliseconds for messages that have the same value for /id, provide the following option: conflation=250ms,conflation_key= [/id]. To set the conflation interval to 1 minute for messages that are the same, as determined by a combination of /customerId and /issueNumber, provide an option of: conflation=1m, conflation_key=[/customerId,/issueNumber].

Bookmark Subscription

To create a bookmark subscription, set the Bookmark property on the command. The value of this property can be either a specific bookmark, a timestamp, or one of the client-provided constants. The AMPS User Guide provides details on creating timestamps. Notice that the MOST_RECENT constant tells the AMPS client to find the appropriate message in the client bookmark store and begin the subscription at that point. In this case, the client sends that bookmark value to AMPS. The Bookmark option is only supported for topics that are recorded in an AMPS transaction log.

Header	Comment
Topic (required)	Sets the topic to subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Bookmark	Sets the point in the transaction log at which the subscription will begin. The bookmark provided can be a specific AMPS bookmark, a timestamp, or one of the client-provided constants. AMPS also accepts a comma-delimited list of bookmarks. In this case, AMPS begins the subscription from whichever of the bookmarks is earliest in the transaction log.

Rate Controlled Bookmark Subscription

To create a bookmark subscription, set the Bookmark property on the command. The value of this property can be either a specific bookmark, a timestamp, or one of the client-provided constants. The AMPS User Guide provides details on creating timestamps. Notice that the MOST_RECENT constant tells the AMPS client to find the appropriate message in the client bookmark store and begin the subscription at that point. In this case, the client sends that bookmark value to AMPS. The Bookmark option is only supported for topics that are recorded in an AMPS transaction log.

To manage the message delivery rate to a bookmark subscription, set the rate option specifying the rate at which to replay messages.

Header	Comment
Topic (required)	Sets the topic to subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Bookmark	Sets the point in the transaction log at which the subscription will begin. The bookmark provided can be a specific AMPS bookmark, a timestamp, or one of the client-provided constants. AMPS also accepts a comma-delimited list of bookmarks. In this case, AMPS begins the subscription from whichever of the bookmarks is earliest in the transaction log.
Options	A comma-separated list of options for the command. To control the rate at which AMPS delivers messages, the options for the command must include a rate specifier. For example, to specify a limit of 750 messages per second, include rate=750 in the options string.

Rate Controlled Bookmark Subscription with Maximum Gap

To create a bookmark subscription, set the Bookmark property on the command. The value of this property can be either a specific bookmark, a timestamp, or one of the client-provided constants. The AMPS User Guide provides details on creating timestamps. Notice that the MOST_RECENT constant tells the AMPS client to find the appropriate message in the client bookmark store and begin the subscription at that point. In this case, the client sends that bookmark value to AMPS. The Bookmark option is only supported for topics that are recorded in an AMPS transaction log.

The rate option specifies the rate at which to replay messages, while the rate_max_gap option specifies the maximum amount of time for AMPS to allow between messages.

Header	Comment
Topic (required)	Sets the topic to subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Bookmark	Sets the point in the transaction log at which the subscription will begin. The bookmark provided can be a specific AMPS bookmark, a timestamp, or one of the client-provided constants. AMPS also accepts a comma-delimited list of bookmarks. In this case, AMPS begins the subscription from whichever of the bookmarks is earliest in the transaction log.
Options	A comma-separated list of options for the command. To control the rate at which AMPS delivers messages, the options for the command must include a rate specifier. For example, to specify that AMPS replays no faster than twice the original rate, include 2X in the options string. To specify that AMPS will go no more than 3 seconds without producing a message, regardless of the original replay timing, use a rate_max_gap of 3s. To provide the options described above, you would use the options string: rate=2X,rate_max_gap=3s.

Bookmark Subscription with Completed Acknowledgment

To create a bookmark subscription, set the Bookmark property on the command. The value of this property can be either a specific bookmark, a timestamp, or one of the client-provided constants. The AMPS User Guide provides details on creating timestamps. Notice that the MOST_RECENT constant tells the AMPS client to find the appropriate message in the client bookmark store and begin the subscription at that point. In this case, the client sends that bookmark value to AMPS. The Bookmark option is only supported for topics that are recorded in an AMPS transaction log.

To receive acknowledgment messages to a bookmark subscription, set the AckType on the command specifying the type of acknowledgments to receive. In this case, be sure to include the completed type.

Header	Comment
Topic (required)	Sets the topic to subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Bookmark	Sets the point in the transaction log at which the subscription will begin. The bookmark provided can be a specific AMPS bookmark, a timestamp, or one of the client-provided constants. AMPS also accepts a comma-delimited list of bookmarks. In this case, AMPS begins the subscription from whichever of the bookmarks is earliest in the transaction log.
AckType	Sets the acknowledgment messages that AMPS returns. The AMPS clients typically request a processed acknowledgment for a subscription to verify whether the subscription succeeded. To receive a completed acknowledgment, which indicates the point at which replay is complete for the subscription, include completed in the set of acknowledgments requested. AMPS will return a message with a command type of ack and an ack type of completed at that point in the subscription.

Bookmark Subscription with Content Filter

To create a bookmark subscription, set the Bookmark property on the command. The property can be either a specific bookmark, a timestamp, or one of the client-provided constants. The AMPS User Guide provides details on creating timestamps. Notice that the MOST_RECENT constant tells the AMPS client to find the appropriate message in the client bookmark store and begin the subscription at that point. In this case, the client sends that bookmark value to AMPS.

To add a filter to a bookmark subscription, set the Filter property on the command. The AMPS User Guide provides details on the filter syntax.

Header	Comment
Topic (required)	Sets the topic to subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Bookmark	Sets the point in the transaction log at which the subscription will begin. The bookmark provided can be a specific AMPS bookmark, a timestamp, or one of the client-provided constants. AMPS also accepts a comma-delimited list of bookmarks. In this case, AMPS begins the subscription from whichever of the bookmarks is earliest in the transaction log.
Filter	Sets the content filter to be applied to the subscription. Only messages that match the content filter will be provided to the subscription.

Pausing a Bookmark Subscription

To pause a bookmark subscription, you must provide the subscription ID and the pause option on a subscribe command.

Header	Comment
Topic (required)	Sets the topic to subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
SubId (required)	A comma-delimited list of subscription IDs to pause.
Options (required)	A comma-delimited list of options for the command. To pause a subscription, the options must include pause.

Resuming a Bookmark Subscription

To resume a bookmark subscription, you must provide the subscription ID and the resume option on a subscribe command.

Header	Comment
Topic (required)	Sets the topic to subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
SubId (required)	A comma-delimited list of subscription IDs to resume.
Options	A comma-delimited list of options for the command. To resume a subscription, the options must include resume.

Replacing the Filter on a Subscription

To replace the content filter on a subscription, provide the SubId of the subscription to be replaced, add the replace option, and set the Filter property on the command with the new filter. The AMPS User Guide provides details on the filter syntax.

Header	Comment
Topic (required)	Sets the topic to subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
SubId (required)	The identifier for the subscription to update. The SubId is the CommandId for the original subscribe command.
Options	A comma-separated list of options. To replace the filter on a subscription, include replace in the list of options.
Filter	Sets the content filter to be applied to the subscription. Only messages that match the content filter will be provided to the subscription.

Subscribing to a Queue and Requesting a max_backlog

To subscribe to a queue and request a max_backlog greater than 1, use the Options field of the subscribe command to set the requested max_backlog.

Header	Comment
Topic (required)	Sets the topic to subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Options	A comma-separated list of options. To request a value for the max_backlog, pass the value in the options as follows: max_backlog= NN. For example, to request a max_backlog of 7, your application would pass the following option: max_backlog=7.