JBoss.orgCommunity Documentation
Most of the services provided by XNIO and its subprojects are configured with options.
An option is identified by an instance of the org.jboss.xnio.Option class. Instances of this
class are also associated with a specific argument type parameter; in other words, option values are strongly
typed.
Options and option values are serializable, singleton constants (not unlike enum values), and support identity comparison
(in other words, one can use the == operator to determine option equality).
By convention, options always have an immutable serializable type as the argument.
There are two kinds of options: simple and sequence. A simple option has only a single
value, typically of a primitive type such as Integer or Boolean, or an enum
type. A sequence option is an option whose argument is a sequence of simple values. A
special immutable List implementation, org.jboss.xnio.Sequence, is provided
for this purpose.
The initial configuration of an XNIO service is usually specified using an org.jboss.xnio.OptionMap. This
is an immutable, serializable map of options and values. Instances are constructed using a builder pattern, as follows:
OptionMap map = OptionMap.builder()
.set(Options.TCP_KEEPALIVE, true)
.set(Options.REUSE_ADDRESSES, true)
.setSequence(Options.SSL_ENABLED_PROTOCOLS, "SSLv2", "TLSv1")
.set(Options.RECEIVE_BUFFER, 2048)
.getMap();
To use XNIO services, one must have an XNIO provider instance (an object
which implements the org.jboss.xnio.Xnio class). The Xnio class contains
static methods to locate providers and create provider instances. A single provider instance can
support many distinct services concurrently.
Here is an example illustrating the creation of a new provider:
final XnioConfiguration conf = new XnioConfiguration();
conf.setOptionMap(OptionMap.builder()
.set(Options.READ_THREADS, 3)
.set(Options.WRITE_THREADS, 1)
.set(Options.CONNECT_THREADS, 1)
.getMap());
Xnio xnio = Xnio.create(conf);
The returned provider will use three threads for read operations, one thread for write operations, and one thread for connect and accept operations.
A provider may be configured to run all channel listeners in a separate java.util.concurrent.Executor
by way of the executor property of XnioConfiguration.
The simplest form of an XNIO TCP server is as follows:
TcpServer server = xnio.createTcpServer(openListener, OptionMap.EMPTY);
server.bind(new InetSocketAddress(12345));
server.bind(new InetSocketAddress(23456));
This creates a basic server listening on ports 12345 and 23456, which will cause the given openListener
the be called every time an incoming connection is accepted on either port. The resulting TCP channel
can then be queried to determine the actual local address.
If one wishes to control each individial binding, the TcpServer.bind() method's return value
may be utilized. When this method is called, it returns an IoFuture which will return the
result of the bind operation as a BoundChannel. This returned channel can be closed at a later
point to cause only the corresponding binding to be undone.