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.

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	getDispatcher()
java.lang.String	getQueueName()
java.lang.String	getSubject()
Message	nextMessage(java.time.Duration timeout) Read the next message for a subscription, or block until one is available.
void	unsubscribe() Unsubscribe this subscription and stop listening for messages.
Subscription	unsubscribe(int after) Unsubscribe this subscription and stop listening for messages, 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

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