io.nats.client

Interface ErrorListener

public interface ErrorListener

This library groups problems into four categories:

Errors

The server sent an error message using the -err protocol operation.

Exceptions

A Java exception occurred, and was handled by the library.

Slow Consumers

One of the connections consumers, Subscription or Dispatcher, is slow, and starting to drop messages.

Fast Producers

One of the connections producers is too fast, and is discarding messages

All of these problems are reported to the application code using the ErrorListener. The listener is configured in the Options at creation time.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	ErrorListener.FlowControlSource

Method Summary

Modifier and Type	Method and Description
default void	errorOccurred(Connection conn, java.lang.String error) NATs related errors that occur asynchronously in the client library are sent to an ErrorListener via errorOccurred.
default void	exceptionOccurred(Connection conn, java.lang.Exception exp) Exceptions that occur in the "normal" course of operations are sent to the ErrorListener using exceptionOccurred.
default void	flowControlProcessed(Connection conn, JetStreamSubscription sub, java.lang.String subject, ErrorListener.FlowControlSource source) Called by the connection when a flow control is processed.
default void	heartbeatAlarm(Connection conn, JetStreamSubscription sub, long lastStreamSequence, long lastConsumerSequence) Called when subscription heartbeats are missed according to the configured period and threshold.
default void	messageDiscarded(Connection conn, Message msg) Called by the connection when a message is discarded.
default void	pullStatusError(Connection conn, JetStreamSubscription sub, Status status) Called when a pull subscription receives a status message that indicates either the subscription cannot continue or the pull request cannot be processed.
default void	pullStatusWarning(Connection conn, JetStreamSubscription sub, Status status) Called when a pull subscription receives a status message that indicates either the subscription or pull might be problematic
default void	slowConsumerDetected(Connection conn, Consumer consumer) Called by the connection when a "slow" consumer is detected.
default void	socketWriteTimeout(Connection conn) Called by the connection when a low level socket write timeout occurs.
default java.lang.String	supplyMessage(java.lang.String label, Connection conn, Consumer consumer, Subscription sub, java.lang.Object... pairs) General message producing function which understands the possible parameters to listener calls.
default void	unhandledStatus(Connection conn, JetStreamSubscription sub, Status status) Called when an unhandled status is received in a push subscription.

Method Detail

errorOccurred

default void errorOccurred(Connection conn,
                           java.lang.String error)

NATs related errors that occur asynchronously in the client library are sent to an ErrorListener via errorOccurred. The ErrorListener can use the error text to decide what to do about the problem.

The text for an error is described in the protocol doc at `https://nats.io/documentation/internals/nats-protocol`.

In some cases the server will close the clients connection after sending one of these errors. In that case, the connections ConnectionListener will be notified.

Parameters:

conn - The connection associated with the error

error - The text of error that has occurred, directly from the server

exceptionOccurred

default void exceptionOccurred(Connection conn,
                               java.lang.Exception exp)

Exceptions that occur in the "normal" course of operations are sent to the ErrorListener using exceptionOccurred. Examples include, application exceptions during Dispatcher callbacks, IOExceptions from the underlying socket, etc.. The library will try to handle these, via reconnect or catching them, but they are forwarded here in case the application code needs them for debugging purposes.

Parameters:

conn - The connection associated with the error

exp - The exception that has occurred, and was handled by the library

slowConsumerDetected

default void slowConsumerDetected(Connection conn,
                                  Consumer consumer)

Called by the connection when a "slow" consumer is detected. This call is only made once until the consumer stops being slow. At which point it will be called again if the consumer starts being slow again.

See Consumer.setPendingLimits for information on how to configure when this method is fired.

Slow consumers will result in dropped messages each consumer provides a method for retrieving the count of dropped messages, see Consumer.getDroppedCount.

Parameters:

conn - The connection associated with the error

consumer - The consumer that is being marked slow

messageDiscarded

default void messageDiscarded(Connection conn,
                              Message msg)

Called by the connection when a message is discarded.

Parameters:

conn - The connection that discarded the message

msg - The message that is discarded

heartbeatAlarm

default void heartbeatAlarm(Connection conn,
                            JetStreamSubscription sub,
                            long lastStreamSequence,
                            long lastConsumerSequence)

Called when subscription heartbeats are missed according to the configured period and threshold. The consumer must be configured with an idle heartbeat time.

Parameters:

conn - The connection that had the issue

sub - the JetStreamSubscription that this occurred on

lastStreamSequence - the last received stream sequence

lastConsumerSequence - the last received consumer sequence

unhandledStatus

default void unhandledStatus(Connection conn,
                             JetStreamSubscription sub,
                             Status status)

Called when an unhandled status is received in a push subscription.

Parameters:

conn - The connection that had the issue

sub - the JetStreamSubscription that this occurred on

status - the status

pullStatusWarning

default void pullStatusWarning(Connection conn,
                               JetStreamSubscription sub,
                               Status status)

Called when a pull subscription receives a status message that indicates either the subscription or pull might be problematic

Parameters:

conn - The connection that had the issue

sub - the JetStreamSubscription that this occurred on

status - the status

pullStatusError

default void pullStatusError(Connection conn,
                             JetStreamSubscription sub,
                             Status status)

Called when a pull subscription receives a status message that indicates either the subscription cannot continue or the pull request cannot be processed.

Parameters:

conn - The connection that had the issue

sub - the JetStreamSubscription that this occurred on

status - the status

flowControlProcessed

default void flowControlProcessed(Connection conn,
                                  JetStreamSubscription sub,
                                  java.lang.String subject,
                                  ErrorListener.FlowControlSource source)

Called by the connection when a flow control is processed.

Parameters:

conn - The connection that had the issue

sub - the JetStreamSubscription that this occurred on

subject - the flow control subject that was handled

source - enum indicating flow control handling in response to which type of message

socketWriteTimeout

default void socketWriteTimeout(Connection conn)

Called by the connection when a low level socket write timeout occurs.

Parameters:

conn - The connection that had the issue

supplyMessage

default java.lang.String supplyMessage(java.lang.String label,
                                       Connection conn,
                                       Consumer consumer,
                                       Subscription sub,
                                       java.lang.Object... pairs)

General message producing function which understands the possible parameters to listener calls.

Parameters:

label - the label for the message

conn - The connection that had the issue, if provided.

consumer - The consumer that is being marked slow, if applicable

sub - the JetStreamSubscription that this occurred on, if applicable

pairs - custom string pairs. I.E. "foo: ", fooObject, "bar-", barObject will be appended to the message like ", foo: <fooValue>, bar-<barValue>".

Returns:

the message