Ending Subscriptions

The AMPS server continues a subscription until the client explicitly ends the subscription (that is, unsubscribes) or until the connection to the client is closed.

With the synchronous interface, AMPS automatically unsubscribes to the topic when the destructor for the MessageStream runs. You can also explicitly call the close() method on the MessageStream object to remove the subscription.

In the asynchronous interface, when a subscription is successfully made, messages will begin flowing to the message handler, and the subscribe() or executeAsync() call will return a string for the subscription id that serves as the identifier for this subscription. A Client can have any number of active subscriptions, and this subscription id is how AMPS designates messages intended for this particular subscription. To unsubscribe, we simply call unsubscribe with the subscription identifier:

Client c = ...;


// try/catch block to manage client lifetime
// is left out

// ... subscribe using the asynchronous message
// processing interface and save the subId

CommandId subId = c.subscribe(new MyMessageHandler(), "messages");

// ... other code here ...

c.unsubscribe(subId);

In this example we use the client.subscribe() method to create a subscription to the messages topic. The subscribe method returns an identifier for the subscription created in AMPS. When our application is done listening to this topic, it unsubscribes by passing in the subId returned by subscribe(). AMPS deletes the subscription. After the subscription is removed, no more messages will flow into the MyMessageHandler() instance for that subscription.

When an application calls unsubscribe(), the client sends an explicit unsubscribe command to AMPS. The AMPS server removes that subscription from the set of subscriptions for the client, and stops sending messages for that subscription. On the client side, the client unregisters the subscription so that the MessageStream or MessageHandler for that subscription will no longer receive messages for that subscription.

Notice that calling unsubscribe does not destroy messages that the server has already sent to the client. If there are messages on the way to the client for this subscription, the AMPS client must consume those messages. If a LastChanceMessageHandler is registered, the handler may receive the messages. Otherwise, they will be discarded since no message handler matches the subscription ID on the message.