Package io.nats.client

Class Options

  • public class Options
extends java.lang.Object
    The Options class specifies the connection options for a new NATs connection, including the default options. Options are created using a Builder. This class, and the builder associated with it, is basically a long list of parameters. The documentation attempts to clarify the value of each parameter in place on the builder and here, but it may be easier to read the documentation starting with the Builder, since it has a simple list of methods that configure the connection.

    • Field Detail

      • DEFAULT_URL

        public static final java.lang.String DEFAULT_URL
        Default server URL.

        This property is defined as "nats://localhost:4222"

        See Also:
        Constant Field Values

      • DEFAULT_PORT

        public static final int DEFAULT_PORT
        Default server port.

        This property is defined as 4222

        See Also:
        Constant Field Values

      • DEFAULT_MAX_RECONNECT

        public static final int DEFAULT_MAX_RECONNECT
        Default maximum number of reconnect attempts, see getMaxReconnect().

        This property is defined as 60

        See Also:
        Constant Field Values

      • DEFAULT_RECONNECT_WAIT

        public static final java.time.Duration DEFAULT_RECONNECT_WAIT
        Default wait time before attempting reconnection to the same server, see getReconnectWait().

        This property is defined as 2 seconds.

      • DEFAULT_CONNECTION_TIMEOUT

        public static final java.time.Duration DEFAULT_CONNECTION_TIMEOUT
        Default connection timeout, see getConnectionTimeout().

        This property is defined as 2 seconds.}

      • DEFAULT_PING_INTERVAL

        public static final java.time.Duration DEFAULT_PING_INTERVAL
        Default server ping interval. The client will send a ping to the server on this interval to insure liveness. The server may send pings to the client as well, these are handled automatically by the library , see getPingInterval().

        A value of <=0 means disabled.

        This property is defined as 2 minutes.

      • DEFAULT_REQUEST_CLEANUP_INTERVAL

        public static final java.time.Duration DEFAULT_REQUEST_CLEANUP_INTERVAL
        Default interval to clean up cancelled/timed out requests. A timer is used to clean up futures that were handed out but never completed via a message, getRequestCleanupInterval().

        This property is defined as 5 seconds.

      • DEFAULT_MAX_PINGS_OUT

        public static final int DEFAULT_MAX_PINGS_OUT
        Default maximum number of pings have not received a response allowed by the client, getMaxPingsOut().

        This property is defined as 2

        See Also:
        Constant Field Values

      • DEFAULT_SSL_PROTOCOL

        public static final java.lang.String DEFAULT_SSL_PROTOCOL
        Default SSL protocol used to create an SSLContext if the secure property is used.

        This property is defined as "TLSv1.2"

        See Also:
        Constant Field Values

      • DEFAULT_RECONNECT_BUF_SIZE

        public static final int DEFAULT_RECONNECT_BUF_SIZE
        Default of pending message buffer that is used for buffering messages that are published during a disconnect/reconnect, getReconnectBufferSize().

        This property is defined as 8388608 bytes, 8 * 1024 * 1024.

        See Also:
        Constant Field Values

      • DEFAULT_MAX_CONTROL_LINE

        public static final int DEFAULT_MAX_CONTROL_LINE
        The default length, 1024 bytes, the client will allow in an outgoing protocol control line, getMaxControlLine().

        This value is configurable on the server, and should be set here to match.

        See Also:
        Constant Field Values

      • DEFAULT_DATA_PORT_TYPE

        public static final java.lang.String DEFAULT_DATA_PORT_TYPE
        Default dataport class, which will use a TCP socket, getDataPortType().

        This option is currently provided only for testing, and experimentation, the default should be used in almost all cases.

      • DEFAULT_BUFFER_SIZE

        public static final int DEFAULT_BUFFER_SIZE
        Default size for buffers in the connection, not as available as other settings, this is primarily changed for testing, getBufferSize().
        See Also:
        Constant Field Values

      • DEFAULT_THREAD_NAME_PREFIX

        public static final java.lang.String DEFAULT_THREAD_NAME_PREFIX
        Default thread name prefix. Used by the default exectuor when creating threads.

        This property is defined as "nats"

        See Also:
        Constant Field Values

      • DEFAULT_INBOX_PREFIX

        public static final java.lang.String DEFAULT_INBOX_PREFIX
        Default prefix used for inboxes, you can change this to manage authorization of subjects. See getInboxPrefix(), the . is required but will be added if missing.
        See Also:
        Constant Field Values

      • MAX_MESSAGES_IN_NETWORK_BUFFER

        public static final int MAX_MESSAGES_IN_NETWORK_BUFFER
        This value is used internally to limit the number of messages sent in a single network I/O. The value returned by getBufferSize() is used first, but if the buffer size is large and the message sizes are small, this limit comes into play. The choice of 1000 is arbitrary and based on testing across several operating systems. Use buffer size for tuning.
        See Also:
        Constant Field Values

      • MAX_MESSAGES_IN_OUTGOING_QUEUE

        public static final int MAX_MESSAGES_IN_OUTGOING_QUEUE
        This value is used internally to limit the number of messages allowed in the outgoing queue. When this limit is reached, publish requests will be blocked until the queue can clear. Because this value is in messages, the memory size associated with this value depends on the actual size of messages. If 0 byte messages are used, then MAX_MESSAGES_IN_OUTGOING_QUEUE will take up the minimal space. If 1024 byte messages are used then approximately 5Mb is used for the queue (plus overhead for subjects, etc..) We are using messages, not bytes, to allow a simplification in the underlying library, and use LinkedBlockingQueue as the core element in the queue.
        See Also:
        Constant Field Values

      • PROP_CONNECTION_CB

        public static final java.lang.String PROP_CONNECTION_CB
        Property used to configure a builder from a Properties object. "io.nats.client.callback.connection", see connectionListener.
        See Also:
        Constant Field Values

      • PROP_DATA_PORT_TYPE

        public static final java.lang.String PROP_DATA_PORT_TYPE
        Property used to configure a builder from a Properties object. "io.nats.client.dataport.type", see dataPortType.
        See Also:
        Constant Field Values

      • PROP_ERROR_LISTENER

        public static final java.lang.String PROP_ERROR_LISTENER
        Property used to configure a builder from a Properties object. "io.nats.client.callback.error", see errorListener.
        See Also:
        Constant Field Values

      • PROP_MAX_PINGS

        public static final java.lang.String PROP_MAX_PINGS
        Property used to configure a builder from a Properties object. "io.nats.client.maxpings", see maxPingsOut.
        See Also:
        Constant Field Values

      • PROP_PING_INTERVAL

        public static final java.lang.String PROP_PING_INTERVAL
        Property used to configure a builder from a Properties object. "io.nats.client.pinginterval", see pingInterval.
        See Also:
        Constant Field Values

      • PROP_CLEANUP_INTERVAL

        public static final java.lang.String PROP_CLEANUP_INTERVAL
        Property used to configure a builder from a Properties object. "io.nats.client.cleanupinterval", see requestCleanupInterval.
        See Also:
        Constant Field Values

      • PROP_CONNECTION_TIMEOUT

        public static final java.lang.String PROP_CONNECTION_TIMEOUT
        Property used to configure a builder from a Properties object. "io.nats.client.timeout", see connectionTimeout.
        See Also:
        Constant Field Values

      • PROP_RECONNECT_BUF_SIZE

        public static final java.lang.String PROP_RECONNECT_BUF_SIZE
        Property used to configure a builder from a Properties object. "io.nats.client.reconnect.buffer.size", see reconnectBufferSize.
        See Also:
        Constant Field Values

      • PROP_RECONNECT_WAIT

        public static final java.lang.String PROP_RECONNECT_WAIT
        Property used to configure a builder from a Properties object. "io.nats.client.reconnect.wait", see reconnectWait.
        See Also:
        Constant Field Values

      • PROP_MAX_RECONNECT

        public static final java.lang.String PROP_MAX_RECONNECT
        Property used to configure a builder from a Properties object. "io.nats.client.reconnect.max", see maxReconnects.
        See Also:
        Constant Field Values

      • PROP_PEDANTIC

        public static final java.lang.String PROP_PEDANTIC
        Property used to configure a builder from a Properties object. "io.nats.client.pedantic", see pedantic.
        See Also:
        Constant Field Values

      • PROP_VERBOSE

        public static final java.lang.String PROP_VERBOSE
        Property used to configure a builder from a Properties object. "io.nats.client.verbose", see verbose.
        See Also:
        Constant Field Values

      • PROP_NO_ECHO

        public static final java.lang.String PROP_NO_ECHO
        Property used to configure a builder from a Properties object. "io.nats.client.noecho", see noEcho.
        See Also:
        Constant Field Values

      • PROP_CONNECTION_NAME

        public static final java.lang.String PROP_CONNECTION_NAME
        Property used to configure a builder from a Properties object. "io.nats.client.name", see connectionName.
        See Also:
        Constant Field Values

      • PROP_NORANDOMIZE

        public static final java.lang.String PROP_NORANDOMIZE
        Property used to configure a builder from a Properties object. "io.nats.client.norandomize", see noRandomize.
        See Also:
        Constant Field Values

      • PROP_SERVERS

        public static final java.lang.String PROP_SERVERS
        Property used to configure a builder from a Properties object. "io.nats.client.servers", see servers. The value can be a comma-separated list of server URLs.
        See Also:
        Constant Field Values

      • PROP_PASSWORD

        public static final java.lang.String PROP_PASSWORD
        Property used to configure a builder from a Properties object. "io.nats.client.password", see userInfo.
        See Also:
        Constant Field Values

      • PROP_USERNAME

        public static final java.lang.String PROP_USERNAME
        Property used to configure a builder from a Properties object. "io.nats.client.username", see userInfo.
        See Also:
        Constant Field Values

      • PROP_TOKEN

        public static final java.lang.String PROP_TOKEN
        Property used to configure a builder from a Properties object. "io.nats.client.token", see token.
        See Also:
        Constant Field Values

      • PROP_URL

        public static final java.lang.String PROP_URL
        Property used to configure a builder from a Properties object. "io.nats.client.url", see server.
        See Also:
        Constant Field Values

      • PROP_SECURE

        public static final java.lang.String PROP_SECURE
        Property used to configure a builder from a Properties object. "io.nats.client.secure", see sslContext. This property is a boolean flag, but it tells the options parser to use the default SSL context. Set the default context before creating the options.
        See Also:
        Constant Field Values

      • PROP_OPENTLS

        public static final java.lang.String PROP_OPENTLS
        Property used to configure a builder from a Properties object. "io.nats.client.opentls", see sslContext. This property is a boolean flag, but it tells the options parser to use the an SSL context that takes any server TLS certificate and does not provide its own. The server must have tls_verify turned OFF for this option to work.
        See Also:
        Constant Field Values

      • PROP_USE_OLD_REQUEST_STYLE

        public static final java.lang.String PROP_USE_OLD_REQUEST_STYLE
        Property used to configure a builder from a Properties object. "use.old.request.style", see oldRequestStyle.
        See Also:
        Constant Field Values

      • PROP_MAX_CONTROL_LINE

        public static final java.lang.String PROP_MAX_CONTROL_LINE
        Property used to configure a builder from a Properties object. "max.control.line", see maxControlLine.
        See Also:
        Constant Field Values

      • PROP_INBOX_PREFIX

        public static final java.lang.String PROP_INBOX_PREFIX
        Property used to set the inbox prefix
        See Also:
        Constant Field Values

    • Method Detail

      • getExecutor

        public java.util.concurrent.ExecutorService getExecutor()
        Returns:
        the executor, see executor() in the builder doc

      • getAuthHandler

        public AuthHandler getAuthHandler()
        Returns:
        the auth handler, or null, see authHandler() in the builder doc

      • getDataPortType

        public java.lang.String getDataPortType()
        Returns:
        the dataport type for connections created by this options object, see dataPortType() in the builder doc

      • buildDataPort

        public io.nats.client.impl.DataPort buildDataPort()
        Returns:
        the data port described by these options

      • getServers

        public java.util.Collection<java.net.URI> getServers()
        Returns:
        the servers stored in this options, see servers() in the builder doc

      • isNoRandomize

        public boolean isNoRandomize()
        Returns:
        should we turn off randomization for server connection attempts, see noRandomize() in the builder doc

      • supportUTF8Subjects

        public boolean supportUTF8Subjects()
        Returns:
        whether or not utf8 subjects are supported, see supportUTF8Subjects() in the builder doc.

      • getConnectionName

        public java.lang.String getConnectionName()
        Returns:
        the connectionName, see connectionName() in the builder doc

      • isVerbose

        public boolean isVerbose()
        Returns:
        are we in verbose mode, see verbose() in the builder doc

      • isNoEcho

        public boolean isNoEcho()
        Returns:
        is echo-ing disabled, see noEcho() in the builder doc

      • isPedantic

        public boolean isPedantic()
        Returns:
        are we using pedantic protocol, see pedantic() in the builder doc

      • isTrackAdvancedStats

        public boolean isTrackAdvancedStats()
        Returns:
        should we track advanced stats, see turnOnAdvancedStats() in the builder doc

      • isTraceConnection

        public boolean isTraceConnection()
        Returns:
        should we trace the connection process to system.out

      • getMaxControlLine

        public int getMaxControlLine()
        Returns:
        the maximum length of a control line, see maxControlLine() in the builder doc

      • isTLSRequired

        public boolean isTLSRequired()
        Returns:
        true if there is an sslContext for this Options, otherwise false, see secure() in the builder doc

      • getSslContext

        public javax.net.ssl.SSLContext getSslContext()
        Returns:
        the sslContext, see secure() in the builder doc

      • getMaxReconnect

        public int getMaxReconnect()
        Returns:
        the maxReconnect attempts to make before failing, see maxReconnects() in the builder doc

      • getReconnectWait

        public java.time.Duration getReconnectWait()
        Returns:
        the reconnectWait, used between reconnect attempts to the same server, see reconnectWait() in the builder doc

      • getConnectionTimeout

        public java.time.Duration getConnectionTimeout()
        Returns:
        the connectionTimeout, see connectionTimeout() in the builder doc

      • getPingInterval

        public java.time.Duration getPingInterval()
        Returns:
        the pingInterval, see pingInterval() in the builder doc

      • getRequestCleanupInterval

        public java.time.Duration getRequestCleanupInterval()
        Returns:
        the request cleanup interval, see requestCleanupInterval() in the builder doc

      • getMaxPingsOut

        public int getMaxPingsOut()
        Returns:
        the maxPingsOut to limit the number of pings on the wire, see maxPingsOut() in the builder doc

      • getReconnectBufferSize

        public long getReconnectBufferSize()
        Returns:
        the reconnectBufferSize, to limit the amount of data held during reconnection attempts, see reconnectBufferSize() in the builder doc

      • getBufferSize

        public int getBufferSize()
        Returns:
        the default size for buffers in the connection code, see bufferSize() in the builder doc

      • getUsername

        @Deprecated
public java.lang.String getUsername()
        Deprecated.
        converts the char array to a string, use getUserNameChars instead for more security
        Returns:
        the username to use for basic authentication, see userInfo() in the builder doc

      • getUsernameChars

        public char[] getUsernameChars()
        Returns:
        the username to use for basic authentication, see userInfo() in the builder doc

      • getPassword

        @Deprecated
public java.lang.String getPassword()
        Deprecated.
        converts the char array to a string, use getPasswordChars instead for more security
        Returns:
        the password the password to use for basic authentication, see userInfo() in the builder doc

      • getPasswordChars

        public char[] getPasswordChars()
        Returns:
        the password the password to use for basic authentication, see userInfo() in the builder doc

      • getToken

        @Deprecated
public java.lang.String getToken()
        Deprecated.
        converts the char array to a string, use getTokenChars instead for more security
        Returns:
        the token to be used for token-based authentication, see token() in the builder doc

      • getTokenChars

        public char[] getTokenChars()
        Returns:
        the token to be used for token-based authentication, see token() in the builder doc

      • isOldRequestStyle

        public boolean isOldRequestStyle()
        Returns:
        the flag to turn on old style requests, see oldStyleRequest() in the builder doc

      • getInboxPrefix

        public java.lang.String getInboxPrefix()
        Returns:
        the inbox prefix to use for requests, see inboxPrefix() in the builder doc

      • createURIForServer

        public java.net.URI createURIForServer​(java.lang.String serverURI)
                                throws java.net.URISyntaxException
        Throws:
        java.net.URISyntaxException

      • buildProtocolConnectOptionsString

        public java.nio.CharBuffer buildProtocolConnectOptionsString​(java.lang.String serverURI,
                                                             boolean includeAuth,
                                                             byte[] nonce)
        Create the options string sent with a connect message. If includeAuth is true the auth information is included: If the server URIs have auth info it is used. Otherwise the userInfo is used.
        Parameters:
        serverURI - the current server uri
        includeAuth - tells the options to build a connection string that includes auth information
        nonce - if the client is supposed to sign the nonce for authentication
        Returns:
        the options String, basically JSON