Package io.nats.client

Interface Subscription

  • All Superinterfaces:
    Consumer
    public interface Subscription
extends Consumer
    A Subscription encapsulates an incoming queue of messages associated with a single subject and optional queue name. Subscriptions can be in one of two modes. Either the subscription can be used for synchronous reading of messages with nextMessage() or the subscription can be owned by a Dispatcher. When a subscription is owned by a dispatcher it cannot be used to get messages or unsubscribe, those operations must be performed on the dispatcher.

    Subscriptions support the concept of auto-unsubscribe. This concept is a bit tricky, as it involves the client library, the server and the Subscriptions history. If told to unsubscribe after 5 messages, a subscription will stop receiving messages when one of the following occurs:

    • The subscription delivers 5 messages with next messages, including any previous messages.
    • The server sends 5 messages to the subscription.
    • The subscription already received 5 or more messages.

    In the case of a reconnect, the remaining message count, as maintained by the subscription, will be sent to the server. So if you unsubscribe with a max of 5, then disconnect after 2, the new server will be told to unsubscribe after 3.

    The other, possibly confusing case, is that unsubscribe is based on total messages. So if you make a subscription and receive 5 messages on it, then say unsubscribe with a maximum of 5, the subscription will immediately stop handling messages.

    • Method Detail

      • getSubject

        java.lang.String getSubject()
        Returns:
        the subject associated with this subscription, will be non-null

      • getQueueName

        java.lang.String getQueueName()
        Returns:
        the queue associated with this subscription, may be null.

      • getDispatcher

        Dispatcher getDispatcher()
        Returns:
        the Dispatcher that owns this subscription, or null

      • nextMessage

        Message nextMessage​(java.time.Duration timeout)
             throws java.lang.InterruptedException,
                    java.lang.IllegalStateException
        Read the next message for a subscription, or block until one is available. While useful in some situations, i.e. tests and simple examples, using a Dispatcher is generally easier and likely preferred for application code.

        Will return null if the calls times out.

        Use a timeout of 0 to wait indefinitely. This could still be interrupted if the subscription is unsubscribed or the client connection is closed.

        Parameters:
        timeout - the maximum time to wait
        Returns:
        the next message for this subscriber or null if there is a timeout
        Throws:
        java.lang.IllegalStateException - if the subscription belongs to a dispatcher, or is not active
        java.lang.InterruptedException - if one occurs while waiting for the message

      • unsubscribe

        void unsubscribe()
        Unsubscribe this subscription and stop listening for messages.

        Stops messages to the subscription locally and notifies the server.

        Throws:
        java.lang.IllegalStateException - if the subscription belongs to a dispatcher, or is not active

      • unsubscribe

        Subscription unsubscribe​(int after)
        Unsubscribe this subscription and stop listening for messages, after the specified number of messages.

        If the subscription has already received after messages, it will not receive more. The provided limit is a lifetime total for the subscription, with the caveat that if the subscription already received more than after when unsubscribe is called the client will not travel back in time to stop them.

        Supports chaining so that you can do things like: 

         nc = Nats.connect()
 m = nc.subscribe("hello").unsubscribe(1).nextMessage(Duration.ZERO);
        Parameters:
        after - the number of messages to accept before unsubscribing
        Returns:
        the subscription so that calls can be chained
        Throws:
        java.lang.IllegalStateException - if the subscription belongs to a dispatcher, or is not active