io.nats.client

Interface Connection

public interface Connection

A Connection object is a client's active connection to NATS.

Method Summary

Modifier and Type	Method and Description
void	close() Closes the connection, also closing all subscriptions on this connection.
void	flush() Flushes the current connection, waiting up to 60 seconds for completion.
void	flush(int timeout) Flushes the current connection, waiting up to timeout for successful completion.
ClosedCallback	getClosedCallback() Returns the connection closed callback.
String	getConnectedServerId() Returns the unique server ID string of the connected server.
io.nats.client.ServerInfo	getConnectedServerInfo() Returns the details from the INFO protocol message received.
String	getConnectedUrl() Returns the URL string of the currently connected NATS server.
DisconnectedCallback	getDisconnectedCallback() Returns the connection disconnected callback.
ExceptionHandler	getExceptionHandler() Returns the connection's asynchronous exception callback.
Exception	getLastException() Returns the last exception registered on the connection.
long	getMaxPayload() Gets the maximum payload size this connection will accept.
int	getPendingByteCount() Returns the number of valid bytes in the pending output buffer.
ReconnectedCallback	getReconnectedCallback() Returns the connection reconnected callback.
Constants.ConnState	getState() Returns the current connection state.
Statistics	getStats() Retrieves the connection statistics.
boolean	isClosed() Indicates whether the connection has been closed.
boolean	isReconnecting() Indicates whether the connection is currently reconnecting.
String	newInbox() Creates a new, uniquely named inbox with the prefix '_INBOX.'
void	publish(Message msg) Publishes a message to a subject.
void	publish(String subject, byte[] data) Publishes the payload specified by data to the subject specified by subject.
void	publish(String subject, String reply, byte[] data) Publishes the payload specified by data to the subject specified by subject, with an optional reply subject.
Message	request(String subject, byte[] data) Publishes a request message to the specified subject, waiting for a response until one is available.
Message	request(String subject, byte[] data, long timeout) Publishes a request message to the specified subject, waiting up to timeout msec for a response.
Message	request(String subject, byte[] data, long timeout, TimeUnit unit)
void	resetStats() Resets the gathered statistics for this connection.
void	setClosedCallback(ClosedCallback cb) Sets the connection closed callback.
void	setDisconnectedCallback(DisconnectedCallback cb) Sets the connection disconnected callback.
void	setExceptionHandler(ExceptionHandler exceptionHandler) Sets the connection's asynchronous exception callback.
void	setReconnectedCallback(ReconnectedCallback cb) Sets the connection reconnected callback.
AsyncSubscription	subscribe(String subject, MessageHandler cb) Creates a AsyncSubscription with interest in a given subject, assign the callback, and immediately start receiving messages
Subscription	subscribe(String subject, String queue, MessageHandler cb) Creates an asynchronous queue subscriber on a given subject of interest.
AsyncSubscription	subscribeAsync(String subject) Creates a AsyncSubscription with interest in a given subject.
AsyncSubscription	subscribeAsync(String subject, MessageHandler cb) Creates a AsyncSubscription with interest in a given subject, assign the callback, and immediately start receiving messages
AsyncSubscription	subscribeAsync(String subject, String queue) Creates an asynchronous queue subscriber on a given subject of interest.
AsyncSubscription	subscribeAsync(String subject, String queue, MessageHandler cb) Create an AsyncSubscription with interest in a given subject, assign the message callback, and immediately start receiving messages.
SyncSubscription	subscribeSync(String subject) Creates a SyncSubscription with interest in a given subject.
SyncSubscription	subscribeSync(String subject, String queue) Creates a synchronous queue subscriber on a given subject of interest.

Method Detail

publish

void publish(String subject,
             byte[] data)
      throws IOException

Publishes the payload specified by data to the subject specified by subject.

Parameters:

subject - the subject to publish the message to

data - the message payload

Throws:

IOException - if an I/O error is encountered

publish

void publish(Message msg)
      throws IOException

Publishes a message to a subject. The subject is set via Message.setSubject(String) or the Message.Message(String, String, byte[]) constructor.

Parameters:

msg - the Message to publish

Throws:

IOException - if an I/O error is encountered

publish

void publish(String subject,
             String reply,
             byte[] data)
      throws IOException

Publishes the payload specified by data to the subject specified by subject, with an optional reply subject. If reply is null, the behavior is identical to publish(String, byte[])

Parameters:

subject - the subject to publish the message to

reply - the subject to which subscribers should send responses

data - the message payload

Throws:

IOException - if an I/O error is encountered

request

Message request(String subject,
                byte[] data,
                long timeout)
         throws TimeoutException,
                IOException

Publishes a request message to the specified subject, waiting up to timeout msec for a response.

Parameters:

subject - the subject to publish the request message to

data - the request message payload

timeout - how long to wait for a response message (in msec)

Returns:

the response message

Throws:

IOException - if a connection-related error occurs

TimeoutException - if timeout elapses before a message is returned

request

Message request(String subject,
                byte[] data)
         throws TimeoutException,
                IOException

Publishes a request message to the specified subject, waiting for a response until one is available.

Parameters:

subject - the subject to publish the request message to

data - the message payload

Returns:

the response message

Throws:

IOException - if a connection-related error occurs

TimeoutException - if timeout elapses before a message is returned

request

Message request(String subject,
                byte[] data,
                long timeout,
                TimeUnit unit)
         throws TimeoutException,
                IOException

Throws:

TimeoutException

IOException

subscribe

AsyncSubscription subscribe(String subject,
                            MessageHandler cb)

Creates a AsyncSubscription with interest in a given subject, assign the callback, and immediately start receiving messages

Parameters:

subject - the subject of interest

cb - a MessageHandler object used to process messages received by the AsyncSubscription

Returns:

the started AsyncSubscription

Throws:

IllegalArgumentException - if the subject (or queue) name contains illegal characters.

NullPointerException - if the subject name is null

IllegalStateException - if the connection is closed

subscribe

Subscription subscribe(String subject,
                       String queue,
                       MessageHandler cb)

Creates an asynchronous queue subscriber on a given subject of interest. All subscribers with the same queue name will form the queue group and only one member of the group will be selected to receive any given message asynchronously.

Parameters:

subject - the subject of interest

queue - the name of the queue group

cb - a MessageHandler object used to process messages received by the Subscription

Returns:

Subscription

subscribeAsync

AsyncSubscription subscribeAsync(String subject)

Creates a AsyncSubscription with interest in a given subject. In order to receive messages, a MessageHandler must be registered, and AsyncSubscription.start() must be called.

Parameters:

subject - the subject of interest

Returns:

the AsyncSubscription

Throws:

IllegalArgumentException - if the subject name contains illegal characters.

NullPointerException - if the subject name is null

IllegalStateException - if the connection is closed

subscribeAsync

AsyncSubscription subscribeAsync(String subject,
                                 MessageHandler cb)

Creates a AsyncSubscription with interest in a given subject, assign the callback, and immediately start receiving messages

Parameters:

subject - the subject of interest

cb - a MessageHandler object used to process messages received by the AsyncSubscription

Returns:

the started AsyncSubscription

Throws:

IllegalArgumentException - if the subject (or queue) name contains illegal characters.

NullPointerException - if the subject name is null

IllegalStateException - if the connection is closed

subscribeAsync

AsyncSubscription subscribeAsync(String subject,
                                 String queue)

Creates an asynchronous queue subscriber on a given subject of interest. All subscribers with the same queue name will form the queue group and only one member of the group will be selected to receive any given message. In order to receive messages, a MessageHandler must be registered, and AsyncSubscription.start() must be called.

Parameters:

subject - the subject of interest

queue - the name of the queue group

Returns:

the Subscription

Throws:

IllegalArgumentException - if the subject (or queue) name contains illegal characters.

NullPointerException - if the subject name is null

IllegalStateException - if the connection is closed

subscribeAsync

AsyncSubscription subscribeAsync(String subject,
                                 String queue,
                                 MessageHandler cb)

Create an AsyncSubscription with interest in a given subject, assign the message callback, and immediately start receiving messages.

Parameters:

subject - the subject of interest

queue - the name of the queue group

cb - a message callback for this subscription

Returns:

the AsyncSubscription

Throws:

IllegalArgumentException - if the subject (or queue) name contains illegal characters.

NullPointerException - if the subject name is null

IllegalStateException - if the connection is closed

subscribeSync

SyncSubscription subscribeSync(String subject,
                               String queue)

Creates a synchronous queue subscriber on a given subject of interest. All subscribers with the same queue name will form the queue group and only one member of the group will be selected to receive any given message. MessageHandler must be registered, and AsyncSubscription.start() must be called.

Parameters:

subject - the subject of interest

queue - the queue group

Returns:

the SyncSubscription

Throws:

IllegalArgumentException - if the subject (or queue) name contains illegal characters.

NullPointerException - if the subject name is null

IllegalStateException - if the connection is closed

subscribeSync

SyncSubscription subscribeSync(String subject)

Creates a SyncSubscription with interest in a given subject. In order to receive messages, call one of the available SyncSubscription.nextMessage().

Parameters:

subject - the subject of interest

Returns:

the SyncSubscription

Throws:

IllegalArgumentException - if the subject name contains illegal characters.

NullPointerException - if the subject name is null

IllegalStateException - if the connection is closed

newInbox

String newInbox()

Creates a new, uniquely named inbox with the prefix '_INBOX.'

Returns:

the newly created inbox subject

close

void close()

Closes the connection, also closing all subscriptions on this connection.

When close() is called, the following things happen, in order:

1. The Connection is flushed, and any other pending flushes previously requested by the user are immediately cleared.
2. Message delivery to all active subscriptions is terminated immediately, without regard to any messages that may have been delivered to the client's connection, but not to the relevant subscription(s). Any such undelivered messages are discarded immediately.
3. The DisconnectedCallback, if registered, is invoked.
4. The ClosedCallback, if registered, is invoked.
5. The TCP/IP socket connection to the NATS server is gracefully closed.

Specified by:

close in interface AutoCloseable

See Also:

AutoCloseable.close()

isClosed

boolean isClosed()

Indicates whether the connection has been closed.

Returns:

true if the connection is closed.

isReconnecting

boolean isReconnecting()

Indicates whether the connection is currently reconnecting.

Returns:

whether or not the connection is currently reconnecting

getStats

Statistics getStats()

Retrieves the connection statistics.

Returns:

the statistics for this connection.

See Also:

Statistics

resetStats

void resetStats()

Resets the gathered statistics for this connection.

See Also:

Statistics

getMaxPayload

long getMaxPayload()

Gets the maximum payload size this connection will accept.

Returns:

the maximum message payload size in bytes.

flush

void flush(int timeout)
    throws IOException,
           TimeoutException,
           Exception

Flushes the current connection, waiting up to timeout for successful completion.

Parameters:

timeout - - the connection timeout in milliseconds.

Throws:

IOException - if a connection-related error prevents the flush from completing

TimeoutException - if the connection does not complete within the specified interval

Exception - if some other error occurs

flush

void flush()
    throws IOException,
           Exception

Flushes the current connection, waiting up to 60 seconds for completion.

Throws:

IOException - if a connection-related issue prevented the flush from completing successfully

Exception - if some other error is encountered

See Also:

flush(int)

getExceptionHandler

ExceptionHandler getExceptionHandler()

Returns the connection's asynchronous exception callback.

Returns:

the asynchronous exception handler for this connection

See Also:

ExceptionHandler

setExceptionHandler

void setExceptionHandler(ExceptionHandler exceptionHandler)

Sets the connection's asynchronous exception callback.

Parameters:

exceptionHandler - the asynchronous exception handler to set for this connection

See Also:

ExceptionHandler

getClosedCallback

ClosedCallback getClosedCallback()

Returns the connection closed callback.

Returns:

the connection closed callback for this connection

See Also:

ClosedCallback

setClosedCallback

void setClosedCallback(ClosedCallback cb)

Sets the connection closed callback.

Parameters:

cb - the connection closed callback to set

getDisconnectedCallback

DisconnectedCallback getDisconnectedCallback()

Returns the connection disconnected callback.

Returns:

the disconnected callback for this conection

setDisconnectedCallback

void setDisconnectedCallback(DisconnectedCallback cb)

Sets the connection disconnected callback.

Parameters:

cb - the disconnected callback to set

getReconnectedCallback

ReconnectedCallback getReconnectedCallback()

Returns the connection reconnected callback.

Returns:

the reconnect callback for this connection

setReconnectedCallback

void setReconnectedCallback(ReconnectedCallback cb)

Sets the connection reconnected callback.

Parameters:

cb - the reconnect callback to set for this connection

getConnectedUrl

String getConnectedUrl()

Returns the URL string of the currently connected NATS server.

Returns:

the URL string of the currently connected NATS server.

getConnectedServerId

String getConnectedServerId()

Returns the unique server ID string of the connected server.

Returns:

the unique server ID string of the connected server

getState

Constants.ConnState getState()

Returns the current connection state.

Returns:

the current connection state

See Also:

Constants.ConnState

getConnectedServerInfo

io.nats.client.ServerInfo getConnectedServerInfo()

Returns the details from the INFO protocol message received.

Returns:

the details from the INFO protocol message received from the NATS server on initial establishment of a TCP connection.

See Also:

ServerInfo

getLastException

Exception getLastException()

Returns the last exception registered on the connection.

Returns:

the last exception registered on this connection

getPendingByteCount

int getPendingByteCount()

Returns the number of valid bytes in the pending output buffer. This buffer is only used during disconnect/reconnect sequences to buffer messages that are published during a temporary disconnection.

Returns:

the number of valid bytes in the pending output buffer.