reactor.netty.tcp

Class TcpServer

java.lang.Object

reactor.netty.tcp.TcpServer

public abstract class TcpServer
extends Object

A TcpServer allows to build in a safe immutable way a TCP server that is materialized and connecting when bind(ServerBootstrap) is ultimately called.

Internally, materialization happens in two phases:

• first configure() is called to retrieve a ready to use ServerBootstrap
• then bind(ServerBootstrap) is called.

Example:

 
 TcpServer.create()
          .doOnBind(startMetrics)
          .doOnBound(startedMetrics)
          .doOnUnbound(stopMetrics)
          .host("127.0.0.1")
          .port(1234)
          .bind()
          .block()
 
 

Author:

Stephane Maldini

Constructor Summary

Constructors

Constructor and Description
TcpServer()

Method Summary

Modifier and Type	Method and Description
TcpServer	addressSupplier(java.util.function.Supplier<? extends SocketAddress> bindingAddressSupplier) The address to which this server should bind on subscribe.
<T> TcpServer	attr(AttributeKey<T> key, T value) Injects default attribute to the future child Channel connections.
Mono<? extends DisposableServer>	bind() Binds the TcpServer and returns a Mono of DisposableServer.
abstract Mono<? extends DisposableServer>	bind(ServerBootstrap b) Binds the TcpServer and returns a Mono of DisposableServer
DisposableServer	bindNow() Starts the server in a blocking fashion, and waits for it to finish initializing or the startup timeout expires (the startup timeout is 45 seconds).
DisposableServer	bindNow(java.time.Duration timeout) Start the server in a blocking fashion, and wait for it to finish initializing or the provided startup timeout expires.
void	bindUntilJavaShutdown(java.time.Duration timeout, java.util.function.Consumer<DisposableServer> onStart) Start the server in a fully blocking fashion, not only waiting for it to initialize but also blocking during the full lifecycle of the server.
TcpServer	bootstrap(java.util.function.Function<? super ServerBootstrap,? extends ServerBootstrap> bootstrapMapper) Applies ServerBootstrap configuration given mapper taking currently configured one and returning a new one to be ultimately used for socket binding.
abstract ServerBootstrap	configure() Materializes a ServerBootstrap from the parent TcpServer chain to use with bind(ServerBootstrap) or separately
static TcpServer	create() Prepare a TcpServer
TcpServer	doOnBind(java.util.function.Consumer<? super ServerBootstrap> doOnBind) Setups a callback called when ServerChannel is about to bind.
TcpServer	doOnBound(java.util.function.Consumer<? super DisposableServer> doOnBound) Setups a callback called when ServerChannel is bound.
TcpServer	doOnConnection(java.util.function.Consumer<? super Connection> doOnConnection) Setups a callback called when a remote client is connected
TcpServer	doOnLifecycle(java.util.function.Consumer<? super ServerBootstrap> onBind, java.util.function.Consumer<? super DisposableServer> onBound, java.util.function.Consumer<? super DisposableServer> onUnbound) Setups all lifecycle callbacks called on or after Channel has been bound and after it has been unbound.
TcpServer	doOnUnbound(java.util.function.Consumer<? super DisposableServer> doOnUnbind) Setups a callback called when ServerChannel is unbound.
TcpServer	handle(java.util.function.BiFunction<? super NettyInbound,? super NettyOutbound,? extends Publisher<Void>> handler) Attaches an I/O handler to react on a connected client
TcpServer	host(String host) The host to which this server should bind.
boolean	isSecure() Returns true if that TcpServer secured via SSL transport
TcpServer	noSSL() Removes any previously applied SSL configuration customization
TcpServer	observe(ConnectionObserver observer) Setups all lifecycle callbacks called on or after Channel has been connected and after it has been disconnected.
<T> TcpServer	option(ChannelOption<T> key, T value) Sets a ChannelOption value for low level connection settings like SO_TIMEOUT or SO_KEEPALIVE.
TcpServer	port(int port) The port to which this server should bind.
TcpServer	runOn(EventLoopGroup eventLoopGroup) Runs I/O loops on the given EventLoopGroup.
TcpServer	runOn(LoopResources channelResources) Runs I/O loops on a supplied EventLoopGroup from the LoopResources container.
TcpServer	runOn(LoopResources channelResources, boolean preferNative) Runs I/O loops on a supplied EventLoopGroup from the LoopResources container.
TcpServer	secure(java.util.function.Consumer<? super SslProvider.SslContextSpec> sslProviderBuilder) Applies an SSL configuration customization via the passed builder.
TcpServer	secure(SslContext sslContext) Deprecated. Use secure(Consumer)
TcpServer	secure(SslProvider sslProvider) Applies an SSL configuration via the passed SslProvider.
<T> TcpServer	selectorAttr(AttributeKey<T> key, T value) Injects default attribute to the future ServerChannel selector connection.
<T> TcpServer	selectorOption(ChannelOption<T> key, T value) Sets a ChannelOption value for low level connection settings like SO_TIMEOUT or SO_KEEPALIVE.
SslProvider	sslProvider() Returns the current SslProvider if that TcpServer secured via SSL transport or null
TcpServer	wiretap() Deprecated. Use wiretap(boolean)
TcpServer	wiretap(boolean enable) Applies or remove a wire logger configuration using TcpServer category and DEBUG logger level
TcpServer	wiretap(String category) Applies a wire logger configuration using the specified category and DEBUG logger level
TcpServer	wiretap(String category, LogLevel level) Applies a wire logger configuration using the specified category and logger level

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TcpServer

public TcpServer()

Method Detail

create

public static TcpServer create()

Prepare a TcpServer

Returns:

a new TcpServer

addressSupplier

public final TcpServer addressSupplier(java.util.function.Supplier<? extends SocketAddress> bindingAddressSupplier)

The address to which this server should bind on subscribe.

Parameters:

bindingAddressSupplier - A supplier of the address to bind to.

Returns:

a new TcpServer

attr

public final <T> TcpServer attr(AttributeKey<T> key,
                                @Nullable
                                T value)

Injects default attribute to the future child Channel connections. It will be available via AttributeMap.attr(AttributeKey). If the value is null, the attribute of the specified key is removed.

Type Parameters:

T - the attribute type

Parameters:

key - the attribute key

value - the attribute value

Returns:

a new TcpServer

See Also:

ServerBootstrap.childAttr(AttributeKey, Object)

bootstrap

public final TcpServer bootstrap(java.util.function.Function<? super ServerBootstrap,? extends ServerBootstrap> bootstrapMapper)

Applies ServerBootstrap configuration given mapper taking currently configured one and returning a new one to be ultimately used for socket binding.

Configuration will apply during configure() phase.

Parameters:

bootstrapMapper - A bootstrap mapping function to update configuration and return an enriched bootstrap.

Returns:

a new TcpServer

bind

public final Mono<? extends DisposableServer> bind()

Binds the TcpServer and returns a Mono of DisposableServer. If Mono is cancelled, the underlying binding will be aborted. Once the DisposableServer has been emitted and is not necessary anymore, disposing the main server loop must be done by the user via DisposableChannel.dispose(). If updateConfiguration phase fails, a Mono.error(Throwable) will be returned;

Returns:

a Mono of DisposableServer

bind

public abstract Mono<? extends DisposableServer> bind(ServerBootstrap b)

Binds the TcpServer and returns a Mono of DisposableServer

Parameters:

b - the ServerBootstrap to bind

Returns:

a Mono of DisposableServer

bindNow

public final DisposableServer bindNow()

Starts the server in a blocking fashion, and waits for it to finish initializing or the startup timeout expires (the startup timeout is 45 seconds). The returned DisposableServer offers simple server API, including to DisposableChannel.disposeNow() shut it down in a blocking fashion.

Returns:

a DisposableServer

bindNow

public final DisposableServer bindNow(java.time.Duration timeout)

Start the server in a blocking fashion, and wait for it to finish initializing or the provided startup timeout expires. The returned DisposableServer offers simple server API, including to DisposableChannel.disposeNow() shut it down in a blocking fashion.

Parameters:

timeout - max startup timeout

Returns:

a DisposableServer

bindUntilJavaShutdown

public final void bindUntilJavaShutdown(java.time.Duration timeout,
                                        @Nullable
                                        java.util.function.Consumer<DisposableServer> onStart)

Start the server in a fully blocking fashion, not only waiting for it to initialize but also blocking during the full lifecycle of the server. Since most servers will be long-lived, this is more adapted to running a server out of a main method, only allowing shutdown of the servers through sigkill.

Note: JVM shutdown hook is added by this method in order to properly disconnect the server upon receiving a sigkill signal.

Parameters:

timeout - a timeout for server shutdown

onStart - an optional callback on server start

configure

public abstract ServerBootstrap configure()

Materializes a ServerBootstrap from the parent TcpServer chain to use with bind(ServerBootstrap) or separately

Returns:

a configured ServerBootstrap

doOnBind

public final TcpServer doOnBind(java.util.function.Consumer<? super ServerBootstrap> doOnBind)

Setups a callback called when ServerChannel is about to bind.

Parameters:

doOnBind - a consumer observing server start event

Returns:

a new TcpServer

doOnBound

public final TcpServer doOnBound(java.util.function.Consumer<? super DisposableServer> doOnBound)

Setups a callback called when ServerChannel is bound.

Parameters:

doOnBound - a consumer observing server started event

Returns:

a new TcpServer

doOnConnection

public final TcpServer doOnConnection(java.util.function.Consumer<? super Connection> doOnConnection)

Setups a callback called when a remote client is connected

Parameters:

doOnConnection - a consumer observing connected clients

Returns:

a new TcpServer

doOnUnbound

public final TcpServer doOnUnbound(java.util.function.Consumer<? super DisposableServer> doOnUnbind)

Setups a callback called when ServerChannel is unbound.

Parameters:

doOnUnbind - a consumer observing server stop event

Returns:

a new TcpServer

doOnLifecycle

public final TcpServer doOnLifecycle(java.util.function.Consumer<? super ServerBootstrap> onBind,
                                     java.util.function.Consumer<? super DisposableServer> onBound,
                                     java.util.function.Consumer<? super DisposableServer> onUnbound)

Setups all lifecycle callbacks called on or after Channel has been bound and after it has been unbound.

Parameters:

onBind - a consumer observing server start event

onBound - a consumer observing server started event

onUnbound - a consumer observing server stop event

Returns:

a new TcpServer

handle

public final TcpServer handle(java.util.function.BiFunction<? super NettyInbound,? super NettyOutbound,? extends Publisher<Void>> handler)

Attaches an I/O handler to react on a connected client

Parameters:

handler - an I/O handler that can dispose underlying connection when Publisher terminates.

Returns:

a new TcpServer

host

public final TcpServer host(String host)

The host to which this server should bind. By default the server will listen on any local address.

Parameters:

host - The host to bind to.

Returns:

a new TcpServer

isSecure

public final boolean isSecure()

Returns true if that TcpServer secured via SSL transport

Returns:

true if that TcpServer secured via SSL transport

noSSL

public final TcpServer noSSL()

Removes any previously applied SSL configuration customization

Returns:

a new TcpServer

observe

public final TcpServer observe(ConnectionObserver observer)

Setups all lifecycle callbacks called on or after Channel has been connected and after it has been disconnected.

Parameters:

observer - a consumer observing state changes

Returns:

a new TcpServer

option

public final <T> TcpServer option(ChannelOption<T> key,
                                  @Nullable
                                  T value)

Sets a ChannelOption value for low level connection settings like SO_TIMEOUT or SO_KEEPALIVE. This will apply to each new channel from remote peer. Use a value of null to remove a previous set ChannelOption.

Type Parameters:

T - the option type

Parameters:

key - the option key

value - the option value

Returns:

new TcpServer

See Also:

ServerBootstrap.childOption(ChannelOption, Object)

port

public final TcpServer port(int port)

The port to which this server should bind. By default the system will pick up an ephemeral port in the bind() operation:

Parameters:

port - The port to bind to.

Returns:

a new TcpServer

runOn

public final TcpServer runOn(EventLoopGroup eventLoopGroup)

Runs I/O loops on the given EventLoopGroup.

Parameters:

eventLoopGroup - an eventLoopGroup to share

Returns:

a new TcpServer

runOn

public final TcpServer runOn(LoopResources channelResources)

Runs I/O loops on a supplied EventLoopGroup from the LoopResources container. Will prefer native (epoll/kqueue) implementation if available unless the environment property reactor.netty.native is set to false.

Parameters:

channelResources - a LoopResources accepting native runtime expectation and returning an eventLoopGroup

Returns:

a new TcpServer

runOn

public final TcpServer runOn(LoopResources channelResources,
                             boolean preferNative)

Runs I/O loops on a supplied EventLoopGroup from the LoopResources container.

Parameters:

channelResources - a LoopResources accepting native runtime expectation and returning an eventLoopGroup.

preferNative - Should the connector prefer native (epoll/kqueue) if available.

Returns:

a new TcpServer

secure

@Deprecated
public final TcpServer secure(SslContext sslContext)

Deprecated. Use secure(Consumer)

Applies an SSL configuration customization via the passed SslContext. with a default value of 10 seconds handshake timeout unless the environment property reactor.netty.tcp.sslHandshakeTimeout is set. If SelfSignedCertificate needs to be used, the sample below can be used. Note that SelfSignedCertificate should not be used in production.

 
     SelfSignedCertificate cert = new SelfSignedCertificate();
     SslContextBuilder sslContextBuilder =
             SslContextBuilder.forServer(cert.certificate(), cert.privateKey());
     secure(sslContextBuilder.build());
 
 

Parameters:

sslContext - The context to set when configuring SSL

Returns:

a new TcpServer

secure

public final TcpServer secure(java.util.function.Consumer<? super SslProvider.SslContextSpec> sslProviderBuilder)

Applies an SSL configuration customization via the passed builder. The builder will produce the SslContext to be passed to with a default value of 10 seconds handshake timeout unless the environment property reactor.netty.tcp.sslHandshakeTimeout is set. If SelfSignedCertificate needs to be used, the sample below can be used. Note that SelfSignedCertificate should not be used in production.

 
     SelfSignedCertificate cert = new SelfSignedCertificate();
     SslContextBuilder sslContextBuilder =
             SslContextBuilder.forServer(cert.certificate(), cert.privateKey());
     secure(sslContextSpec -> sslContextSpec.sslContext(sslContextBuilder));
 
 

Parameters:

sslProviderBuilder - builder callback for further customization of SslContext.

Returns:

a new TcpServer

secure

public final TcpServer secure(SslProvider sslProvider)

Applies an SSL configuration via the passed SslProvider. If SelfSignedCertificate needs to be used, the sample below can be used. Note that SelfSignedCertificate should not be used in production.

 
     SelfSignedCertificate cert = new SelfSignedCertificate();
     SslContextBuilder sslContextBuilder =
             SslContextBuilder.forServer(cert.certificate(), cert.privateKey());
     secure(sslContextSpec -> sslContextSpec.sslContext(sslContextBuilder));
 
 

Parameters:

sslProvider - The provider to set when configuring SSL

Returns:

a new TcpServer

selectorAttr

public final <T> TcpServer selectorAttr(AttributeKey<T> key,
                                        T value)

Injects default attribute to the future ServerChannel selector connection.

Type Parameters:

T - the attribute type

Parameters:

key - the attribute key

value - the attribute value

Returns:

a new TcpServer

See Also:

AbstractBootstrap.attr(AttributeKey, Object)

selectorOption

public final <T> TcpServer selectorOption(ChannelOption<T> key,
                                          T value)

Sets a ChannelOption value for low level connection settings like SO_TIMEOUT or SO_KEEPALIVE. This will apply to parent selector channel.

Type Parameters:

T - the option type

Parameters:

key - the option key

value - the option value

Returns:

new TcpServer

See Also:

AbstractBootstrap.option(ChannelOption, Object)

sslProvider

@Nullable
public SslProvider sslProvider()

Returns the current SslProvider if that TcpServer secured via SSL transport or null

Returns:

the current SslProvider if that TcpServer secured via SSL transport or null

wiretap

@Deprecated
public final TcpServer wiretap()

Deprecated. Use wiretap(boolean)

Applies a wire logger configuration using TcpServer category and DEBUG logger level

Returns:

a new TcpServer

wiretap

public final TcpServer wiretap(boolean enable)

Applies or remove a wire logger configuration using TcpServer category and DEBUG logger level

Parameters:

enable - Specifies whether the wire logger configuration will be added to the pipeline

Returns:

a new TcpServer

wiretap

public final TcpServer wiretap(String category)

Applies a wire logger configuration using the specified category and DEBUG logger level

Parameters:

category - the logger category

Returns:

a new TcpServer

wiretap

public final TcpServer wiretap(String category,
                               LogLevel level)

Applies a wire logger configuration using the specified category and logger level

Parameters:

category - the logger category

level - the logger level

Returns:

a new TcpServer