Package reactor.netty.tcp

Class TcpClient

java.lang.Object

reactor.netty.transport.Transport<T,CONF>

reactor.netty.transport.ClientTransport<TcpClient,TcpClientConfig>

reactor.netty.tcp.TcpClient

public abstract class TcpClient
extends ClientTransport<TcpClient,TcpClientConfig>

A TcpClient allows building in a safe immutable way a TCP client that is materialized and connecting when connect() is ultimately called.

Example:

 
 TcpClient.create()
          .doOnConnect(connectMetrics)
          .doOnConnected(connectedMetrics)
          .doOnDisconnected(disconnectedMetrics)
          .host("127.0.0.1")
          .port(1234)
          .secure()
          .connect()
          .block()
 
 

Author:

Stephane Maldini, Violeta Georgieva

Nested Class Summary

Nested classes/interfaces inherited from class reactor.netty.transport.ClientTransport

ClientTransport.ResolvedAddressSelector<CONF>

Constructor Summary

Constructors

Constructor	Description
TcpClient()

Method Summary

Modifier and Type	Method	Description
final TcpClient	addressSupplier(Supplier<? extends SocketAddress> connectAddressSupplier)	Deprecated. Use remoteAddress(Supplier).
<A> TcpClient	attr(AttributeKey<A> key, @Nullable A value)	Update the given attribute key or remove it if the value is null.
TcpClient	bindAddress(Supplier<? extends SocketAddress> bindAddressSupplier)	Set a new local address to which this transport should bind on subscribe.
final TcpClient	bootstrap(Function<? super Bootstrap,? extends Bootstrap> bootstrapMapper)	Deprecated. as of 0.9.10.
Mono<? extends Connection>	connect()	Connect the ClientTransport and return a Mono of Connection.
final Connection	connectNow()	Block the ClientTransport and return a Connection.
final Connection	connectNow(Duration timeout)	Block the ClientTransport and return a Connection.
static TcpClient	create()	Prepare a pooled TcpClient.
static TcpClient	create(ConnectionProvider provider)	Prepare a TcpClient.
TcpClient	doOnConnect(Consumer<? super TcpClientConfig> doOnConnect)	Set or add a callback called when ClientTransport is about to connect to the remote endpoint.
TcpClient	doOnConnected(Consumer<? super Connection> doOnConnected)	Set or add a callback called after Connection has been connected.
TcpClient	doOnDisconnected(Consumer<? super Connection> doOnDisconnected)	Set or add a callback called after Connection has been disconnected.
TcpClient	handle(BiFunction<? super NettyInbound,? super NettyOutbound,? extends Publisher<Void>> handler)	Attach an IO handler to react on connected client.
TcpClient	host(String host)	The host to which this client should connect.
TcpClient	metrics(boolean enable)	Whether to enable metrics to be collected and registered in Micrometer's globalRegistry.
TcpClient	metrics(boolean enable, Supplier<? extends ChannelMetricsRecorder> recorder)	Specifies whether the metrics are enabled on the Transport.
static TcpClient	newConnection()	Prepare a non pooled TcpClient.
TcpClient	noProxy()	Remove any previously applied Proxy configuration customization.
TcpClient	noSSL()	Remove any previously applied SSL configuration customization.
TcpClient	observe(ConnectionObserver observer)	Set or add the given ConnectionObserver to observe the connection state changes.
<O> TcpClient	option(ChannelOption<O> key, @Nullable O value)	Update the given option key or remove it if the value is null.
TcpClient	port(int port)	The port to which this client should connect.
TcpClient	proxy(Consumer<? super ProxyProvider.TypeSpec> proxyOptions)	Apply a proxy configuration.
TcpClient	remoteAddress(Supplier<? extends SocketAddress> remoteAddressSupplier)	The address to which this client should connect on each subscribe.
TcpClient	resolver(AddressResolverGroup<?> resolver)	Assign an AddressResolverGroup.
TcpClient	runOn(EventLoopGroup eventLoopGroup)	Run IO loops on the given EventLoopGroup.
TcpClient	runOn(LoopResources channelResources)	Run IO loops on a supplied EventLoopGroup from the LoopResources container.
TcpClient	runOn(LoopResources loopResources, boolean preferNative)	Run IO loops on a supplied EventLoopGroup from the LoopResources container.
TcpClient	secure()	Enable default sslContext support.
TcpClient	secure(Consumer<? super SslProvider.SslContextSpec> sslProviderBuilder)	Apply an SSL configuration customization via the passed builder.
TcpClient	secure(SslProvider sslProvider)	Apply an SSL configuration via the passed SslProvider.
Mono<Void>	warmup()	Based on the actual configuration, returns a Mono that triggers: an initialization of the event loop group an initialization of the host name resolver loads the necessary native libraries for the transport loads the necessary native libraries for the security if there is such By default, when method is not used, the connect operation absorbs the extra time needed to load resources.
TcpClient	wiretap(boolean enable)	Apply or remove a wire logger configuration using Transport category (logger), DEBUG logger level and AdvancedByteBufFormat.HEX_DUMP for ByteBuf format, which means both events and content will be logged and the content will be in hex format.
TcpClient	wiretap(String category)	Apply a wire logger configuration using the specified category (logger), DEBUG logger level and AdvancedByteBufFormat.HEX_DUMP for ByteBuf format, which means both events and content will be logged and the content will be in hex format.
TcpClient	wiretap(String category, LogLevel level)	Apply a wire logger configuration using the specified category (logger), logger level and AdvancedByteBufFormat.HEX_DUMP for ByteBuf format, which means both events and content will be logged and the content will be in hex format.

Methods inherited from class reactor.netty.transport.ClientTransport

doAfterResolve, doOnResolve, doOnResolveError, proxyWithSystemProperties, resolvedAddressesSelector, resolver

Methods inherited from class reactor.netty.transport.Transport

channelGroup, configuration, doOnChannelInit, duplicate, wiretap, wiretap

Methods inherited from class java.lang.Object

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

Constructor Details

TcpClient

public TcpClient()

Method Details

create

public static TcpClient create()

Prepare a pooled TcpClient.

Returns:

a TcpClient

create

public static TcpClient create(ConnectionProvider provider)

Prepare a TcpClient.

Parameters:

provider - a ConnectionProvider to acquire connections

Returns:

a TcpClient

newConnection

public static TcpClient newConnection()

Prepare a non pooled TcpClient.

Returns:

a TcpClient

addressSupplier

@Deprecated
public final TcpClient addressSupplier(Supplier<? extends SocketAddress> connectAddressSupplier)

Deprecated.

Use remoteAddress(Supplier). This method will be removed in version 1.1.0.

The address to which this client should connect for each subscribe.

Parameters:

connectAddressSupplier - A supplier of the address to connect to.

Returns:

a new TcpClient

attr

public <A> TcpClient attr(AttributeKey<A> key,
 @Nullable A value)

Description copied from class: Transport

Update the given attribute key or remove it if the value is null.

Overrides:

attr in class Transport<TcpClient,TcpClientConfig>

Type Parameters:

A - the attribute type

Parameters:

key - the AttributeKey key

value - the AttributeKey value

Returns:

a new Transport reference

bindAddress

public TcpClient bindAddress(Supplier<? extends SocketAddress> bindAddressSupplier)

Description copied from class: Transport

Set a new local address to which this transport should bind on subscribe.

Overrides:

bindAddress in class Transport<TcpClient,TcpClientConfig>

Parameters:

bindAddressSupplier - A supplier of the address to bind to.

Returns:

a new Transport

bootstrap

@Deprecated
public final TcpClient bootstrap(Function<? super Bootstrap,? extends Bootstrap> bootstrapMapper)

Deprecated.

as of 0.9.10. Use the other methods exposed by TcpClient to achieve the same configurations. The method will be removed in version 1.1.0.

Apply a Bootstrap mapping function to update TcpClient configuration and return an enriched TcpClient to use.

Note: There isn't only one method that replaces this deprecated method. The configuration that can be done with this deprecated method, can also be done with the other methods exposed by TcpClient.

Examples:

Configuration via the deprecated '.bootstrap(...)' method

 
 TcpClient.bootstrap(b ->
     b.attr(...) // configures the channel attributes
      .group(...) // configures the event loop group
      .handler(...) // configures the channel handler
      .localAddress(...) // configures the bind (local) address
      .option(...) // configures the channel options
      .remoteAddress(...) // configures the remote address
      .resolver(...)) // configures the host names resolver
 
 

Configuration via the other methods exposed by TcpClient

 
 TcpClient.attr(...) // configures the channel attributes
          .runOn(...) // configures the event loop group
          .doOnChannelInit(...) // configures the channel handler
          .bindAddress(...) // configures the bind (local) address
          .option(...) // configures the channel options
          .remoteAddress(...) // configures the remote address
          .resolver(...) // configures the host names resolver
 
 

Wire logging in plain text

 
 TcpClient.wiretap("logger", LogLevel.DEBUG, AdvancedByteBufFormat.TEXTUAL)
 
 

Parameters:

bootstrapMapper - A Bootstrap mapping function to update TcpClient configuration and return an enriched TcpClient to use.

Returns:

a new TcpClient

connect

public Mono<? extends Connection> connect()

Description copied from class: ClientTransport

Connect the ClientTransport and return a Mono of Connection. If Mono is cancelled, the underlying connection will be aborted. Once the Connection has been emitted and is not necessary anymore, disposing must be done by the user via DisposableChannel.dispose().

Overrides:

connect in class ClientTransport<TcpClient,TcpClientConfig>

Returns:

a Mono of Connection

connectNow

public final Connection connectNow()

Description copied from class: ClientTransport

Block the ClientTransport and return a Connection. Disposing must be done by the user via DisposableChannel.dispose(). The max connection timeout is 45 seconds.

Overrides:

connectNow in class ClientTransport<TcpClient,TcpClientConfig>

Returns:

a Connection

connectNow

public final Connection connectNow(Duration timeout)

Description copied from class: ClientTransport

Block the ClientTransport and return a Connection. Disposing must be done by the user via DisposableChannel.dispose().

Overrides:

connectNow in class ClientTransport<TcpClient,TcpClientConfig>

Parameters:

timeout - connect timeout (resolution: ns)

Returns:

a Connection

doOnConnect

public TcpClient doOnConnect(Consumer<? super TcpClientConfig> doOnConnect)

Description copied from class: ClientTransport

Set or add a callback called when ClientTransport is about to connect to the remote endpoint.

Overrides:

doOnConnect in class ClientTransport<TcpClient,TcpClientConfig>

Parameters:

doOnConnect - a consumer observing connect events

Returns:

a new ClientTransport reference

doOnConnected

public TcpClient doOnConnected(Consumer<? super Connection> doOnConnected)

Description copied from class: ClientTransport

Set or add a callback called after Connection has been connected.

Overrides:

doOnConnected in class ClientTransport<TcpClient,TcpClientConfig>

Parameters:

doOnConnected - a consumer observing connected events

Returns:

a new ClientTransport reference

doOnDisconnected

public TcpClient doOnDisconnected(Consumer<? super Connection> doOnDisconnected)

Description copied from class: ClientTransport

Set or add a callback called after Connection has been disconnected.

Overrides:

doOnDisconnected in class ClientTransport<TcpClient,TcpClientConfig>

Parameters:

doOnDisconnected - a consumer observing disconnected events

Returns:

a new ClientTransport reference

handle

public TcpClient handle(BiFunction<? super NettyInbound,? super NettyOutbound,? extends Publisher<Void>> handler)

Attach an IO handler to react on connected client.

Parameters:

handler - an IO handler that can dispose underlying connection when Publisher terminates.

Returns:

a new TcpClient

host

public TcpClient host(String host)

Description copied from class: ClientTransport

The host to which this client should connect.

Overrides:

host in class ClientTransport<TcpClient,TcpClientConfig>

Parameters:

host - the host to connect to

Returns:

a new ClientTransport reference

metrics

public TcpClient metrics(boolean enable)

Description copied from class: Transport

Whether to enable metrics to be collected and registered in Micrometer's globalRegistry. Applications can separately register their own filters. For example, to put an upper bound on the number of tags produced:

 MeterFilter filter = ... ;
 Metrics.globalRegistry.config().meterFilter(MeterFilter.maximumAllowableTags(prefix, 100, filter));
 

By default this is not enabled.

Overrides:

metrics in class Transport<TcpClient,TcpClientConfig>

Parameters:

enable - true enables metrics collection; false disables it

Returns:

a new Transport reference

metrics

public TcpClient metrics(boolean enable,
 Supplier<? extends ChannelMetricsRecorder> recorder)

Description copied from class: Transport

Specifies whether the metrics are enabled on the Transport. All generated metrics are provided to the specified recorder which is only instantiated if metrics are being enabled (the instantiation is not lazy, but happens immediately, while configuring the Transport).

Overrides:

metrics in class Transport<TcpClient,TcpClientConfig>

Parameters:

enable - if true enables the metrics on the Transport.

recorder - a supplier for the ChannelMetricsRecorder

Returns:

a new Transport reference

noProxy

public TcpClient noProxy()

Description copied from class: ClientTransport

Remove any previously applied Proxy configuration customization.

Overrides:

noProxy in class ClientTransport<TcpClient,TcpClientConfig>

Returns:

a new ClientTransport reference

noSSL

public TcpClient noSSL()

Remove any previously applied SSL configuration customization.

Returns:

a new TcpClient

observe

public TcpClient observe(ConnectionObserver observer)

Description copied from class: Transport

Set or add the given ConnectionObserver to observe the connection state changes.

Overrides:

observe in class Transport<TcpClient,TcpClientConfig>

Parameters:

observer - the ConnectionObserver to be set or add

Returns:

a new Transport reference

option

public <O> TcpClient option(ChannelOption<O> key,
 @Nullable O value)

Description copied from class: Transport

Update the given option key or remove it if the value is null. Note: Setting ChannelOption.AUTO_READ option will be ignored. It is configured to be false.

Overrides:

option in class Transport<TcpClient,TcpClientConfig>

Type Parameters:

O - the option type

Parameters:

key - the ChannelOption key

value - the ChannelOption value or null

Returns:

a new Transport reference

port

public TcpClient port(int port)

The port to which this client should connect. If a port is not specified, the default port 12012 is used.

Note: The port can be specified also with PORT environment variable.

Overrides:

port in class ClientTransport<TcpClient,TcpClientConfig>

Parameters:

port - the port to connect to

Returns:

a new TcpClient

proxy

public TcpClient proxy(Consumer<? super ProxyProvider.TypeSpec> proxyOptions)

Description copied from class: ClientTransport

Apply a proxy configuration.

Overrides:

proxy in class ClientTransport<TcpClient,TcpClientConfig>

Parameters:

proxyOptions - the proxy configuration callback

Returns:

a new ClientTransport reference

remoteAddress

public TcpClient remoteAddress(Supplier<? extends SocketAddress> remoteAddressSupplier)

Description copied from class: ClientTransport

The address to which this client should connect on each subscribe.

Overrides:

remoteAddress in class ClientTransport<TcpClient,TcpClientConfig>

Parameters:

remoteAddressSupplier - A supplier of the address to connect to.

Returns:

a new ClientTransport

resolver

public TcpClient resolver(AddressResolverGroup<?> resolver)

Description copied from class: ClientTransport

Assign an AddressResolverGroup.

Overrides:

resolver in class ClientTransport<TcpClient,TcpClientConfig>

Parameters:

resolver - the new AddressResolverGroup

Returns:

a new ClientTransport reference

runOn

public TcpClient runOn(EventLoopGroup eventLoopGroup)

Description copied from class: Transport

Run IO loops on the given EventLoopGroup.

Overrides:

runOn in class Transport<TcpClient,TcpClientConfig>

Parameters:

eventLoopGroup - an eventLoopGroup to share

Returns:

a new Transport reference

runOn

public TcpClient runOn(LoopResources channelResources)

Description copied from class: Transport

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

Overrides:

runOn in class Transport<TcpClient,TcpClientConfig>

Parameters:

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

Returns:

a new Transport reference

runOn

public TcpClient runOn(LoopResources loopResources,
 boolean preferNative)

Description copied from class: Transport

Run IO loops on a supplied EventLoopGroup from the LoopResources container.

Overrides:

runOn in class ClientTransport<TcpClient,TcpClientConfig>

Parameters:

loopResources - a new loop resources

preferNative - should prefer running on epoll, io_uring, kqueue or similar instead of java NIO

Returns:

a new Transport reference

secure

public TcpClient secure()

Enable default sslContext support. The default SslContext will be assigned to with a default value of:

• 10 seconds handshake timeout unless the environment property reactor.netty.tcp.sslHandshakeTimeout is set.
• 3 seconds close_notify flush timeout
• 0 second close_notify read timeout

Returns:

a new TcpClient

secure

public TcpClient secure(Consumer<? super SslProvider.SslContextSpec> sslProviderBuilder)

Apply 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.
• 3 seconds close_notify flush timeout
• 0 second close_notify read timeout

Parameters:

sslProviderBuilder - builder callback for further customization of SslContext.

Returns:

a new TcpClient

secure

public TcpClient secure(SslProvider sslProvider)

Apply an SSL configuration via the passed SslProvider.

Parameters:

sslProvider - The provider to set when configuring SSL

Returns:

a new TcpClient

warmup

public Mono<Void> warmup()

Based on the actual configuration, returns a Mono that triggers:

• an initialization of the event loop group
• an initialization of the host name resolver
• loads the necessary native libraries for the transport
• loads the necessary native libraries for the security if there is such

By default, when method is not used, the connect operation absorbs the extra time needed to load resources.

Overrides:

warmup in class ClientTransport<TcpClient,TcpClientConfig>

Returns:

a Mono representing the completion of the warmup

Since:

1.0.3

wiretap

public TcpClient wiretap(boolean enable)

Description copied from class: Transport

Apply or remove a wire logger configuration using Transport category (logger), DEBUG logger level and AdvancedByteBufFormat.HEX_DUMP for ByteBuf format, which means both events and content will be logged and the content will be in hex format.

Overrides:

wiretap in class Transport<TcpClient,TcpClientConfig>

Parameters:

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

Returns:

a new Transport reference

wiretap

public TcpClient wiretap(String category)

Description copied from class: Transport

Apply a wire logger configuration using the specified category (logger), DEBUG logger level and AdvancedByteBufFormat.HEX_DUMP for ByteBuf format, which means both events and content will be logged and the content will be in hex format.

Overrides:

wiretap in class Transport<TcpClient,TcpClientConfig>

Parameters:

category - the logger category

Returns:

a new Transport reference

wiretap

public TcpClient wiretap(String category,
 LogLevel level)

Description copied from class: Transport

Apply a wire logger configuration using the specified category (logger), logger level and AdvancedByteBufFormat.HEX_DUMP for ByteBuf format, which means both events and content will be logged and the content will be in hex format.

Overrides:

wiretap in class Transport<TcpClient,TcpClientConfig>

Parameters:

category - the logger category

level - the logger level

Returns:

a new Transport reference