Package io.nats.client

Interface Dispatcher

  • All Superinterfaces:
    Consumer
    public interface Dispatcher
extends Consumer
    This library uses the concept of a Dispatcher to organize message callbacks in a way that the application can control. Each dispatcher has a single MessageHandler that will be notified of incoming messages. The dispatcher also has 0 or more subscriptions associated with it. This means that a group of subscriptions, or subjects, can be combined into a single callback thread. But, multiple dispatchers can be created to handle different groups of subscriptions/subjects.

    All messages to this dispatcher are delivered via a single thread. If the message handler is slow to handle any one message it will delay deliver of subsequent messages. Use separate dispatchers to handle the scenario of a set of messages that require a lot of work and a set of fast moving messages, or create other threads as necessary. The Dispatcher will only use one.

    Dispatchers are created from the connection using createDispatcher() and can be closed using closeDispatcher(). Closing a dispatcher will clean up the thread it is using for message deliver.

    See the documentation on Consumer for configuring behavior in a slow consumer situation.

    • Method Detail

      • subscribe

        Dispatcher subscribe​(java.lang.String subject)
        Create a subscription to the specified subject under the control of this dispatcher.

        This call is a no-op if the dispatcher already has a subscription to the specified subject.

        Parameters:
        subject - The subject to subscribe to.
        Returns:
        The Dispatcher, so calls can be chained.
        Throws:
        java.lang.IllegalStateException - if the dispatcher was previously closed

      • subscribe

        Dispatcher subscribe​(java.lang.String subject,
                     java.lang.String queue)
        Create a subscription to the specified subject and queue under the control of this dispatcher.

        This call is a no-op if the dispatcher already has a subscription to the specified subject (regardless of the queue name).

        Parameters:
        subject - The subject to subscribe to.
        queue - The queue group to join.
        Returns:
        The Dispatcher, so calls can be chained.
        Throws:
        java.lang.IllegalStateException - if the dispatcher was previously closed

      • subscribe

        Subscription subscribe​(java.lang.String subject,
                       MessageHandler handler)
        Create a subscription to the specified subject under the control of this dispatcher. Since a MessageHandler is also required, the Dispatcher will not prevent duplicate subscriptions from being made.

        Every call creates a new subscription, unlike the subscribe(String) method that does not take a MessageHandler.

        Parameters:
        subject - The subject to subscribe to.
        handler - The target for the messages
        Returns:
        The Subscription, so subscriptions may be later unsubscribed manually.
        Throws:
        java.lang.IllegalStateException - if the dispatcher was previously closed

      • subscribe

        Subscription subscribe​(java.lang.String subject,
                       java.lang.String queue,
                       MessageHandler handler)
        Create a subscription to the specified subject under the control of this dispatcher. Since a MessageHandler is also required, the Dispatcher will not prevent duplicate subscriptions from being made.

        Every call creates a new subscription, unlike the subscribe(String, String) method that does not take a MessageHandler.

        Parameters:
        subject - The subject to subscribe to.
        queue - The queue group to join.
        handler - The target for the messages
        Returns:
        The Subscription, so subscriptions may be later unsubscribed manually.
        Throws:
        java.lang.IllegalStateException - if the dispatcher was previously closed

      • unsubscribe

        Dispatcher unsubscribe​(java.lang.String subject)
        Unsubscribe from the specified subject, the queue is implicit.

        Stops messages to the subscription locally and notifies the server.

        Parameters:
        subject - The subject to unsubscribe from.
        Returns:
        The Dispatcher, so calls can be chained.
        Throws:
        java.lang.IllegalStateException - if the dispatcher was previously closed

      • unsubscribe

        Dispatcher unsubscribe​(Subscription subscription)
        Unsubscribe from the specified Subscription.

        Stops messages to the subscription locally and notifies the server. This method is to be used to unsubscribe from subscriptions created by the Dispatcher using subscribe(String, MessageHandler).

        Parameters:
        subscription - The Subscription to unsubscribe from.
        Returns:
        The Dispatcher, so calls can be chained.
        Throws:
        java.lang.IllegalStateException - if the dispatcher was previously closed
        java.lang.IllegalStateException - if the Subscription is not managed by this dispatcher

      • unsubscribe

        Dispatcher unsubscribe​(java.lang.String subject,
                       int after)
        Unsubscribe from the specified subject, the queue is implicit, 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.

        For example, to get a single asynchronous message, you might do: 

         nc = Nats.connect()
 d = nc.createDispatcher(myHandler);
 d.subscribe("hello").unsubscribe("hello", 1);
        Parameters:
        subject - The subject to unsubscribe from.
        after - The number of messages to accept before unsubscribing
        Returns:
        The Dispatcher, so calls can be chained.
        Throws:
        java.lang.IllegalStateException - if the dispatcher was previously closed

      • unsubscribe

        Dispatcher unsubscribe​(Subscription subscription,
                       int after)
        Unsubscribe from the specified subject, the queue is implicit, 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.

        Stops messages to the subscription locally and notifies the server. This method is to be used to unsubscribe from subscriptions created by the Dispatcher using subscribe(String, MessageHandler).

        Parameters:
        subscription - The Subscription to unsubscribe from.
        after - The number of messages to accept before unsubscribing
        Returns:
        The Dispatcher, so calls can be chained.
        Throws:
        java.lang.IllegalStateException - if the dispatcher was previously closed
        java.lang.IllegalStateException - if the Subscription is not managed by this dispatcher