io.nats.client.Nats Maven / Gradle / Ivy
Show all versions of jnats Show documentation
// Copyright 2015-2018 The NATS Authors
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at:
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package io.nats.client;
import java.io.IOException;
import io.nats.client.impl.NatsImpl;
/**
* The Nats class is the entry point into the NATS client for Java. This class
* is used to create a connection to the Nats server, gnatsd. Connecting is a
* synchronous process, with a new asynchronous version available for experimenting.
*
* Simple connections can be created with a URL, while more control is provided
* when an {@link Options Options} object is used. There are a number of options that
* effect every connection, as described in the {@link Options Options} documentation.
*
*
At its simplest, you can connect to a gnatsd on the local host using the default port with:
*
Connection nc = Nats.connect()
* and start sending or receiving messages immediately after that.
*
*
While the simple case relies on a single URL, the options allows you to configure a list of servers
* that is used at connect time and during reconnect scenarios.
*
*
NATS supports TLS connections. This library relies on the standard SSLContext class to configure
* SSL certificates and trust managers, as a result there are two steps to setting up a TLS connection,
* configuring the SSL context and telling the library which one to use. Several options are provided
* for each. To tell the library to connect with TLS:
*
*
* - Pass a tls:// URL to the connect method, or as part of the options. The library will use the
* default SSLContext for both the client certificates and trust managers.
*
- Call the {@link Options.Builder#secure() secure} method on the options builder, again the default
* SSL Context is used.
*
- Call {@link Options.Builder#sslContext(javax.net.ssl.SSLContext) sslContext} when building your options.
* Your context will be used.
*
- Pass an opentls:// url to the connect method, or in the options. The library will create a special
* SSLContext that has no client certificates and trusts any server. This is less secure, but useful for
* testing and behind a firewall.
*
- Call the {@link Options.Builder#opentls() opentls} method on the builder when creating your options, again
* the all trusting, non-verifiable client is created.
*
*
* To set up the default context for tls:// or {@link Options.Builder#secure() secure} you can:
*
* - Configure the default using System properties, i.e. javax.net.ssl.keyStore.
*
- Set the context manually with the SSLContext setDefault method.
*
*
* If the server is configured to verify clients, the opentls mode will not work, and the other modes require a client certificate
* to work.
*
*
Authentication, if configured on the server, is managed via the Options as well. However, the url passed to {@link #connect(String) connect()}
* can provide a user/password pair or a token using the forms: {@code nats://user:password@server:port} and {@code nats://token@server:port}.
*
*
Regardless of the method used a {@link Connection Connection} object is created, and provides the methods for
* sending, receiving and dispatching messages.
*/
public class Nats {
/**
* Current version of the library - {@value #CLIENT_VERSION}
*/
public static final String CLIENT_VERSION = "2.0.0";
/**
* Current language of the library - {@value #CLIENT_LANGUAGE}
*/
public static final String CLIENT_LANGUAGE = "java";
/**
* Connect to the default URL, {@link Options#DEFAULT_URL Options.DEFAULT_URL}, with all of the
* default options.
*
*
This is a synchronous call, and the connection should be ready for use on return
* there are network timing issues that could result in a successful connect call but
* the connection is invalid soon after return, where soon is in the network/thread world.
*
*
If the connection fails, an IOException is thrown
*
* @throws IOException if a networking issue occurs
* @throws InterruptedException if the current thread is interrupted
* @return the connection
*/
public static Connection connect() throws IOException, InterruptedException {
Options options = new Options.Builder().server(Options.DEFAULT_URL).build();
return createConnection(options, false);
}
/**
* The Java client generally expects URLs of the form {@code nats://hostname:port}
*
*
but also allows urls with a user password {@code nats://user:pass@hostname:port}.
*
*
or token in them {@code nats://token@hostname:port}.
*
*
Moreover, you can initiate a TLS connection, by using the `tls`
* schema, which will use the default SSLContext, or fail if one is not set. For
* testing and development, the `opentls` schema is support when the server is
* in non-verify mode. In this case, the client will accept any server
* certificate and will not provide one of its own.
*
*
This is a synchronous call, and the connection should be ready for use on return
* there are network timing issues that could result in a successful connect call but
* the connection is invalid soon after return, where soon is in the network/thread world.
*
*
If the connection fails, an IOException is thrown
*
* @param url the url of the server, ie. nats://localhost:4222
* @throws IOException if a networking issue occurs
* @throws InterruptedException if the current thread is interrupted
* @return the connection
*/
public static Connection connect(String url) throws IOException, InterruptedException {
Options options = new Options.Builder().server(url).build();
return createConnection(options, false);
}
/**
* Options can be used to set the server URL, or multiple URLS, callback
* handlers for various errors, and connection events.
*
*
*
This is a synchronous call, and the connection should be ready for use on return
* there are network timing issues that could result in a successful connect call but
* the connection is invalid soon after return, where soon is in the network/thread world.
*
*
If the connection fails, an IOException is thrown
*
* @param options the options object to use to create the connection
* @throws IOException if a networking issue occurs
* @throws InterruptedException if the current thread is interrupted
* @return the connection
*/
public static Connection connect(Options options) throws IOException, InterruptedException {
return createConnection(options, false);
}
/**
* Try to connect in another thread, a connection listener is required to get
* the connection.
*
*
Normally connect will loop through the available servers one time. If
* reconnectOnConnect is true, the connection attempt will repeat based on the
* settings in options, including indefinitely.
*
*
If there is an exception before a connection is created, and the error
* listener is set, it will be notified with a null connection.
*
*
This method is experimental, please provide feedback on its value.
*
* @param options the connection options
* @param reconnectOnConnect if true, the connection will treat the initial
* connection as any other and attempt reconnects on
* failure
*
* @throws IllegalArgumentException if no connection listener is set in the options
* @throws InterruptedException if the current thread is interrupted
*/
public static void connectAsynchronously(Options options, boolean reconnectOnConnect)
throws InterruptedException {
if (options.getConnectionListener() == null) {
throw new IllegalArgumentException("Connection Listener required in connectAsynchronously");
}
Thread t = new Thread(() -> {
try {
NatsImpl.createConnection(options, reconnectOnConnect);
} catch (Exception ex) {
if (options.getErrorListener() != null) {
options.getErrorListener().exceptionOccurred(null, ex);
}
}
});
t.start();
}
private static Connection createConnection(Options options, boolean reconnectOnConnect)
throws IOException, InterruptedException {
return NatsImpl.createConnection(options, reconnectOnConnect);
}
private Nats() {
throw new UnsupportedOperationException("Nats is a static class");
}
}