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 |
|---|---|
| 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 (opts) header on the Command.
| Header | Comment |
|---|---|
| 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. |
opts | 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 (opts) header on the Command to the select list specifier.
| Header | Comment |
|---|---|
| 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. |
opts | 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 (opts) 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 |
|---|---|
| Sets the topic to subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics. |
opts | 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 (opts) property on the command to specify the conflation interval. When the topic is not in the State of the World, you must provide a conflation_key.
| Header | Comment |
|---|---|
| Sets the topic to subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics. |
opts | 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 |
|---|---|
| Sets the topic to subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics. |
Bbokmark | 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 |
|---|---|
| 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. |
opts | 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 |
|---|---|
| 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. |
opts | 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 ack_type on the command specifying the type of acknowledgments to receive. In this case, be sure to include the completed type.
| Header | Comment |
|---|---|
| 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. |
ack_type | 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 |
|---|---|
| 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. |
Entering a Bookmark Subscription In the Paused State
To pause a bookmark subscription, you must provide the subscription ID and the pause option on a subscribe command.
This option is used to enter a number of subscriptions at the same point in the transaction log. The subscriptions can then be resumed together and will progress through the transaction log together.
| Header | Comment |
|---|---|
| Sets the topic to subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics. |
| The subscription ID to enter in a paused state. |
| A comma-delimited list of options for the command. To enter a paused subscription, the options must include pause. |
Starting One or More Paused Bookmark Subscriptions
Starting bookmark subscriptions that are currently paused requires you to provide the subscription ID and a resume option on a subscribe command.
| Header | Comment |
|---|---|
| Sets the topic to subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics. |
| A comma-delimited list of subscription IDs to start. |
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 sub_id 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 |
|---|---|
| Sets the topic to subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics. |
| The identifier for the subscription to update. The sub_id is the sub_id of the original subscribe command (or the cmd_id if a sub_id was not provided). |
opts | 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 after the filter is replaced. |
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 (opts) field of the subscribe command to set the requested max_backlog.
| Header | Comment |
|---|---|
| Sets the topic to subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics. |
opts | 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. |