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.

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