Package reactor.netty.tcp
Class TcpClient
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 -
Method Summary
Modifier and TypeMethodDescriptionfinal TcpClient
addressSupplier
(Supplier<? extends SocketAddress> connectAddressSupplier) Deprecated.<A> TcpClient
attr
(AttributeKey<A> key, @Nullable A value) Update the given attribute key or remove it if the value is null.bindAddress
(Supplier<? extends SocketAddress> bindAddressSupplier) Set a new local address to which this transport should bind on subscribe.final TcpClient
Deprecated.as of 0.9.10.Mono<? extends Connection>
connect()
final Connection
Block theClientTransport
and return aConnection
.final Connection
connectNow
(Duration timeout) Block theClientTransport
and return aConnection
.static TcpClient
create()
Prepare a pooledTcpClient
.static TcpClient
create
(ConnectionProvider provider) Prepare aTcpClient
.doOnConnect
(Consumer<? super TcpClientConfig> doOnConnect) Set or add a callback called whenClientTransport
is about to connect to the remote endpoint.doOnConnected
(Consumer<? super Connection> doOnConnected) Set or add a callback called afterConnection
has been connected.doOnDisconnected
(Consumer<? super Connection> doOnDisconnected) Set or add a callback called afterConnection
has been disconnected.handle
(BiFunction<? super NettyInbound, ? super NettyOutbound, ? extends Publisher<Void>> handler) Attach an IO handler to react on connected client.The host to which this client should connect.metrics
(boolean enable) Whether to enable metrics to be collected and registered in Micrometer'sglobalRegistry
.metrics
(boolean enable, Supplier<? extends ChannelMetricsRecorder> recorder) Specifies whether the metrics are enabled on theTransport
.static TcpClient
Prepare a non pooledTcpClient
.noProxy()
Remove any previously applied Proxy configuration customization.noSSL()
Remove any previously applied SSL configuration customization.observe
(ConnectionObserver observer) Set or add the givenConnectionObserver
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.port
(int port) The port to which this client should connect.proxy
(Consumer<? super ProxyProvider.TypeSpec> proxyOptions) Apply a proxy configuration.remoteAddress
(Supplier<? extends SocketAddress> remoteAddressSupplier) The address to which this client should connect on each subscribe.resolver
(AddressResolverGroup<?> resolver) Assign anAddressResolverGroup
.runOn
(EventLoopGroup eventLoopGroup) Run IO loops on the givenEventLoopGroup
.runOn
(LoopResources channelResources) Run IO loops on a suppliedEventLoopGroup
from theLoopResources
container.runOn
(LoopResources loopResources, boolean preferNative) Run IO loops on a suppliedEventLoopGroup
from theLoopResources
container.secure()
Enable default sslContext support.secure
(Consumer<? super SslProvider.SslContextSpec> sslProviderBuilder) Apply an SSL configuration customization via the passed builder.secure
(SslProvider sslProvider) Apply an SSL configuration via the passedSslProvider
.warmup()
Based on the actual configuration, returns aMono
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, theconnect operation
absorbs the extra time needed to load resources.wiretap
(boolean enable) Apply or remove a wire logger configuration usingTransport
category (logger),DEBUG
logger level andAdvancedByteBufFormat.HEX_DUMP
forByteBuf
format, which means both events and content will be logged and the content will be in hex format.Apply a wire logger configuration using the specified category (logger),DEBUG
logger level andAdvancedByteBufFormat.HEX_DUMP
forByteBuf
format, which means both events and content will be logged and the content will be in hex format.Apply a wire logger configuration using the specified category (logger), logger level andAdvancedByteBufFormat.HEX_DUMP
forByteBuf
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
-
Constructor Details
-
TcpClient
public TcpClient()
-
-
Method Details
-
create
Prepare a pooledTcpClient
.- Returns:
- a
TcpClient
-
create
Prepare aTcpClient
.- Parameters:
provider
- aConnectionProvider
to acquire connections- Returns:
- a
TcpClient
-
newConnection
Prepare a non pooledTcpClient
.- Returns:
- a
TcpClient
-
addressSupplier
@Deprecated public final TcpClient addressSupplier(Supplier<? extends SocketAddress> connectAddressSupplier) Deprecated.UseremoteAddress(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
Description copied from class:Transport
Update the given attribute key or remove it if the value is null.- Overrides:
attr
in classTransport<TcpClient,
TcpClientConfig> - Type Parameters:
A
- the attribute type- Parameters:
key
- theAttributeKey
keyvalue
- theAttributeKey
value- Returns:
- a new
Transport
reference
-
bindAddress
Description copied from class:Transport
Set a new local address to which this transport should bind on subscribe.- Overrides:
bindAddress
in classTransport<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 byTcpClient
to achieve the same configurations. The method will be removed in version 1.1.0.Apply aBootstrap
mapping function to updateTcpClient
configuration and return an enrichedTcpClient
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)
-
connect
Description copied from class:ClientTransport
Connect theClientTransport
and return aMono
ofConnection
. IfMono
is cancelled, the underlying connection will be aborted. Once theConnection
has been emitted and is not necessary anymore, disposing must be done by the user viaDisposableChannel.dispose()
.- Overrides:
connect
in classClientTransport<TcpClient,
TcpClientConfig> - Returns:
- a
Mono
ofConnection
-
connectNow
Description copied from class:ClientTransport
Block theClientTransport
and return aConnection
. Disposing must be done by the user viaDisposableChannel.dispose()
. The max connection timeout is 45 seconds.- Overrides:
connectNow
in classClientTransport<TcpClient,
TcpClientConfig> - Returns:
- a
Connection
-
connectNow
Description copied from class:ClientTransport
Block theClientTransport
and return aConnection
. Disposing must be done by the user viaDisposableChannel.dispose()
.- Overrides:
connectNow
in classClientTransport<TcpClient,
TcpClientConfig> - Parameters:
timeout
- connect timeout (resolution: ns)- Returns:
- a
Connection
-
doOnConnect
Description copied from class:ClientTransport
Set or add a callback called whenClientTransport
is about to connect to the remote endpoint.- Overrides:
doOnConnect
in classClientTransport<TcpClient,
TcpClientConfig> - Parameters:
doOnConnect
- a consumer observing connect events- Returns:
- a new
ClientTransport
reference
-
doOnConnected
Description copied from class:ClientTransport
Set or add a callback called afterConnection
has been connected.- Overrides:
doOnConnected
in classClientTransport<TcpClient,
TcpClientConfig> - Parameters:
doOnConnected
- a consumer observing connected events- Returns:
- a new
ClientTransport
reference
-
doOnDisconnected
Description copied from class:ClientTransport
Set or add a callback called afterConnection
has been disconnected.- Overrides:
doOnDisconnected
in classClientTransport<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. -
host
Description copied from class:ClientTransport
The host to which this client should connect.- Overrides:
host
in classClientTransport<TcpClient,
TcpClientConfig> - Parameters:
host
- the host to connect to- Returns:
- a new
ClientTransport
reference
-
metrics
Description copied from class:Transport
Whether to enable metrics to be collected and registered in Micrometer'sglobalRegistry
. Applications can separately register their ownfilters
. 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 classTransport<TcpClient,
TcpClientConfig> - Parameters:
enable
- true enables metrics collection; false disables it- Returns:
- a new
Transport
reference
-
metrics
Description copied from class:Transport
Specifies whether the metrics are enabled on theTransport
. 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 theTransport
).- Overrides:
metrics
in classTransport<TcpClient,
TcpClientConfig> - Parameters:
enable
- if true enables the metrics on theTransport
.recorder
- a supplier for theChannelMetricsRecorder
- Returns:
- a new
Transport
reference
-
noProxy
Description copied from class:ClientTransport
Remove any previously applied Proxy configuration customization.- Overrides:
noProxy
in classClientTransport<TcpClient,
TcpClientConfig> - Returns:
- a new
ClientTransport
reference
-
noSSL
Remove any previously applied SSL configuration customization.- Returns:
- a new
TcpClient
-
observe
Description copied from class:Transport
Set or add the givenConnectionObserver
to observe the connection state changes.- Overrides:
observe
in classTransport<TcpClient,
TcpClientConfig> - Parameters:
observer
- theConnectionObserver
to be set or add- Returns:
- a new
Transport
reference
-
option
Description copied from class:Transport
Update the given option key or remove it if the value is null. Note: SettingChannelOption.AUTO_READ
option will be ignored. It is configured to befalse
.- Overrides:
option
in classTransport<TcpClient,
TcpClientConfig> - Type Parameters:
O
- the option type- Parameters:
key
- theChannelOption
keyvalue
- theChannelOption
value or null- Returns:
- a new
Transport
reference
-
port
The port to which this client should connect. If a port is not specified, the default port12012
is used.Note: The port can be specified also with
PORT
environment variable.- Overrides:
port
in classClientTransport<TcpClient,
TcpClientConfig> - Parameters:
port
- the port to connect to- Returns:
- a new
TcpClient
-
proxy
Description copied from class:ClientTransport
Apply a proxy configuration.- Overrides:
proxy
in classClientTransport<TcpClient,
TcpClientConfig> - Parameters:
proxyOptions
- the proxy configuration callback- Returns:
- a new
ClientTransport
reference
-
remoteAddress
Description copied from class:ClientTransport
The address to which this client should connect on each subscribe.- Overrides:
remoteAddress
in classClientTransport<TcpClient,
TcpClientConfig> - Parameters:
remoteAddressSupplier
- A supplier of the address to connect to.- Returns:
- a new
ClientTransport
-
resolver
Description copied from class:ClientTransport
Assign anAddressResolverGroup
.- Overrides:
resolver
in classClientTransport<TcpClient,
TcpClientConfig> - Parameters:
resolver
- the newAddressResolverGroup
- Returns:
- a new
ClientTransport
reference
-
runOn
Description copied from class:Transport
Run IO loops on the givenEventLoopGroup
.- Overrides:
runOn
in classTransport<TcpClient,
TcpClientConfig> - Parameters:
eventLoopGroup
- an eventLoopGroup to share- Returns:
- a new
Transport
reference
-
runOn
Description copied from class:Transport
Run IO loops on a suppliedEventLoopGroup
from theLoopResources
container. Will prefer native (epoll/io_uring/kqueue) implementation if available unless the environment propertyreactor.netty.native
is set tofalse
.- Overrides:
runOn
in classTransport<TcpClient,
TcpClientConfig> - Parameters:
channelResources
- aLoopResources
accepting native runtime expectation and returning an eventLoopGroup- Returns:
- a new
Transport
reference
-
runOn
Description copied from class:Transport
Run IO loops on a suppliedEventLoopGroup
from theLoopResources
container.- Overrides:
runOn
in classClientTransport<TcpClient,
TcpClientConfig> - Parameters:
loopResources
- a new loop resourcespreferNative
- should prefer running on epoll, io_uring, kqueue or similar instead of java NIO- Returns:
- a new
Transport
reference
-
secure
Enable default sslContext support. The defaultSslContext
will be assigned to with a default value of:10
seconds handshake timeout unless the environment propertyreactor.netty.tcp.sslHandshakeTimeout
is set.3
seconds close_notify flush timeout0
second close_notify read timeout
- Returns:
- a new
TcpClient
-
secure
Apply an SSL configuration customization via the passed builder. The builder will produce theSslContext
to be passed to with a default value of:10
seconds handshake timeout unless the environment propertyreactor.netty.tcp.sslHandshakeTimeout
is set.3
seconds close_notify flush timeout0
second close_notify read timeout
- Parameters:
sslProviderBuilder
- builder callback for further customization of SslContext.- Returns:
- a new
TcpClient
-
secure
Apply an SSL configuration via the passedSslProvider
.- Parameters:
sslProvider
- The provider to set when configuring SSL- Returns:
- a new
TcpClient
-
warmup
Based on the actual configuration, returns aMono
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
connect operation
absorbs the extra time needed to load resources.- Overrides:
warmup
in classClientTransport<TcpClient,
TcpClientConfig> - Returns:
- a
Mono
representing the completion of the warmup - Since:
- 1.0.3
-
wiretap
Description copied from class:Transport
Apply or remove a wire logger configuration usingTransport
category (logger),DEBUG
logger level andAdvancedByteBufFormat.HEX_DUMP
forByteBuf
format, which means both events and content will be logged and the content will be in hex format.- Overrides:
wiretap
in classTransport<TcpClient,
TcpClientConfig> - Parameters:
enable
- specifies whether the wire logger configuration will be added to the pipeline- Returns:
- a new
Transport
reference
-
wiretap
Description copied from class:Transport
Apply a wire logger configuration using the specified category (logger),DEBUG
logger level andAdvancedByteBufFormat.HEX_DUMP
forByteBuf
format, which means both events and content will be logged and the content will be in hex format.- Overrides:
wiretap
in classTransport<TcpClient,
TcpClientConfig> - Parameters:
category
- the logger category- Returns:
- a new
Transport
reference
-
wiretap
Description copied from class:Transport
Apply a wire logger configuration using the specified category (logger), logger level andAdvancedByteBufFormat.HEX_DUMP
forByteBuf
format, which means both events and content will be logged and the content will be in hex format.- Overrides:
wiretap
in classTransport<TcpClient,
TcpClientConfig> - Parameters:
category
- the logger categorylevel
- the logger level- Returns:
- a new
Transport
reference
-
remoteAddress(Supplier)
.