Ending Subscriptions

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

With the synchronous message processing interface, AMPS automatically unsubscribes when the dispose() method for the MessageStream is called. You can also explicitly call the close() method on the MessageStream to remove the subscription.

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

Client c = ...;

Command subscribe_command = new Command("subscribe").setTopic("messages");

CommandId subscriptionId = c.executeAsync(subscribe_command,
    (message) => Console.WriteLine(message));

...

client.unsubscribe(subscriptionId);

In this example, we use the executeAsync() method to create a subscription to the messages topic. When our application is done listening to this topic, it unsubscribes by executing an unsubscribe command that contains the subscriptionId returned when the subscription was created. After the subscription is removed, no more messages will flow into our (message) lambda function.

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 will receive the messages. Otherwise, they will be discarded since no MessageHandler matches the subscription ID on the message.