Connection (NATS.IO Java API)

All Superinterfaces:

java.lang.AutoCloseable
```
public interface Connection
extends java.lang.AutoCloseable
```
The Connection class is at the heart of the NATS Java client. Fundamentally a connection represents a single network connection to the NATS server.
Each connection you create will result in the creation of a single socket and several threads:
- A reader thread for taking data off the socket
- A writer thread for putting data onto the socket
- A timer thread for a few maintenance timers
- A dispatch thread to handle request/reply traffic
The connection has a status which can be checked using the getStatus method or watched using a ConnectionListener.
Connections, by default, are configured to try to reconnect to the server if there is a network failure up to times. You can configure this behavior in the Options. Moreover, the options allows you to control whether reconnect happens in the same order every time, and the time to wait if trying to reconnect to the same server over and over.
The list of servers used for connecting is provided by the Options. The list of servers used during reconnect can be an expanded list. This expansion comes from the connections most recent server. For example, if you connect to serverA, it can tell the connection "i know about serverB and serverC". If serverA goes down the client library will try to connect to serverA, serverB and serverC. Now, if the library connects to serverB, it may tell the client "i know about serverB and serverE". The client's list of servers, available from getServers() will now be serverA from the initial connect, serverB and serverE, the reference to serverC is lost.
When a connection is closed the thread and socket resources are cleaned up.
All outgoing messages are sent through the connection object using one of the two publish methods or the request method. When publishing you can specify a reply to subject which can be retrieved by the receiver to respond. The request method will handle this behavior itself, but it relies on getting the value out of a Future so may be less flexible than publish with replyTo set.
Messages can be received in two ways. You can create a Subscription which will allow you to read messages synchronously using the nextMessage method or you can create a Dispatcher. The Dispatcher will create a thread to listen for messages on one or more subscriptions. The Dispatcher groups a set of subscriptions into a single listener thread that calls application code for each messages.
Applications can use the flush method to check that published messages have made it to the server. However, this method initiates a round trip to the server and waits for the response so it should be used sparingly.
The connection provides two listeners via the Options. The ConnectionListener can be used to listen for lifecycle events. This listener is required for connectAsynchronously, but otherwise optional. The ErrorListener provides three callback opportunities including slow consumers, error messages from the server and exceptions handled by the client library. These listeners can only be set at creation time using the options.
Note: The publish methods take an array of bytes. These arrays will not be copied. This design choice is based on the common case of strings or objects being converted to bytes. Once a client can be sure a message was received by the NATS server it is theoretically possible to reuse that byte array, but this pattern should be treated as advanced and only used after thorough testing.

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static class Connection.Status
Enum representing the status of a connection

Nested Classes
Modifier and Type	Interface and Description
`static class`	`Connection.Status` Enum representing the status of a connection

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`addConnectionListener(@NonNull ConnectionListener connectionListener)` Attach another ConnectionListener.
`void`	`clearLastError()` Clear the last error from the server
`void`	`close()` Close the connection and release all blocking calls like `flush` and `nextMessage`.
`void`	`closeDispatcher(@NonNull Dispatcher dispatcher)` Close a dispatcher.
`@NonNull Dispatcher`	`createDispatcher()` Convenience method to create a dispatcher with no default handler.
`@NonNull Dispatcher`	`createDispatcher(@Nullable MessageHandler handler)` Create a `Dispatcher` for this connection.
`@NonNull java.lang.String`	`createInbox()` Create a new inbox subject, can be used for directed replies from subscribers.
`@NonNull java.util.concurrent.CompletableFuture<java.lang.Boolean>`	`drain(@Nullable java.time.Duration timeout)` Drain tells the connection to process in flight messages before closing.
`void`	`flush(@Nullable java.time.Duration timeout)` Flush the connection's buffer of outgoing messages, including sending a protocol message to and from the server.
`void`	`flushBuffer()` Immediately flushes the underlying connection buffer if the connection is valid.
`void`	`forceReconnect()` Forces reconnect behavior.
`void`	`forceReconnect(@Nullable ForceReconnectOptions options)` Forces reconnect behavior.
`@Nullable java.net.InetAddress`	`getClientInetAddress()` the InetAddress of client as known by the NATS server, otherwise null.
`@Nullable java.lang.String`	`getConnectedUrl()` the url used for the current connection, or null if disconnected
`@NonNull ConsumerContext`	`getConsumerContext(@NonNull java.lang.String streamName, @NonNull java.lang.String consumerName)` Get a consumer context for a specific named stream and specific named consumer.
`@NonNull ConsumerContext`	`getConsumerContext(@NonNull java.lang.String streamName, @NonNull java.lang.String consumerName, @Nullable JetStreamOptions options)` Get a consumer context for a specific named stream and specific named consumer.
`@Nullable java.lang.String`	`getLastError()` the error text from the last error sent by the server to this client
`long`	`getMaxPayload()` MaxPayload returns the size limit that a message payload can have.
`@NonNull Options`	`getOptions()` the read-only options used to create this connection
`@NonNull ServerInfo`	`getServerInfo()` Return the server info object.
`@NonNull java.util.Collection<java.lang.String>`	`getServers()` Return the list of known server urls, including additional servers discovered after a connection has been established.
`@NonNull Statistics`	`getStatistics()` a wrapper for useful statistics about the connection
`@NonNull Connection.Status`	`getStatus()` Returns the connections current status.
`@NonNull StreamContext`	`getStreamContext(@NonNull java.lang.String streamName)` Get a stream context for a specific stream.
`@NonNull StreamContext`	`getStreamContext(@NonNull java.lang.String streamName, @Nullable JetStreamOptions options)` Get a stream context for a specific stream
`@NonNull JetStream`	`jetStream()` Gets a context for publishing and subscribing to subjects backed by Jetstream streams and consumers.
`@NonNull JetStream`	`jetStream(@Nullable JetStreamOptions options)` Gets a context for publishing and subscribing to subjects backed by Jetstream streams and consumers.
`@NonNull JetStreamManagement`	`jetStreamManagement()` Gets a context for managing Jetstream streams and consumers.
`@NonNull JetStreamManagement`	`jetStreamManagement(@Nullable JetStreamOptions options)` Gets a context for managing Jetstream streams and consumers.
`@NonNull KeyValue`	`keyValue(@NonNull java.lang.String bucketName)` Gets a context for working with a Key Value bucket
`@NonNull KeyValue`	`keyValue(@NonNull java.lang.String bucketName, @Nullable KeyValueOptions options)` Gets a context for working with a Key Value bucket
`@NonNull KeyValueManagement`	`keyValueManagement()` Gets a context for managing Key Value buckets
`@NonNull KeyValueManagement`	`keyValueManagement(@Nullable KeyValueOptions options)` Gets a context for managing Key Value buckets
`@NonNull ObjectStore`	`objectStore(@NonNull java.lang.String bucketName)` Gets a context for working with an Object Store.
`@NonNull ObjectStore`	`objectStore(@NonNull java.lang.String bucketName, @Nullable ObjectStoreOptions options)` Gets a context for working with an Object Store.
`@NonNull ObjectStoreManagement`	`objectStoreManagement()` Gets a context for managing Object Stores
`@NonNull ObjectStoreManagement`	`objectStoreManagement(ObjectStoreOptions options)` Gets a context for managing Object Stores
`long`	`outgoingPendingBytes()` Get the number of bytes based to be written calculated from the messages in the outgoing queue for this connection.
`long`	`outgoingPendingMessageCount()` Get the number of messages in the outgoing queue for this connection.
`void`	`publish(@NonNull Message message)` Send a message to the specified subject.
`void`	`publish(@NonNull java.lang.String subject, byte[] body)` Send a message to the specified subject.
`void`	`publish(@NonNull java.lang.String subject, @Nullable io.nats.client.impl.Headers headers, byte[] body)` Send a message to the specified subject.
`void`	`publish(@NonNull java.lang.String subject, @Nullable java.lang.String replyTo, byte[] body)` Send a request to the specified subject, providing a replyTo subject.
`void`	`publish(@NonNull java.lang.String subject, @Nullable java.lang.String replyTo, @Nullable io.nats.client.impl.Headers headers, byte[] body)` Send a request to the specified subject, providing a replyTo subject.
`void`	`removeConnectionListener(@NonNull ConnectionListener connectionListener)` Detach a ConnectionListioner.
`@NonNull java.util.concurrent.CompletableFuture<Message>`	`request(@NonNull Message message)` Send a request.
`@Nullable Message`	`request(@NonNull Message message, @Nullable java.time.Duration timeout)` Send a request and returns the reply or null.
`@NonNull java.util.concurrent.CompletableFuture<Message>`	`request(@NonNull java.lang.String subject, byte[] body)` Send a request.
`@Nullable Message`	`request(@NonNull java.lang.String subject, byte[] body, @Nullable java.time.Duration timeout)` Send a request and returns the reply or null.
`@NonNull java.util.concurrent.CompletableFuture<Message>`	`request(@NonNull java.lang.String subject, @Nullable io.nats.client.impl.Headers headers, byte[] body)` Send a request.
`@Nullable Message`	`request(@NonNull java.lang.String subject, @Nullable io.nats.client.impl.Headers headers, byte[] body, @Nullable java.time.Duration timeout)` Send a request and returns the reply or null.
`@NonNull java.util.concurrent.CompletableFuture<Message>`	`requestWithTimeout(@NonNull Message message, @Nullable java.time.Duration timeout)` Send a request.
`@NonNull java.util.concurrent.CompletableFuture<Message>`	`requestWithTimeout(@NonNull java.lang.String subject, byte[] body, @Nullable java.time.Duration timeout)` Send a request.
`@NonNull java.util.concurrent.CompletableFuture<Message>`	`requestWithTimeout(@NonNull java.lang.String subject, @Nullable io.nats.client.impl.Headers headers, byte[] body, java.time.Duration timeout)` Send a request.
`@NonNull java.time.Duration`	`RTT()` Calculates the round trip time between this client and the server.
`@NonNull Subscription`	`subscribe(@NonNull java.lang.String subject)` Create a synchronous subscription to the specified subject.
`@NonNull Subscription`	`subscribe(@NonNull java.lang.String subject, @NonNull java.lang.String queueName)` Create a synchronous subscription to the specified subject and queue.

- Method Detail
  - publish
```
void publish(@NonNull java.lang.String subject,
             byte[] body)
```
    Send a message to the specified subject. The message body will not be copied. The expected usage with string content is something like:
```
 nc = Nats.connect()
 nc.publish("destination", "message".getBytes("UTF-8"))
 
```
    where the sender creates a byte array immediately before calling publish. See publish() for more details on publish during reconnect.
    Parameters:
    
    subject - the subject to send the message to
    
    body - the message body
    
    Throws:
    
    java.lang.IllegalStateException - if the reconnect buffer is exceeded
  - publish
```
void publish(@NonNull java.lang.String subject,
             @Nullable io.nats.client.impl.Headers headers,
             byte[] body)
```
    Send a message to the specified subject. The message body will not be copied. The expected usage with string content is something like:
```
 nc = Nats.connect()
 Headers h = new Headers().put("key", "value");
 nc.publish("destination", h, "message".getBytes("UTF-8"))
 
```
    where the sender creates a byte array immediately before calling publish. See publish() for more details on publish during reconnect.
    Parameters:
    
    subject - the subject to send the message to
    
    headers - Optional headers to publish with the message.
    
    body - the message body
    
    Throws:
    
    java.lang.IllegalStateException - if the reconnect buffer is exceeded
  - publish
```
void publish(@NonNull java.lang.String subject,
             @Nullable java.lang.String replyTo,
             byte[] body)
```
    Send a request to the specified subject, providing a replyTo subject. The message body will not be copied. The expected usage with string content is something like:
```
 nc = Nats.connect()
 nc.publish("destination", "reply-to", "message".getBytes("UTF-8"))
 
```
    where the sender creates a byte array immediately before calling publish.
    During reconnect the client will try to buffer messages. The buffer size is set in the connect options, see reconnectBufferSize() with a default value of 8 * 1024 * 1024 bytes. If the buffer is exceeded an IllegalStateException is thrown. Applications should use this exception as a signal to wait for reconnect before continuing.
    Parameters:
    
    subject - the subject to send the message to
    
    replyTo - the subject the receiver should send any response to
    
    body - the message body
    
    Throws:
    
    java.lang.IllegalStateException - if the reconnect buffer is exceeded
  - publish
```
void publish(@NonNull java.lang.String subject,
             @Nullable java.lang.String replyTo,
             @Nullable io.nats.client.impl.Headers headers,
             byte[] body)
```
    Send a request to the specified subject, providing a replyTo subject. The message body will not be copied. The expected usage with string content is something like:
```
 nc = Nats.connect()
 Headers h = new Headers().put("key", "value");
 nc.publish("destination", "reply-to", h, "message".getBytes("UTF-8"))
 
```
    where the sender creates a byte array immediately before calling publish.
    During reconnect the client will try to buffer messages. The buffer size is set in the connect options, see reconnectBufferSize() with a default value of 8 * 1024 * 1024 bytes. If the buffer is exceeded an IllegalStateException is thrown. Applications should use this exception as a signal to wait for reconnect before continuing.
    Parameters:
    
    subject - the subject to send the message to
    
    replyTo - the subject the receiver should send any response to
    
    headers - Optional headers to publish with the message.
    
    body - the message body
    
    Throws:
    
    java.lang.IllegalStateException - if the reconnect buffer is exceeded
  - publish
```
void publish(@NonNull Message message)
```
    Send a message to the specified subject. The message body will not be copied. The expected usage with string content is something like:
```
 nc = Nats.connect()
 nc.publish(NatsMessage.builder()...build())
 
```
    where the sender creates a byte array immediately before calling publish. See publish() for more details on publish during reconnect.
    Parameters:
    
    message - the message
    
    Throws:
    
    java.lang.IllegalStateException - if the reconnect buffer is exceeded
  - request
```
@NonNull java.util.concurrent.CompletableFuture<Message> request(@NonNull java.lang.String subject,
                                                                 byte[] body)
```
    Send a request. The returned future will be completed when the response comes back.
    
    Parameters:
    
    subject - the subject for the service that will handle the request
    
    body - the content of the message
    
    Returns:
    
    a Future for the response, which may be cancelled on error or timed out
  - request
```
@NonNull java.util.concurrent.CompletableFuture<Message> request(@NonNull java.lang.String subject,
                                                                 @Nullable io.nats.client.impl.Headers headers,
                                                                 byte[] body)
```
    Send a request. The returned future will be completed when the response comes back.
    
    Parameters:
    
    subject - the subject for the service that will handle the request
    
    headers - Optional headers to publish with the message.
    
    body - the content of the message
    
    Returns:
    
    a Future for the response, which may be cancelled on error or timed out
  - requestWithTimeout
```
@NonNull java.util.concurrent.CompletableFuture<Message> requestWithTimeout(@NonNull java.lang.String subject,
                                                                            byte[] body,
                                                                            @Nullable java.time.Duration timeout)
```
    Send a request. The returned future will be completed when the response comes back.
    
    Parameters:
    
    subject - the subject for the service that will handle the request
    
    body - the content of the message
    
    timeout - the time to wait for a response. If not supplied a default will be used.
    
    Returns:
    
    a Future for the response, which may be cancelled on error or timed out
  - requestWithTimeout
```
@NonNull java.util.concurrent.CompletableFuture<Message> requestWithTimeout(@NonNull java.lang.String subject,
                                                                            @Nullable io.nats.client.impl.Headers headers,
                                                                            byte[] body,
                                                                            java.time.Duration timeout)
```
    Send a request. The returned future will be completed when the response comes back.
    
    Parameters:
    
    subject - the subject for the service that will handle the request
    
    body - the content of the message
    
    headers - Optional headers to publish with the message.
    
    timeout - the time to wait for a response
    
    Returns:
    
    a Future for the response, which may be cancelled on error or timed out
  - request
```
@NonNull java.util.concurrent.CompletableFuture<Message> request(@NonNull Message message)
```
    Send a request. The returned future will be completed when the response comes back.
    The Message object allows you to set a replyTo, but in requests, the replyTo is reserved for internal use as the address for the server to respond to the client with the consumer's reply.
    
    Parameters:
    
    message - the message
    
    Returns:
    
    a Future for the response, which may be cancelled on error or timed out
  - requestWithTimeout
```
@NonNull java.util.concurrent.CompletableFuture<Message> requestWithTimeout(@NonNull Message message,
                                                                            @Nullable java.time.Duration timeout)
```
    Send a request. The returned future will be completed when the response comes back.
    The Message object allows you to set a replyTo, but in requests, the replyTo is reserved for internal use as the address for the server to respond to the client with the consumer's reply.
    
    Parameters:
    
    message - the message
    
    timeout - the time to wait for a response
    
    Returns:
    
    a Future for the response, which may be cancelled on error or timed out
  - request
```
@Nullable Message request(@NonNull java.lang.String subject,
                          byte[] body,
                          @Nullable java.time.Duration timeout)
                   throws java.lang.InterruptedException
```
    Send a request and returns the reply or null. This version of request is equivalent to calling get on the future returned from request() with the timeout and handling the ExecutionException and TimeoutException.
    
    Parameters:
    
    subject - the subject for the service that will handle the request
    
    body - the content of the message
    
    timeout - the time to wait for a response
    
    Returns:
    
    the reply message or null if the timeout is reached
    
    Throws:
    
    java.lang.InterruptedException - if one is thrown while waiting, in order to propagate it up
  - request
```
@Nullable Message request(@NonNull java.lang.String subject,
                          @Nullable io.nats.client.impl.Headers headers,
                          byte[] body,
                          @Nullable java.time.Duration timeout)
                   throws java.lang.InterruptedException
```
    Send a request and returns the reply or null. This version of request is equivalent to calling get on the future returned from request() with the timeout and handling the ExecutionException and TimeoutException.
    
    Parameters:
    
    subject - the subject for the service that will handle the request
    
    headers - Optional headers to publish with the message.
    
    body - the content of the message
    
    timeout - the time to wait for a response
    
    Returns:
    
    the reply message or null if the timeout is reached
    
    Throws:
    
    java.lang.InterruptedException - if one is thrown while waiting, in order to propagate it up
  - request
```
@Nullable Message request(@NonNull Message message,
                          @Nullable java.time.Duration timeout)
                   throws java.lang.InterruptedException
```
    Send a request and returns the reply or null. This version of request is equivalent to calling get on the future returned from request() with the timeout and handling the ExecutionException and TimeoutException.
    The Message object allows you to set a replyTo, but in requests, the replyTo is reserved for internal use as the address for the server to respond to the client with the consumer's reply.
    
    Parameters:
    
    message - the message
    
    timeout - the time to wait for a response
    
    Returns:
    
    the reply message or null if the timeout is reached
    
    Throws:
    
    java.lang.InterruptedException - if one is thrown while waiting, in order to propagate it up
  - subscribe
```
@NonNull Subscription subscribe(@NonNull java.lang.String subject)
```
    Create a synchronous subscription to the specified subject.
    Use the nextMessage method to read messages for this subscription.
    See createDispatcher for information about creating an asynchronous subscription with callbacks.
    As of 2.6.1 this method will throw an IllegalArgumentException if the subject contains whitespace.
    
    Parameters:
    
    subject - the subject to subscribe to
    
    Returns:
    
    an object representing the subscription
  - subscribe
```
@NonNull Subscription subscribe(@NonNull java.lang.String subject,
                                @NonNull java.lang.String queueName)
```
    Create a synchronous subscription to the specified subject and queue.
    Use the nextMessage method to read messages for this subscription.
    See createDispatcher for information about creating an asynchronous subscription with callbacks.
    As of 2.6.1 this method will throw an IllegalArgumentException if either string contains whitespace.
    
    Parameters:
    
    subject - the subject to subscribe to
    
    queueName - the queue group to join
    
    Returns:
    
    an object representing the subscription
  - createDispatcher
```
@NonNull Dispatcher createDispatcher(@Nullable MessageHandler handler)
```
    Create a Dispatcher for this connection. The dispatcher can group one or more subscriptions into a single callback thread. All messages go to the same MessageHandler.
    Use the Dispatcher's Dispatcher.subscribe(String) and Dispatcher.subscribe(String, String) methods to add subscriptions.
```
 nc = Nats.connect()
 d = nc.createDispatcher((m) -> System.out.println(m)).subscribe("hello");
 
```
    Parameters:
    
    handler - The target for the messages. If the handler is null, subscribing without using its API that accepts a handler will discard messages.
    
    Returns:
    
    a new Dispatcher
  - createDispatcher
```
@NonNull Dispatcher createDispatcher()
```
    Convenience method to create a dispatcher with no default handler. Only used with JetStream push subscriptions that require specific handlers per subscription.
    
    Returns:
    
    a new Dispatcher
  - closeDispatcher
```
void closeDispatcher(@NonNull Dispatcher dispatcher)
```
    Close a dispatcher. This will unsubscribe any subscriptions and stop the delivery thread.
    Once closed the dispatcher will throw an exception on subsequent subscribe or unsubscribe calls.
    
    Parameters:
    
    dispatcher - the dispatcher to close
  - addConnectionListener
```
void addConnectionListener(@NonNull ConnectionListener connectionListener)
```
    Attach another ConnectionListener.
    The ConnectionListener will only receive Connection events arriving after it has been attached. When a Connection event is raised, the invocation order and parallelism of multiple ConnectionListeners is not specified.
    
    Parameters:
    
    connectionListener - the ConnectionListener to attach. A null listener is a no-op
  - removeConnectionListener
```
void removeConnectionListener(@NonNull ConnectionListener connectionListener)
```
    Detach a ConnectionListioner. This will cease delivery of any further Connection events to this instance.
    
    Parameters:
    
    connectionListener - the ConnectionListener to detach
  - flush
```
void flush(@Nullable java.time.Duration timeout)
    throws java.util.concurrent.TimeoutException,
           java.lang.InterruptedException
```
    Flush the connection's buffer of outgoing messages, including sending a protocol message to and from the server. Passing null is equivalent to passing 0, which will wait forever. If called while the connection is closed, this method will immediately throw a TimeoutException, regardless of the timeout. If called while the connection is disconnected due to network issues this method will wait for up to the timeout for a reconnect or close.
    
    Parameters:
    
    timeout - The time to wait for the flush to succeed, pass 0 or null to wait forever.
    
    Throws:
    
    java.util.concurrent.TimeoutException - if the timeout is exceeded
    
    java.lang.InterruptedException - if the underlying thread is interrupted
  - drain
```
@NonNull java.util.concurrent.CompletableFuture<java.lang.Boolean> drain(@Nullable java.time.Duration timeout)
                                                                  throws java.util.concurrent.TimeoutException,
                                                                         java.lang.InterruptedException
```
    Drain tells the connection to process in flight messages before closing. Drain initially drains all the consumers, stopping incoming messages. Next, publishing is halted and a flush call is used to insure all published messages have reached the server. Finally, the connection is closed. In order to drain subscribers, an unsub protocol message is sent to the server followed by a flush. These two steps occur before drain returns. The remaining steps occur in a background thread. This method tries to manage the timeout properly, so that if the timeout is 1 second, and the flush takes 100ms, the remaining steps have 900ms in the background thread. The connection will try to let all messages be drained, but when the timeout is reached the connection is closed and any outstanding dispatcher threads are interrupted. A future allows this call to be treated as synchronous or asynchronous as needed by the application. The value of the future will be true if all the subscriptions were drained in the timeout, and false otherwise. The future completes after the connection is closed, so any connection handler notifications will happen before the future completes.
    
    Parameters:
    
    timeout - The time to wait for the drain to succeed, pass 0 or null to wait forever. Drain involves moving messages to and from the server so a very short timeout is not recommended. If the timeout is reached before the drain completes, the connection is simply closed, which can result in message loss.
    
    Returns:
    
    A future that can be used to check if the drain has completed
    
    Throws:
    
    java.lang.InterruptedException - if the thread is interrupted
    
    java.util.concurrent.TimeoutException - if the initial flush times out
  - close
```
void close()
    throws java.lang.InterruptedException
```
    Close the connection and release all blocking calls like flush and nextMessage. If close() is called after drain it will wait up to the connection timeout to return, but it will not initiate a close. The drain takes precedence and will initiate the close.
    
    Specified by:
    
    close in interface java.lang.AutoCloseable
    
    Throws:
    
    java.lang.InterruptedException - if the thread, or one owned by the connection is interrupted during the close
  - getStatus
```
@NonNull Connection.Status getStatus()
```
    Returns the connections current status.
    
    Returns:
    
    the connection's status
  - getMaxPayload
```
long getMaxPayload()
```
    MaxPayload returns the size limit that a message payload can have. This is set by the server configuration and delivered to the client upon connect.
    
    Returns:
    
    the maximum size of a message payload
  - getServers
```
@NonNull java.util.Collection<java.lang.String> getServers()
```
    Return the list of known server urls, including additional servers discovered after a connection has been established. Will be empty (but not null) before a connection is made and will represent the last connected server while disconnected
    
    Returns:
    
    this connection's list of known server URLs
  - getStatistics
```
@NonNull Statistics getStatistics()
```
    a wrapper for useful statistics about the connection
    
    Returns:
    
    the Statistics implementation
  - getOptions
```
@NonNull Options getOptions()
```
    the read-only options used to create this connection
    
    Returns:
    
    the Options
  - getServerInfo
```
@NonNull ServerInfo getServerInfo()
```
    Return the server info object. Will never be null, but will be an instance of ServerInfo.EMPTY_INFO before a connection is made, and will represent the last connected server once connected and while disconnected until a new connection is made.
    
    Returns:
    
    the server information such as id, client info, etc.
  - getConnectedUrl
```
@Nullable java.lang.String getConnectedUrl()
```
    the url used for the current connection, or null if disconnected
    
    Returns:
    
    the url string
  - getClientInetAddress
```
@Nullable java.net.InetAddress getClientInetAddress()
```
    the InetAddress of client as known by the NATS server, otherwise null.
    
    Returns:
    
    the InetAddress
  - getLastError
```
@Nullable java.lang.String getLastError()
```
    the error text from the last error sent by the server to this client
    
    Returns:
    
    the last error text
  - clearLastError
```
void clearLastError()
```
    Clear the last error from the server
  - createInbox
```
@NonNull java.lang.String createInbox()
```
    Create a new inbox subject, can be used for directed replies from subscribers. These are guaranteed to be unique, but can be shared and subscribed to by others.
    
    Returns:
    
    the inbox
  - flushBuffer
```
void flushBuffer()
          throws java.io.IOException
```
    Immediately flushes the underlying connection buffer if the connection is valid.
    
    Throws:
    
    java.io.IOException - if the connection flush fails
  - forceReconnect
```
void forceReconnect()
             throws java.io.IOException,
                    java.lang.InterruptedException
```
    Forces reconnect behavior. Stops the current connection including the reading and writing, copies already queued outgoing messages, and then begins the reconnect logic. Does not flush. Does not force close the connection. See ForceReconnectOptions.
    
    Throws:
    
    java.io.IOException - the forceReconnect fails
    
    java.lang.InterruptedException - the connection is not connected
  - forceReconnect
```
void forceReconnect(@Nullable ForceReconnectOptions options)
             throws java.io.IOException,
                    java.lang.InterruptedException
```
    Forces reconnect behavior. Stops the current connection including the reading and writing, copies already queued outgoing messages, and then begins the reconnect logic. If options are not provided, the default options are used meaning Does not flush and Does not force close the connection. See ForceReconnectOptions.
    
    Parameters:
    
    options - options for how the forceReconnect works.
    
    Throws:
    
    java.io.IOException - the forceReconnect fails
    
    java.lang.InterruptedException - the connection is not connected
  - RTT
```
@NonNull java.time.Duration RTT()
                         throws java.io.IOException
```
    Calculates the round trip time between this client and the server.
    
    Returns:
    
    the RTT as a duration
    
    Throws:
    
    java.io.IOException - various IO exception such as timeout or interruption
  - getStreamContext
```
@NonNull StreamContext getStreamContext(@NonNull java.lang.String streamName)
                                 throws java.io.IOException,
                                        JetStreamApiException
```
    Get a stream context for a specific stream.
    Recommended: See getStreamContext(String, JetStreamOptions)
    
    Parameters:
    
    streamName - the stream for the context
    
    Returns:
    
    a StreamContext instance.
    
    Throws:
    
    java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption
    
    JetStreamApiException - the request had an error related to the data
  - getStreamContext
```
@NonNull StreamContext getStreamContext(@NonNull java.lang.String streamName,
                                        @Nullable JetStreamOptions options)
                                 throws java.io.IOException,
                                        JetStreamApiException
```
    Get a stream context for a specific stream
    Recommended: StreamContext and ConsumerContext are the preferred way to interact with existing streams and consume from streams. JetStreamManagement should be used to create streams and consumers. ConsumerContext.consume() supports both push and pull consumers transparently.
```
 nc = Nats.connect();
 StreamContext streamContext = nc.getStreamContext("my-stream");
 ConsumerContext consumerContext = streamContext.getConsumerContext("my-consumer");
 // Or directly: 
 // ConsumerContext consumerContext = nc.getConsumerContext("my-stream", "my-consumer"); 
 consumerContext.consume(
        msg -> {
             System.out.println("   Received " + msg.getSubject());
             msg.ack();
           });
           
```
    Parameters:
    
    streamName - the stream for the context
    
    options - JetStream options. If null, default / no options are used.
    
    Returns:
    
    a StreamContext instance.
    
    Throws:
    
    java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption
    
    JetStreamApiException - the request had an error related to the data
  - getConsumerContext
```
@NonNull ConsumerContext getConsumerContext(@NonNull java.lang.String streamName,
                                            @NonNull java.lang.String consumerName)
                                     throws java.io.IOException,
                                            JetStreamApiException
```
    Get a consumer context for a specific named stream and specific named consumer. Verifies that the stream and consumer exist.
    Recommended: See getStreamContext(String, JetStreamOptions)
    
    Parameters:
    
    streamName - the name of the stream
    
    consumerName - the name of the consumer
    
    Returns:
    
    a ConsumerContext object
    
    Throws:
    
    java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption
    
    JetStreamApiException - the request had an error related to the data
  - getConsumerContext
```
@NonNull ConsumerContext getConsumerContext(@NonNull java.lang.String streamName,
                                            @NonNull java.lang.String consumerName,
                                            @Nullable JetStreamOptions options)
                                     throws java.io.IOException,
                                            JetStreamApiException
```
    Get a consumer context for a specific named stream and specific named consumer. Verifies that the stream and consumer exist.
    Recommended: See getStreamContext(String, JetStreamOptions)
    
    Parameters:
    
    streamName - the name of the stream
    
    consumerName - the name of the consumer
    
    options - JetStream options. If null, default / no options are used.
    
    Returns:
    
    a ConsumerContext object
    
    Throws:
    
    java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption
    
    JetStreamApiException - the request had an error related to the data
  - jetStream
```
@NonNull JetStream jetStream()
                      throws java.io.IOException
```
    Gets a context for publishing and subscribing to subjects backed by Jetstream streams and consumers.
    
    Returns:
    
    a JetStream instance.
    
    Throws:
    
    java.io.IOException - various IO exception such as timeout or interruption
  - jetStream
```
@NonNull JetStream jetStream(@Nullable JetStreamOptions options)
                      throws java.io.IOException
```
    Gets a context for publishing and subscribing to subjects backed by Jetstream streams and consumers.
    
    Parameters:
    
    options - JetStream options. If null, default / no options are used.
    
    Returns:
    
    a JetStream instance.
    
    Throws:
    
    java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption
  - jetStreamManagement
```
@NonNull JetStreamManagement jetStreamManagement()
                                          throws java.io.IOException
```
    Gets a context for managing Jetstream streams and consumers.
    
    Returns:
    
    a JetStreamManagement instance.
    
    Throws:
    
    java.io.IOException - various IO exception such as timeout or interruption
  - jetStreamManagement
```
@NonNull JetStreamManagement jetStreamManagement(@Nullable JetStreamOptions options)
                                          throws java.io.IOException
```
    Gets a context for managing Jetstream streams and consumers.
    
    Parameters:
    
    options - JetStream options. If null, default / no options are used.
    
    Returns:
    
    a JetStreamManagement instance.
    
    Throws:
    
    java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption
  - keyValue
```
@NonNull KeyValue keyValue(@NonNull java.lang.String bucketName)
                    throws java.io.IOException
```
    Gets a context for working with a Key Value bucket
    
    Parameters:
    
    bucketName - the bucket name
    
    Returns:
    
    a KeyValue instance.
    
    Throws:
    
    java.io.IOException - various IO exception such as timeout or interruption
  - keyValue
```
@NonNull KeyValue keyValue(@NonNull java.lang.String bucketName,
                           @Nullable KeyValueOptions options)
                    throws java.io.IOException
```
    Gets a context for working with a Key Value bucket
    
    Parameters:
    
    bucketName - the bucket name
    
    options - KeyValue options. If null, default / no options are used.
    
    Returns:
    
    a KeyValue instance.
    
    Throws:
    
    java.io.IOException - various IO exception such as timeout or interruption
  - keyValueManagement
```
@NonNull KeyValueManagement keyValueManagement()
                                        throws java.io.IOException
```
    Gets a context for managing Key Value buckets
    
    Returns:
    
    a KeyValueManagement instance.
    
    Throws:
    
    java.io.IOException - various IO exception such as timeout or interruption
  - keyValueManagement
```
@NonNull KeyValueManagement keyValueManagement(@Nullable KeyValueOptions options)
                                        throws java.io.IOException
```
    Gets a context for managing Key Value buckets
    
    Parameters:
    
    options - KeyValue options. If null, default / no options are used.
    
    Returns:
    
    a KeyValueManagement instance.
    
    Throws:
    
    java.io.IOException - various IO exception such as timeout or interruption
  - objectStore
```
@NonNull ObjectStore objectStore(@NonNull java.lang.String bucketName)
                          throws java.io.IOException
```
    Gets a context for working with an Object Store.
    
    Parameters:
    
    bucketName - the bucket name
    
    Returns:
    
    an ObjectStore instance.
    
    Throws:
    
    java.io.IOException - various IO exception such as timeout or interruption
  - objectStore
```
@NonNull ObjectStore objectStore(@NonNull java.lang.String bucketName,
                                 @Nullable ObjectStoreOptions options)
                          throws java.io.IOException
```
    Gets a context for working with an Object Store.
    
    Parameters:
    
    bucketName - the bucket name
    
    options - ObjectStore options. If null, default / no options are used.
    
    Returns:
    
    an ObjectStore instance.
    
    Throws:
    
    java.io.IOException - various IO exception such as timeout or interruption
  - objectStoreManagement
```
@NonNull ObjectStoreManagement objectStoreManagement()
                                              throws java.io.IOException
```
    Gets a context for managing Object Stores
    
    Returns:
    
    an ObjectStoreManagement instance.
    
    Throws:
    
    java.io.IOException - various IO exception such as timeout or interruption
  - objectStoreManagement
```
@NonNull ObjectStoreManagement objectStoreManagement(ObjectStoreOptions options)
                                              throws java.io.IOException
```
    Gets a context for managing Object Stores
    
    Parameters:
    
    options - ObjectStore options. If null, default / no options are used.
    
    Returns:
    
    a ObjectStoreManagement instance.
    
    Throws:
    
    java.io.IOException - various IO exception such as timeout or interruption
  - outgoingPendingMessageCount
```
long outgoingPendingMessageCount()
```
    Get the number of messages in the outgoing queue for this connection. This value is volatile in the sense that it changes often and may be adjusted by more than one message. It changes every time a message is published (put in the outgoing queue) and every time a message is removed from the queue to be written over the socket
    
    Returns:
    
    the number of messages in the outgoing queue
  - outgoingPendingBytes
```
long outgoingPendingBytes()
```
    Get the number of bytes based to be written calculated from the messages in the outgoing queue for this connection. This value is volatile in the sense that it changes often and may be adjusted by more than one message's bytes. It changes every time a message is published (put in the outgoing queue) and every time a message is removed from the queue to be written over the socket
    
    Returns:
    
    the number of messages in the outgoing queue

Interface Connection

Nested Class Summary

Method Summary

Method Detail

publish

publish

publish

publish

publish

request

request

requestWithTimeout

requestWithTimeout

request

requestWithTimeout

request

request

request

subscribe

subscribe

createDispatcher

createDispatcher

closeDispatcher

addConnectionListener

removeConnectionListener

flush

drain

close

getStatus

getMaxPayload

getServers

getStatistics

getOptions

getServerInfo

getConnectedUrl

getClientInetAddress

getLastError

clearLastError

createInbox

flushBuffer

forceReconnect

forceReconnect

RTT

getStreamContext

getStreamContext

getConsumerContext

getConsumerContext

jetStream

jetStream

jetStreamManagement

jetStreamManagement

keyValue

keyValue

keyValueManagement

keyValueManagement

objectStore

objectStore

objectStoreManagement

objectStoreManagement

outgoingPendingMessageCount

outgoingPendingBytes