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 the message, or 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 and Commands

AMPS messages are represented in the client as Message objects. The Message object is generic, and can represent any type of AMPS message. This section includes a brief overview of elements common to Command - the class that is used to build AMPS messages. Full details of commands to AMPS are provided in the AMPS Command Reference Guide.

All AMPS Command objects 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 command 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 a Command

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

var command = new amps.Command('sow');

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

var command = new amps.command('publish')
                  .topic('messages')
                  .data({id: 1, hello: 'World'})
                  .expiration(5);

Another example is a SOW command:

var command = new amps.command('sow')
                  .topic('messages-sow')
                  .filter('/id > 20');

When sent to AMPS using the Client.execute() method, AMPS performs a SOW query from the topic messages-sow using a 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 command, use the Client.execute() method to send the command to AMPS. The method returns the Promise object, sends the message to AMPS, waits for a processed acknowledgment, then resolves the promise with the command ID. Messages are processed on the client asynchronously.

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

client
    .execute(command, messageHandler)
    .then(function(commandId) { ... })
    .catch(...);

This is equivalent to calling the Client.sow() method.

You can also provide a message handler to receive acknowledgments, statistics, or the results of subscriptions and SOW queries:

function messageHandler(message) {
    // Received the requested ack 'processed' message
    if (message.c === 'ack') {
        console.log(message.a + ':', message.reason);
    }
    else {
        // other messages are handled here
        // ...
    }
}

client.execute(
    // request the ack message from AMPS
    command.ackType('processed'),

    // Message handler
    messageHandler
);

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.

Notice that the publish command does not typically return results other than acknowledgment messages. To send a publish command, use the execute() method, without providing a message handler:

client.execute(publishCmd);