public static class Options.Builder
extends java.lang.Object
new Options.Builder().build()
is equivalent to calling Nats.connect()
.
A common usage for testing might be new Options.Builder().server(myserverurl).noReconnect.build()
Constructor and Description |
---|
Builder()
Constructs a new Builder with the default values.
|
Builder(java.util.Properties props)
Constructs a new
Builder from a Properties object. |
Modifier and Type | Method and Description |
---|---|
Options.Builder |
authHandler(AuthHandler handler)
Set the
AuthHandler to sign the server nonce for authentication in
nonce-mode. |
Options.Builder |
bufferSize(int size)
Sets the initial size for buffers in the connection, primarily for testing.
|
Options |
build()
Build an Options object from this Builder.
|
Options.Builder |
clientSideLimitChecks(boolean checks)
Set client side limit checks.
|
Options.Builder |
connectionListener(ConnectionListener listener)
Set the
ConnectionListener to receive asynchronous notifications of disconnect
events. |
Options.Builder |
connectionName(java.lang.String name)
Set the connection's optional Name.
|
Options.Builder |
connectionTimeout(java.time.Duration time)
Set the timeout for connection attempts.
|
Options.Builder |
dataPortType(java.lang.String dataPortClassName)
The class to use for this connections data port.
|
Options.Builder |
discardMessagesWhenOutgoingQueueFull()
Enable discard messages when the outgoing queue full.
|
Options.Builder |
errorListener(ErrorListener listener)
Set the
ErrorListener to receive asynchronous error events related to this
connection. |
Options.Builder |
executor(java.util.concurrent.ExecutorService executor)
Set the
ExecutorService used to run threaded tasks. |
Options.Builder |
ignoreDiscoveredServers()
Turn off use of discovered servers when connecting / reconnecting.
|
Options.Builder |
inboxPrefix(java.lang.String prefix)
Set the connection's inbox prefix.
|
Options.Builder |
maxControlLine(int bytes)
Set the maximum length of a control line sent by this connection.
|
Options.Builder |
maxMessagesInOutgoingQueue(int maxMessagesInOutgoingQueue)
Set the maximum number of messages in the outgoing queue.
|
Options.Builder |
maxPingsOut(int max)
Set the maximum number of pings the client can have in flight.
|
Options.Builder |
maxReconnects(int max)
Set the maximum number of reconnect attempts.
|
Options.Builder |
noEcho()
Turn off echo.
|
Options.Builder |
noHeaders()
Turn off header support.
|
Options.Builder |
noNoResponders()
Turn off noresponder support.
|
Options.Builder |
noRandomize()
For the default server list provider, turn off server pool randomization.
|
Options.Builder |
noReconnect()
Equivalent to calling maxReconnects with 0,
maxReconnects . |
Options.Builder |
oldRequestStyle()
Turn on the old request style that uses a new inbox and subscriber for each
request.
|
Options.Builder |
opentls()
Set the SSL context to one that accepts any server certificate and has no client certificates.
|
Options.Builder |
pedantic()
Turn on pedantic mode for the server, in relation to this connection.
|
Options.Builder |
pingInterval(java.time.Duration time)
Set the interval between attempts to pings the server.
|
Options.Builder |
reconnectBufferSize(long size)
Set the maximum number of bytes to buffer in the client when trying to
reconnect.
|
Options.Builder |
reconnectDelayHandler(ReconnectDelayHandler handler)
Set the
ReconnectDelayHandler for custom reconnect duration |
Options.Builder |
reconnectJitter(java.time.Duration time)
Set the jitter time to wait between reconnect attempts to the same server.
|
Options.Builder |
reconnectJitterTls(java.time.Duration time)
Set the jitter time for a tls/secure connection to wait between reconnect attempts to the same server.
|
Options.Builder |
reconnectWait(java.time.Duration time)
Set the time to wait between reconnect attempts to the same server.
|
Options.Builder |
requestCleanupInterval(java.time.Duration time)
Set the interval between cleaning passes on outstanding request futures that are cancelled or timeout
in the application code.
|
Options.Builder |
secure()
Sets the options to use the default SSL Context, if it exists.
|
Options.Builder |
server(java.lang.String serverURL)
Add a server to the list of known servers.
|
Options.Builder |
serverListProvider(ServerListProvider serverListProvider)
Set the ServerListProvider implementation for connections to use instead of the default bahvior
IMPORTANT! ServerListProvider IS CURRENTLY EXPERIMENTAL AND SUBJECT TO CHANGE.
|
Options.Builder |
servers(java.lang.String[] servers)
Add an array of servers to the list of known servers.
|
Options.Builder |
sslContext(javax.net.ssl.SSLContext ctx)
Set the SSL context, requires that the server supports TLS connections and
the URI specifies TLS.
|
Options.Builder |
supportUTF8Subjects()
Deprecated.
Plans are to remove allowing utf8mode
|
Options.Builder |
token(char[] token)
Set the token for token-based authentication.
|
Options.Builder |
token(java.lang.String token)
Deprecated.
use the char[] version instead for better security
|
Options.Builder |
traceConnection()
Enable connection trace messages.
|
Options.Builder |
turnOnAdvancedStats()
Turn on advanced stats, primarily for test/benchmarks.
|
Options.Builder |
userInfo(char[] userName,
char[] password)
Set the username and password for basic authentication.
|
Options.Builder |
userInfo(java.lang.String userName,
java.lang.String password)
Set the username and password for basic authentication.
|
Options.Builder |
verbose()
Turn on verbose mode with the server.
|
public Builder()
One tiny clarification is that the builder doesn't have a server url. When build()
is called on a default builder it will add the default url
to its list of servers before creating the options object.
public Builder(java.util.Properties props) throws java.lang.IllegalArgumentException
Builder
from a Properties
object.
If PROP_SECURE
is set, the builder will
try to to get the default contextgetDefault()
.
If a context can't be found, no context is set and an IllegalArgumentException is thrown.
Methods called on the builder after construction can override the properties.
props
- the Properties
objectjava.lang.IllegalArgumentException
public Options.Builder server(java.lang.String serverURL)
serverURL
- the URL for the server to addjava.lang.IllegalArgumentException
- if the url is not formatted correctly.public Options.Builder servers(java.lang.String[] servers)
servers
- A list of server URIsjava.lang.IllegalArgumentException
- if any url is not formatted correctly.public Options.Builder oldRequestStyle()
public Options.Builder noRandomize()
public Options.Builder noEcho()
public Options.Builder noHeaders()
public Options.Builder noNoResponders()
public Options.Builder clientSideLimitChecks(boolean checks)
checks
- the checks flag@Deprecated public Options.Builder supportUTF8Subjects()
public Options.Builder connectionName(java.lang.String name)
name
- the connections new name.public Options.Builder inboxPrefix(java.lang.String prefix)
prefix
- prefix to use.public Options.Builder verbose()
public Options.Builder pedantic()
public Options.Builder turnOnAdvancedStats()
Statistics
object.public Options.Builder traceConnection()
public Options.Builder secure() throws java.security.NoSuchAlgorithmException, java.lang.IllegalArgumentException
java.security.NoSuchAlgorithmException
- If the default protocol is unavailable.java.lang.IllegalArgumentException
- If there is no default SSL context.public Options.Builder opentls() throws java.security.NoSuchAlgorithmException
java.security.NoSuchAlgorithmException
- If the tls protocol is unavailable.public Options.Builder sslContext(javax.net.ssl.SSLContext ctx)
ctx
- the SSL Context to use for TLS connectionspublic Options.Builder noReconnect()
maxReconnects
.public Options.Builder maxReconnects(int max)
The reconnect count is incremented on a per-server basis, so if the server list contains 5 servers but max reconnects is set to 3, only 3 of those servers will be tried.
This library has a slight difference from some NATS clients, if you set the maxReconnects to zero there will not be any reconnect attempts, regardless of the number of known servers.
The reconnect state is entered when the connection is connected and loses
that connection. During the initial connection attempt, the client will cycle over
its server list one time, regardless of what maxReconnects is set to. The only exception
to this is the experimental async connect method connectAsynchronously
.
max
- the maximum reconnect attemptspublic Options.Builder reconnectWait(java.time.Duration time)
time
- the time to waitpublic Options.Builder reconnectJitter(java.time.Duration time)
time
- the time to waitpublic Options.Builder reconnectJitterTls(java.time.Duration time)
time
- the time to waitpublic Options.Builder maxControlLine(int bytes)
bytes
- the max byte countpublic Options.Builder connectionTimeout(java.time.Duration time)
time
- the time to waitpublic Options.Builder pingInterval(java.time.Duration time)
maxPingsOut()
. As of 2.4.4 the library
may way up to 2 * time to send a ping. Incoming traffic from the server can postpone
the next ping to avoid pings taking up bandwidth during busy messaging.
Keep in mind that a ping requires a round trip to the server. Setting this value to a small
number can result in quick failures due to maxPingsOut being reached, these failures will
force a disconnect/reconnect which can result in messages being held back or failed. In general,
the ping interval should be set in seconds but this value is not enforced as it would result in
an API change from the 2.0 release.time
- the time between client to server pingspublic Options.Builder requestCleanupInterval(java.time.Duration time)
The default value is probably reasonable, but this interval is useful in a very noisy network situation where lots of requests are used.
time
- the cleaning intervalpublic Options.Builder maxPingsOut(int max)
max
- the max pingspublic Options.Builder bufferSize(int size)
size
- the size in bytes to make buffers for connections created with this optionspublic Options.Builder reconnectBufferSize(long size)
Statistics
.
A value of zero will disable the reconnect buffer, a value less than zero means unlimited. Caution
should be used for negative numbers as they can result in an unreliable network connection plus a
high message rate leading to an out of memory error.size
- the size in bytespublic Options.Builder userInfo(java.lang.String userName, java.lang.String password)
userName
- a non-empty user namepassword
- the password, in plain textpublic Options.Builder userInfo(char[] userName, char[] password)
userName
- a non-empty user namepassword
- the password, in plain text@Deprecated public Options.Builder token(java.lang.String token)
token
- The tokenpublic Options.Builder token(char[] token)
token
- The tokenpublic Options.Builder authHandler(AuthHandler handler)
AuthHandler
to sign the server nonce for authentication in
nonce-mode.handler
- The new AuthHandler for this connection.public Options.Builder reconnectDelayHandler(ReconnectDelayHandler handler)
ReconnectDelayHandler
for custom reconnect durationhandler
- The new ReconnectDelayHandler for this connection.public Options.Builder errorListener(ErrorListener listener)
ErrorListener
to receive asynchronous error events related to this
connection.listener
- The new ErrorListener for this connection.public Options.Builder connectionListener(ConnectionListener listener)
ConnectionListener
to receive asynchronous notifications of disconnect
events.listener
- The new ConnectionListener for this type of event.public Options.Builder executor(java.util.concurrent.ExecutorService executor)
ExecutorService
used to run threaded tasks. The default is a
cached thread pool that names threads after the connection name (or a default). This executor
is used for reading and writing the underlying sockets as well as for each Dispatcher.
The default executor uses a short keepalive time, 500ms, to insure quick shutdowns. This is reasonable
since most threads from the executor are long lived. If you customize, be sure to keep the shutdown
effect in mind, exectors can block for their keepalive time. The default executor also marks threads
with priority normal and as non-daemon.executor
- The ExecutorService to use for connections built with these options.public Options.Builder dataPortType(java.lang.String dataPortClassName)
dataPortClassName
- a valid and accessible class namepublic Options.Builder maxMessagesInOutgoingQueue(int maxMessagesInOutgoingQueue)
maxMessagesInOutgoingQueue
- the maximum number of messages in the outgoing queuepublic Options.Builder discardMessagesWhenOutgoingQueueFull()
maxMessagesInOutgoingQueue
public Options.Builder ignoreDiscoveredServers()
public Options.Builder serverListProvider(ServerListProvider serverListProvider)
serverListProvider
- the implementationpublic Options build() throws java.lang.IllegalStateException
If the Options builder was not provided with a server, a default one will be included
Options.DEFAULT_URL
. If only a single server URI is included, the builder
will try a few things to make connecting easier:
nats://user:password@server:port
, they will be used.
nats://token@server:port
, it will be used.
secure()
.
java.lang.IllegalStateException
- if there is a conflict in the options, like a token and a user/pass