10. AMPS Programming: Working with Commands

The AMPS clients provide named convenience methods for core AMPS functionality. These named methods work by creating messages and sending those messages to AMPS. All communication with AMPS occurs through messages.

You can use the Command object to customize the messages that AMPS sends. This is useful for more advanced scenarios where you need precise control over AMPS, in cases where you need to use an earlier version of the client to communicate with a more recent version of AMPS, or in cases where a named method is not available.

Understanding AMPS Messages

AMPS messages are represented in the client as AMPS.Message objects. The Message object is generic, and can represent any type of AMPS message, including both outgoing and incoming messages. This section includes a brief overview of elements common to AMPS command message. Full details of the commands to AMPS are provided in the AMPS Command Reference Guide.

All AMPS command messages contain the following elements:

  • Command. The command tells AMPS how to interpret the message. Without a command, AMPS will reject the message. Examples of commands include publish, subscribe, and sow.
  • CommandId. The command id, together with the name of the client, uniquely identifies a command to AMPS. The command ID can be used later on to refer to the command or the results of the command. For example, the command id for a subscribe message becomes the identifier for the subscription. The AMPS client provides a command id when the command requires one and no command id is set.

Most AMPS commands contain the following fields:

  • Topic. The topic that the command applies to, or a regular expression that identifies a set of topics that the command applies to. For most commands, the topic is required. Commands such as logon, start_timer, and stop_timer do not apply to a specific topic, and do not need this field.
  • Ack Type. The ack type tells AMPS how to acknowledge the message to the client. Each command has a default acknowledgment type that AMPS uses if no other type is provided.
  • Options. The options are a comma-separated list of options that affect how AMPS processes and responds to the message.

Beyond these fields, different commands include fields that are relevant to that particular command. For example, SOW queries, subscriptions, and some forms of SOW deletes accept the Filter field, which specifies the filter to apply to the subscription or query. As another example, publish commands accept the Expiration field, which sets the SOW expiration for the message.

For full details on the options available for each command and the acknowledgment messages returned by AMPS, see the AMPS Command Reference Guide.

Creating and Populating the Command

To create a command, you simply construct a command object of the appropriate type:

Command command = new Command("sow");

Once created, you set the appropriate fields on the message. For example, the following code creates a publish message, setting the command, topic, data to publish, and an expiration for the message:

Command command = new Command("sow");
command.setTopic("messages-sow");
command.setFilter("/id > 20");

When sent to AMPS, AMPS performs a SOW query from the topic messages-sow using the filter of /id > 20. The results of sending this message to AMPS are no different than using the form of the sow method that sets these fields.

Using execute

Once you’ve created a message, use the execute method to send the message to AMPS. The execute method returns a MessageStream that provides response messages. The executeAsync method sends the message to AMPS, waits for a processed acknowledgment, then returns. Messages are processed on the client background thread.

For example, the following snippet sends the command created above:

client.execute(command);

This returns a MessageStream identical to the MessageStream returned by the equivalent client.sow() method.

You can also provide a message handler to receive acknowledgments, statistics, or the results of subscriptions and SOW queries. The AMPS client maintains a background thread that receives and processes incoming messages. The call to executeAsync returns on the main thread as soon as AMPS acknowledges the command as having been processed, and messages are received and processed on the background thread:

import com.crankuptheamps.client.Message;
import com.crankuptheamps.client.MessageHandler;



class SimpleMessageHandler implements MessageHandler {


    // For sample purposes, just print the acknowledgment type and
    // reason.
    public void invoke(Message m) {
        System.out.println(m.getAckType() + " : " + m.getReason() );
    }
}

Then, to send the command and use the message handler, pass the command and the handler to executeAsync().

client.executeAsync(command, new SimpleMessageHandler());

While this message handler simply prints the ack type and reason for sample purposes, message handlers in production applications are typically designed with a specific purpose. For example, your message handler may fill a work queue, or check for success and throw an exception if the command failed.

Using execute to Publish

Notice that the publish command does not provide typically return results other than acknowledgment messages. To send a publish command, use the executeAsync() method with a null message handler:

client.executeAsync(publishCmd, null);

Since the code provides a null message handler, this code does not receive acknowledgments. To detect publish failures, set the FailedWriteHandler for the client. The publish methods of the AMPS Java client are implemented internally as calls to executeAsync with a null message handler.

Command Cookbook

This section is a quick guide to commonly used AMPS commands. For the full range of options on AMPS commands, see theAMPS Command Reference.

Publishing

This section presents common recipes for publishing 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.

The AMPS server does not return a stream of messages in response to a publish command.

important AMPS publish commands do not return a stream of messages. A publish command must be used with asynchronous message processing, and should typically pass an empty message handler.

Basic Publish

In its simplest form, a subscription needs only the topic to publish to and the data to publish. The AMPS client automatically constructs the necessary AMPS headers and formats the full publish command.

In many cases, a publisher only needs to use the basic publish command.

Header Comment
Topic

Sets the topic to publish to. The topic specified must be a literal topic name. Regular expression characters in the topic name are not interpreted.

Some topics in AMPS, such as views and conflated topics, cannot be published to directly. Instead, a publisher must publish to the underlying topics.

Data The data to publish to the topic. The AMPS client does not interpret, escape, or validate this data: the data is provided to the server verbatim.

Table 10.1: Basic Publish

Publish With CorrelationId

AMPS provides publishers with a header field that can be used to contain arbitrary data, the CorrelationId.

Header Comment
Topic

Sets the topic to publish to. The topic specified must be a literal topic name. Regular expression characters in the topic name are not interpreted.

Some topics in AMPS, such as views and conflated topics, cannot be published to directly. Instead, a publisher must publish to the underlying topics.

Data The data to publish to the topic. The AMPS client does not interpret, escape, or validate this data: the data is provided to the server verbatim.
CorrelationId

The CorrelationId to provide on the message. AMPS provides the CorrelationId to subscribers. The CorrelationId has no significance for AMPS.

The CorrelationId may only contain characters that are valid in base-64 encoding.

Table 10.2: Publish With CorrelationId

Publish With Explicit SOW Key

When publishing to a SOW topic that is configured to require an explicit SOW key, the publisher needs to set the SowKey header on the message.

Header Comment
Topic

Sets the topic to publish to. The topic specified must be a literal topic name. Regular expression characters in the topic name are not interpreted.

Some topics in AMPS, such as views and conflated topics, cannot be published to directly. Instead, a publisher must publish to the underlying topics.

Data The data to publish to the topic. The AMPS client does not interpret, escape, or validate this data: the data is provided to the server verbatim.
SowKey The SOW Key to use for this message. This header is only supported for publishes to a topic that requires an explicit SOW Key.

Table 10.3: Publish with Explicit SOW Key

Command Cookbook: Subscribing

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.

Basic Subscription

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

Header Comment
Topic
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.

Table 10.4: Basic Subscription

Basic 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
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 AMPS Command Reference for a description of supported options.

Table 10.4: Basic Subscription with Options

Basic 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
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 AMPS Command Reference 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]

Table 10.5: Basic Subscription with Select List

Content Filtered Subscription

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
Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
Filter Sets the content filter to be applied to the subscription. Only messages that match the content filter will be provided to the subscription.

Table 10.6: Content Filtered 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
Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
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

Table 10.7: Conflated Subscription to a SOW topic

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
Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
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 are the same as determined by a combination of /customerId and /issueNumber provide an option of:

conflation=1m,
conflation_key=[/customerId,/iss
ueNumber]

Table 10.8: Conflated Subscription to a SOW topic

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
Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
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.

Table 10.9: Bookmark Subscription

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.

Header Comment
Topic
Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
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.

Table 10.10: Bookmark Subscription

Bookmark Subscription With Completed Acknowledgement

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
Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
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.

Acknowledgements

Sets the acknowledgement messages that AMPS returns. The AMPS clients typically request a processed acknowledgement for a subscription to verify whether the subscription succeeded.

To receive a completed acknowledgement, which indicates the point at which replay is complete for the subscription, include completed in the set of acknowledgements requested. AMPS will return a message with a command type of ack and an ack type of completed at that point in the subscription.

Table 10.11: Bookmark Subscription With Completed Acknowledgement

Rate Controlled Bookmark Subscription

To create a bookmark subscription, set the Bookmark property on the

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
Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
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.

Table 10.12: Bookmark Subscription With Content Filter

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 max_gap option specifies the maximum amount of time for AMPS to allow between messages.

Header Comment
Topic
Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
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

Table 10.13: Bookmark Subscription with Maximum Gap Between Messages

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
Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
SubId A comma-delimited list of subscription IDs to pause.
Options A comma-delimited list of options for the command. To pause a subscription, the options must include pause.

Table 10.14: Pause a Bookmark Subscription

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
Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
SubId
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.

Table 10.15: Resume a Bookmark Subscription

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
Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
SubId 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.

Table 10.16: Replacing the Filter on a 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
Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
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

Table 10.17: Requesting a max_backlog

SOW query

This section presents common recipes for querying a SOW 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.

Basic SOW Query

In its simplest form, a SOW query needs only the topic to query.

Header Comment
Topic
Sets the topic to query. The SOW query returns all messages in the SOW. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.

Table 10.18: Basic SOW Query

Basic SOW With Options

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

Header Comment
Topic
Sets the topic to query. The SOW query returns all messages in the SOW. 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 AMPS Command Reference for a description of supported options.

Table 10.19: Basic SOW Query with Options

SOW Query With Ordered Results

In its simplest form, a SOW needs only the topic to subscribe to. To return the results in a specific order, provide an ordering expression in the OrderBy header.

Header Comment
Topic
Sets the topic to query. The SOW query returns all messages in the SOW. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
OrderBy

Orders the results returned as specified. Requires a comma-separated list of identifiers of the form:

/field/[ASC | DESC]

For example, to sort in descending order by orderDate so that the most recent orders are first, and ascending order by customerName for orders with the same date, you might use a specifier such as:

/orderDate DESC, /customerName ASC

Table 10.20: Basic SOW Query with Ordered Results

SOW Query With TopN Results

In its simplest form, a SOW needs only the topic to subscribe to. To return only a specific number of records, provide the number of records to return in the TopN header.

Header Comment
Topic
Sets the topic to query. The SOW query returns all messages in the SOW. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
TopN

The maximum number of records to return. AMPS uses the OrderBy header to determine the order of the records.

If no OrderBy header is provided, records are returned in an indeterminate order. In most cases, using an OrderBy header when you use the TopN header will guarantee that you get the records of interest.

OrderBy

Orders the results returned as specified. Requires a comma-separated list of identifiers of the form:

/field/[ASC | DESC]

For example, to sort in descending order by orderDate so that the most recent orders are first, and ascending order by customerName for orders with the same date, you might use a specifier such as:

/orderDate DESC, /customerName ASC

Table 10.21: SOW Query with TopN Results

Content Filtered SOW Query

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

Header Comment
Topic
Sets the topic to query. 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 query. Only messages that match the content filter will be returned in response to the query.

Table 10.22: Content Filtered SOW Query Subscription

Historical SOW Query

To create a historical SOW query, set the Bookmark property on the command. The property can be either a specific bookmark or a timestamp. The AMPS User Guide provides details on creating timestamps.

This command is only supported on SOW topics that have History enabled.

Header Comment
Topic
Sets the topic to query. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Bookmark Sets the historical point in the SOW at which to query. The query returns the saved state of the records in the SOW as of the point in time specified in this header.

Table 10.23: Historical SOW Query

Historical SOW Query With Content Filter

To create a historical SOW query, set the Bookmark property on the command. The property can be either a specific bookmark or a timestamp. The AMPS User Guide provides details on creating timestamps. To add a filter to the query, set the Filter property on the command. The AMPS User Guide provides details on the filter syntax.

This command is only supported on SOW topics that have History enabled.

Header Comment
Topic
Sets the topic to query. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Bookmark Sets the historical point in the SOW at which to query. The query returns the saved state of the records in the SOW as of the point in time specified in this header.
Filter Sets the content filter to be applied to the query. Only messages that match the content filter will be provided to the query.

Table 10.24: Historical SOW Query With Content Filter

SOW Query for Specific Records

AMPS allows a consumer to query for specific records as identified by a set of SowKeys. For topics where AMPS assigns the SowKey, the SowKey for the record is the AMPS-assigned identifier. For topics configured to require a user-provided SowKey, the SowKey for the record is the original key provided when the record was published. The AMPS User Guide provides more details on SOW keys.

Header Comment
Topic
Sets the topic to query. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
SowKeys

A comma-delimited list of SowKey values. AMPS returns only the records specified in this list.

For example, a valid format for a list of keys would be:

 1853097931817257202,104027799402
01650075,22363879930342650852

Table 10.25: SOW Query by SOW Key

SOW Query with Pagination

AMPS allows a consumer to page through records in the SOW using the top_n and skip_n options. With this approach, the application uses the top_n option to limit the number of records returned to a single page worth of records. The application uses the skip_n option to set the number of records to skip ahead to get to the page to display, and sets the OrderBy header to specify the ordering for the records. For example, if 10 records fit on a page, and the pages are ordered by the ClientName field of the records, to display the fourth page, the application would set top_n to 10, skip_n to 30 (to skip the first three pages of records), and OrderBy to /ClientName.

Header Comment
Topic
Sets the topic to query. The topic specified must be a literal topic name. Pagination is not supported with regular expression subscriptions.
OrderBy

Orders the results returned as specified. Requires a comma-separated list of identifiers of the form:

/field/[ASC | DESC]

For example, to sort in descending order by orderDate so that the most recent orders are first, and ascending order by customerName for orders with the same date, you might use a specifier such as:

/orderDate DESC, /customerName ASC
Options

An options string that sets the top_n and skip_n values for this query. For example, to skip 100 records and return the next 10 records, use an options string such as:

top_n=10,skip_n=100

Table 10.26: SOW Query With Pagination

Aggregated SOW Query

An aggregated SOW query is a SOW query that provides aggregation options in the options field. To add these options to the subscription, set the Options header on the Command.

Header Comment
Topic
Sets the topic to query. The SOW query returns all messages in the SOW. 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. For an aggregated SOW query, the options provide the projection and grouping for the aggregation.

See the AMPS Command Reference for a description of supported options.

Table 10.27: Aggregated SOW Query

SOW and Subscribe

This section presents common recipes for atomic sow and subscribe 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.

Basic SOW and Subscribe

In its simplest form, a SOW and Subscribe needs only the topic to subscribe to.

Header Comment
Topic
Sets the topic to query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.

Table 10.28: Basic SOW and Subscribe

SOW and Subscribe With Options

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

Header Comment
Topic
Sets the topic to query and subscribe to. 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 AMPS Command Reference for a full description of supported options.

The most common options for this command are:

oof Request out of focus notifications
timestamp Include timestamps on messages

Table 10.29: Basic SOW and Subscribe with Options

SOW and Subscribe With Select List

In its simplest form, a SOW and subscribe command needs only the topic to subscribe to. To add options to the subscription, set the Options header on the Command. To use a select list, include the specifier for the select list in the options provided.

Header Comment
Topic
Sets the topic to query and subscribe to. 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 AMPS Command Reference for a full description of supported options.

For example, to remove all fields except for id and ticker, and also request out of focus notifications, you might use an options string of: oof,select=[-/,+/id,+/ticker]

Table 10.30: Basic SOW and Subscribe with Select List

Content Filtered SOW and Subscribe

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

Header Comment
Topic
Sets the topic to query and 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 query. Only messages that match the content filter will be returned in response to the query.

Table 10.31: Content Filtered SOW and Subscribe

Conflated SOW and Subscribe

To request conflation on the subscription for a SOW and subscribe, 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
Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
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

Table 10.32: Conflated SOW and Subscribe

Paginated SOW and Subscribe

To request a paginated subscription for a SOW and subscribe, set the Options property on the command to specify the number of records to return and the number of records to skip before returning records. Most paginated subscriptions also specify the oof option to be notified when a record is out of focus.

Header Comment
Topic
Sets the topic to subscribe to. The topic specified must be a literal topic name. Pagination is not supported with regular expression subscriptions.
OrderBy Specifies how to order the results within the paginated result set. If the OrderBy is not provided, the results are ordered by the SowKey for the messages.
Options

A comma-separated list of options for the command. Set the number of results returned with top_n, and the starting point within the result set with skip_n.

For example, to display records 31-50 of the result set, you could provide the following option:

top_n=20,skip_n=30,oof

This tells AMPS to skip the first 30 records of the result set, and then provide the top 20 records from the remaining results. Out of focus notifications will be provided.

Table 10.33: Paginated SOW and Subscribe

Historical SOW and Subscribe

To create a historical SOW query with a subscription, set the Bookmark property on the command. The property can be either a specific bookmark or a timestamp. The AMPS User Guide provides details on creating timestamps. This command is only supported on SOW topics that are recorded in an AMPS transaction log.

When History is enabled for the SOW topic, the Bookmark provided must be a timestamp or a specific bookmark value, including the special values NOW (0|1|) or EPOCH (0).

If the Bookmark provided is a value other than NOW (0|1|), the SOW topic must have History enabled.

Header Comment
Topic
Sets the topic to query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Bookmark Sets the historical point in the SOW at which to query. The query returns the saved state of the records in the SOW as of the point in time specified in this header.

Table 10.34: Historical SOW and Subscribe

Historical SOW and Subscribe With Content Filter

To create a historical SOW query with a subscription, set the Bookmark property on the command. The property can be either a specific bookmark or a timestamp. The AMPS User Guide provides details on creating timestamps. This command is only supported on SOW topics that are recorded in an AMPS transaction log. If the Bookmark provided is a value other than NOW (0|1|), the SOW topic must have History enabled.

Header Comment
Topic
Sets the topic to query. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Bookmark Sets the historical point in the SOW at which to query. The query returns the saved state of the records in the SOW as of the point in time specified in this header.
Filter Sets the content filter to be applied to the query. Only messages that match the content filter will be provided to the query.

Table 10.35: Historical SOW and Subscribe With Content Filter

Aggregated SOW and Subscribe

An aggregated SOW and subscribe command is a SOW and subcribe command that provides aggregation options. To add these options to the sow and subscribe command, set the Options header on the Command.

Header Comment
Topic
Sets the topic to query and subscribe to. 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. For an aggregated subscription, the options provide the projection and grouping for the command.

An aggregated sow and subscribe can include options in addition to the projection and grouping. The most common additional options are:

oof Request out of focus notifications
timestamp Include timestamp headers on messages.

See the AMPS Command Reference for a full description of supported options.

Table 10.36: Aggregated SOW and Subscribe

Delta Publishing

This section presents common recipes for publishing 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.

Basic Delta Publish

In its simplest form, a subscription needs only the topic to publish to and the data to publish. The AMPS client automatically constructs the necessary AMPS headers and formats the full delta_publish command.

In many cases, a publisher only needs to use the basic delta publish command.

Header Comment
Topic

Sets the topic to publish to. The topic specified must be a literal topic name. Regular expression characters in the topic name are not interpreted.

Some topics in AMPS, such as views and conflated topics, cannot be published to directly. Instead, a publisher must publish to the underlying topics.

Data The data to publish to the topic. The AMPS client does not interpret, escape, or validate this data: the data is provided to the server verbatim.

Table 10.37: Basic Delta Publish

Delta Publish With CorrelationId

AMPS provides publishers with a header field that can be used to contain arbitrary data, the CorrelationId. A delta publish message can be used to update the CorrelationId as well as the data within the message.

Header Comment
Topic

Sets the topic to publish to. The topic specified must be a literal topic name. Regular expression characters in the topic name are not interpreted.

Some topics in AMPS, such as views and conflated topics, cannot be published to directly. Instead, a publisher must publish to the underlying topics.

Data The data to publish to the topic. The AMPS client does not interpret, escape, or validate this data: the data is provided to the server verbatim.
CorrelationId

The CorrelationId to provide on the message. AMPS provides the CorrelationId to subscribers. The CorrelationId has no significance for AMPS.

The CorrelationId may only contain characters that are valid in base-64 encoding.

Table 10.38: Delta Publish With CorrelationId

Delta Publish With Explicit SOW Key

When publishing to a SOW topic that is configured to require an explicit SOW key, the publisher needs to set the SowKey header on the message.

Header Comment
Topic

Sets the topic to publish to. The topic specified must be a literal topic name. Regular expression characters in the topic name are not interpreted.

Some topics in AMPS, such as views and conflated topics, cannot be published to directly. Instead, a publisher must publish to the underlying topics.

Data The data to publish to the topic. The AMPS client does not interpret, escape, or validate this data: the data is provided to the server verbatim.
SowKey The SOW Key to use for this message. This header is only supported for publishes to a topic that requires an explicit SOW Key.

Table 10.39: Delta Publish with Explicit SOW Key

Delta Subscribing

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.

Basic Delta Subscription

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

Header Comment
Topic
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.

Table 10.40: Basic Delta Subscription

Basic Delta 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
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 AMPS Command Reference for a description of supported options.

Table 10.41: Basic Delta Subscription

Content Filtered Delta Subscription

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
Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
Filter Sets the content filter to be applied to the subscription. Only messages that match the content filter will be provided to the subscription.

Table 10.42: Content Filtered Subscription

SOW and Delta Subscribe

This section presents common recipes for atomic sow and delta subscribe 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.

Basic SOW and Delta Subscribe

In its simplest form, a SOW and Delta Subscribe needs only the topic to subscribe to.

Header Comment
Topic
Sets the topic to query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.

Table 10.43: Basic SOW Query

SOW and Delta Subscribe With Options

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

Header Comment
Topic
Sets the topic to query and subscribe to. 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 AMPS Command Reference for a full description of supported options.

The most common options for this command are:

oof Request out of order notifications
timestamp Include timestamps on messages

Table 10.44: Basic SOW and Delta Subscribe with Options

Content Filtered SOW and Delta Subscribe

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

Header Comment
Topic
Sets the topic to query and 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 query. Only messages that match the content filter will be returned in response to the query.

Table 10.45: Content Filtered SOW and Delta Subscribe

Paginated SOW and Delta Subscribe

To request a paginated subscription for a SOW and delta subscribe, set the Options property on the command to specify the number of records to return and the number of records to skip before returning records. Most paginated subscriptions also specify the oof option to be notified when a record is out of focus.

Header Comment
Topic
Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
OrderBy Specifies how to order the results within the paginated result set. If the OrderBy is not provided, the results are ordered by the SowKey for the messages.
Options

A comma-separated list of options for the command. Set the number of results returned with top_n, and the starting point within the result set with skip_n.

For example, to display records 31-50 of the result set, you could provide the following option:

top_n=20,skip_n=30,oof

This tells AMPS to skip the first 30 records of the result set, and then provide the top 20 records from the remaining results. Out of focus notifications will be provided.

Table 10.46: Paginated SOW and Delta Subscribe

Aggregated SOW and Delta Subscribe

An aggregated SOW and delta subscribe is a SOW and delta subscribe command that provides aggregation options. To add these options ot the command, set the Options header on the Command.

Header Comment
Topic
Sets the topic to query and subscribe to. 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. For an aggregated SOW and delta subscribe, the options provide the projection and grouping for the command.

A SOW and delta subscribe can provide options in addition to the projection and grouping. The most common additional options are:

oof Request out of order notifications
timestamp Include timestamps on messages
no_empties Do not send a delta message if the update does not change the value of a field.

Table 10.47: Aggregated SOW and Delta Subscribe

SOW Delete

This section presents common recipes for sending a sow_delete command 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.

Delete All Records in a SOW

To delete all records in a SOW, provide a filter that evaluates to TRUE for every record in the SOW. By convention, 60East recommends 1=1 for the filter.

Header Comment
Topic
Sets the topic from which to remove records.
Filter
A filter specifying the messages to remove. By convention, use 1=1 to remove all records in the SOW.

Table 10.48: Delete All Records in a SOW

Delete SOW Records Matching a Filter

To delete the records that match a particular filter, provide the filter in the sow_delete command.

Header Comment
Topic
Sets the topic from which to remove records.
Filter
A filter specifying the messages to remove.

Table 10.49: Delete All Records in a SOW

Delete A Specific Message By Data

To delete a specific message, provide the data for the message to delete. With this form of SOW delete, AMPS deletes the message that would have been updated if the data were provided as a publish message. Notice that this form of sow_delete relies on the Key definition in the SOW configuration, and is not generally useful with explicitly-keyed SOW topics.

Header Comment
Topic
Sets the topic from which to remove records.
Data
The message to remove.

Table 10.50: Delete All Records in a SOW

Deleting Specific Messages Using Keys

To delete specific messages using SOW keys, provide the SOW keys for the message to delete.

Header Comment
Topic
Sets the topic from which to remove records.
SOWKeys
A comma-delimited list of SOWKeys that specify the messages to remove.

Table 10.51: Delete All Records in a SOW

Acknowledging Messages from a Queue

To acknowledge messages from an AMPS queue, provide the bookmarks for the messages to acknowledge. Notice that this is the only form of the sow_delete command that can acknowledge messages from a queue, and that this form of sow_delete is not accepted for topics that are not queue topics.

Header Comment
Topic
Sets the topic that contains the messages to acknowledge.
Bookmark
A comma-delimited list of Bookmarks that specify the messages to acknowledge.

Table 10.52: Acknowledging a queue message