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
Dispatcher	subscribe(java.lang.String subject) 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.
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.

Methods inherited from interface io.nats.client.Consumer

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

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

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(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