Subscriptions

Messages published to a topic on an AMPS server are available to other clients via a subscription. Before messages can be received, a client must subscribe to one or more topics on the AMPS server so that the server will begin sending messages to the client. The server will continue sending messages to the client until the client unsubscribes, or the client disconnects. With content filtering, the AMPS server will limit the messages sent to only those messages that match a client-supplied filter. In this chapter, you will learn how to subscribe, unsubscribe, and supply filters for messages using the AMPS JavaScript client.

Subscribing to a Topic

The AMPS client makes it simple to subscribe to a topic. You call Client.subscribe() with the message handler, the topic to subscribe to and the parameters for the subscription. The client submits the subscription to AMPS and returns a Promise object that resolves with the subscription identifier. Received messages are asynchronously delivered to the message handler function. Below is a short example:

/**
* Let's create a message handler function. It will be invoked
* when AMPS delivers messages to the subscription.
* Within this handler, we process messages. In this case,
* we simply print the contents of the message.
*/
const onMessage = message => console.log(message.data);

// let's create a Client that is connected to an AMPS server.
const client = new Client('test');
await client.connect('wss://127.0.0.1:9007/amps/json');

/**
* Here we subscribe to the topic "messages". We do not provide
* a filter, so AMPS does not content-filter the topic.
* The command resolves with the id of the subscription.
*/
const subId = await client.subscribe(onMessage, 'messages');
console.log('subId:', subId);

AMPS creates an asynchronous subscription that receives messages and calls the message handler only if there's a new message. This means that the client application as a whole can continue to receive messages while you are doing processing work, by stacking them in the execution queue.

The simple method described above is provided for convenience. The AMPS JavaScript client provides convenience methods for the most common form of AMPS commands. The client also provides an interface that allows you to have precise control over the command. Using that interface, the example above becomes:

/**
* Let's create a message handler function. It will be invoked
* when AMPS delivers messages to the subscription.
* Within this handler, we process messages. In this case,
* we simply print the contents of the message.
*/
const onMessage = message => console.log(message.data);

// let's create a Client that is connected to an AMPS server.
const client = new Client('test');
await client.connect('wss://127.0.0.1:9007/amps/json');

/**
* Here we create a Command object for the subscribe
* command, specifying the topic "messages". We do not
* provide a filter, so AMPS does not content-filter
* the topic.
*/
const cmd = new Command('subscribe').topic('messages');

/**
* We execute the Command using the execute() method.
* The command execution resolves with the id of the
* subscription.
*/
const subId = await client.execute(cmd, onMessage);
console.log('subId: ', subId);

The Command interface allows you to precisely customize the commands you send to AMPS. For flexibility and ease of maintenance, 60East recommends using the Command interface (rather than a named method) for any command that will receive messages from AMPS. For publishing messages, there can be a slight performance advantage to using the named commands where possible.