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.

Field Summary

Fields inherited from interface io.nats.client.Consumer

DEFAULT_MAX_BYTES, DEFAULT_MAX_MESSAGES

Method Summary

Modifier and Type	Method and Description
void	start(java.lang.String id) Start the dispatcher with a given id.
Dispatcher	subscribe(java.lang.String subject) Create a subscription to the specified subject under the control of this dispatcher.
Subscription	subscribe(java.lang.String subject, MessageHandler handler) Create a subscription to the specified subject under the control of this dispatcher.
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.
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.
Dispatcher	unsubscribe(java.lang.String subject) Unsubscribe from the specified subject, the queue is implicit.
Dispatcher	unsubscribe(java.lang.String subject, int after) Unsubscribe from the specified subject, the queue is implicit, after the specified number of messages.
Dispatcher	unsubscribe(Subscription subscription) Unsubscribe from the specified Subscription.
Dispatcher	unsubscribe(Subscription subscription, int after) Unsubscribe from the specified subject, the queue is implicit, after the specified number of messages.

Methods inherited from interface io.nats.client.Consumer

clearDroppedCount, drain, getDeliveredCount, getDroppedCount, getPendingByteCount, getPendingByteLimit, getPendingMessageCount, getPendingMessageLimit, isActive, setPendingLimits

Method Detail

start

void start(java.lang.String id)

Start the dispatcher with a given id. Use post-construction to start to the dispatcher, which should not be started on construction.

Parameters:

id - the assigned id of the dispatcher

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