Package io.nats.client

Interface Consumer

  • All Known Subinterfaces:
    Dispatcher, Subscription
    public interface Consumer
    A Consumer in the NATS library is an object that represents an incoming queue of messages. There are two types of consumers Dispatcher and Subscription. This interface unifies the responsibilities that are focused on dealing with slow consumers. The Dispatcher and Subscription deal with the mechanics of their specialized roles.

    A slow consumer is defined as a consumer that is not handling messages as quickly as they are arriving. For example, if the application code doesn't call nextMessage() often enough on a Subscription.

    By default the library will allow a consumer to be a bit slow, at times, by caching messages for it in a queue. The size of this queue is determined by setPendingLimits(). When a consumer maxes out its queue size, either by message count or bytes, the library will start to drop messages.

    • Field Detail

      • DEFAULT_MAX_MESSAGES

        static final long DEFAULT_MAX_MESSAGES
        The default number of messages a consumer will hold before it starts to drop them.
        See Also:
        Constant Field Values

      • DEFAULT_MAX_BYTES

        static final long DEFAULT_MAX_BYTES
        The default number of bytes a consumer will hold before it starts to drop messages.
        See Also:
        Constant Field Values

    • Method Detail

      • setPendingLimits

        void setPendingLimits​(long maxMessages,
                      long maxBytes)
        Set limits on the maximum number of messages, or maximum size of messages this consumer will hold before it starts to drop new messages waiting for the application to drain the queue.

        Messages are dropped as they encounter a full queue, which is to say, new messages are dropped rather than old messages. If a queue is 10 deep and fills up, the 11th message is dropped.

        Sizes are checked after the fact, so if the max bytes is too small for the first pending message to arrive, it will still be stored, only the next message will fail.

        Setting a value to anything less than or equal to 0 will disable this check.

        Parameters:
        maxMessages - the maximum message count to hold, defaults to {65536L}
        maxBytes - the maximum bytes to hold, defaults to {67108864L}

      • getPendingMessageLimit

        long getPendingMessageLimit()
        Returns:
        the pending message limit set by setPendingLimits

      • getPendingByteLimit

        long getPendingByteLimit()
        Returns:
        the pending byte limit set by setPendingLimits

      • getPendingMessageCount

        long getPendingMessageCount()
        Returns:
        the number of messages waiting to be delivered/popped, setPendingLimits

      • getPendingByteCount

        long getPendingByteCount()
        Returns:
        the cumulative size of the messages waiting to be delivered/popped, setPendingLimits

      • getDeliveredCount

        long getDeliveredCount()
        Returns:
        the total number of messages delivered to this consumer, for all time

      • getDroppedCount

        long getDroppedCount()
        Returns:
        the number of messages dropped from this consumer, since the last call to clearDroppedCount.

      • clearDroppedCount

        void clearDroppedCount()
        Reset the drop count to 0.

      • isActive

        boolean isActive()
        Returns:
        whether or not this consumer is still processing messages. For a subscription the answer is false after unsubscribe. For a dispatcher, false after stop.

      • drain

        java.util.concurrent.CompletableFuture<java.lang.Boolean> drain​(java.time.Duration timeout)
                                                         throws java.lang.InterruptedException
        Drain tells the consumer to process in flight, or cached messages, but stop receiving new ones. The library will flush the unsubscribe call(s) insuring that any publish calls made by this client are included. When all messages are processed the consumer effectively becomes unsubscribed. A future is used to allow this call to be treated as synchronous or asynchronous as needed by the application.
        Parameters:
        timeout - The time to wait for the drain to succeed, pass 0 to wait forever. Drain involves moving messages to and from the server so a very short timeout is not recommended.
        Returns:
        A future that can be used to check if the drain has completed
        Throws:
        java.lang.InterruptedException - if the thread is interrupted