public class RSocketConnector extends Object
For using TCP using default settings:
import io.rsocket.transport.netty.client.TcpClientTransport;
Mono<RSocket> source =
RSocketConnector.connectWith(TcpClientTransport.create("localhost", 7000));
RSocketClient client = RSocketClient.from(source);
To customize connection settings before connecting:
Mono<RSocket> source =
RSocketConnector.create()
.metadataMimeType("message/x.rsocket.composite-metadata.v0")
.dataMimeType("application/cbor")
.connect(TcpClientTransport.create("localhost", 7000));
RSocketClient client = RSocketClient.from(source);
Modifier and Type | Method and Description |
---|---|
RSocketConnector |
acceptor(SocketAcceptor acceptor)
Configure a client-side
SocketAcceptor for responding to requests from the server. |
Mono<RSocket> |
connect(ClientTransport transport)
Connect with the given transport and obtain a live
RSocket to use for making requests. |
Mono<RSocket> |
connect(Supplier<ClientTransport> transportSupplier)
|
static Mono<RSocket> |
connectWith(ClientTransport transport)
Static factory method to connect with default settings, effectively a shortcut for:
RSocketConnector.create().connect(transport); |
static RSocketConnector |
create()
Static factory method to create an
RSocketConnector instance and customize default
settings before connecting. |
RSocketConnector |
dataMimeType(String dataMimeType)
Set the MIME type to use for formatting payload data on the established connection.
|
RSocketConnector |
fragment(int mtu)
When this is set, frames larger than the given maximum transmission unit (mtu) size value are
broken down into fragments to fit that size.
|
RSocketConnector |
interceptors(Consumer<InterceptorRegistry> configurer)
Configure interception at one of the following levels:
Transport level
At the level of accepting new connections
Performing requests
Responding to requests
|
RSocketConnector |
keepAlive(Duration interval,
Duration maxLifeTime)
Set the "Time Between
KEEPALIVE Frames" which is how frequently KEEPALIVE
frames should be emitted, and the "Max Lifetime" which is how long to allow between KEEPALIVE frames from the remote end before concluding that connectivity is lost. |
RSocketConnector |
lease()
Enables the Lease feature of the RSocket protocol where the number of requests that can be
performed from either side are rationed via
LEASE frames from the responder side. |
RSocketConnector |
lease(Consumer<LeaseSpec> leaseConfigurer)
Enables the Lease feature of the RSocket protocol where the number of requests that can be
performed from either side are rationed via
LEASE frames from the responder side. |
RSocketConnector |
maxInboundPayloadSize(int maxInboundPayloadSize)
When this is set, frames reassembler control maximum payload size which can be reassembled.
|
RSocketConnector |
metadataMimeType(String metadataMimeType)
Set the MIME type to use for formatting payload metadata on the established connection.
|
RSocketConnector |
payloadDecoder(PayloadDecoder decoder)
Configure the
PayloadDecoder used to create Payload 's from incoming raw frame
buffers. |
RSocketConnector |
reconnect(Retry retry)
When this is enabled, the connect methods of this class return a special
Mono<RSocket>
that maintains a single, shared RSocket for all subscribers: |
RSocketConnector |
resume(Resume resume)
Enables the Resume capability of the RSocket protocol where if the client gets disconnected,
the connection is re-acquired and any interrupted streams are resumed automatically.
|
RSocketConnector |
setupPayload(Mono<Payload> setupPayloadMono)
Provide a
Mono from which to obtain the Payload for the initial SETUP frame. |
RSocketConnector |
setupPayload(Payload payload)
Variant of
setupPayload(Mono) that accepts a Payload instance. |
public static RSocketConnector create()
RSocketConnector
instance and customize default
settings before connecting. To connect only, use connectWith(ClientTransport)
.public static Mono<RSocket> connectWith(ClientTransport transport)
RSocketConnector.create().connect(transport);
transport
- the transport of choice to connect withMono
with the connected RSocketpublic RSocketConnector setupPayload(Mono<Payload> setupPayloadMono)
Mono
from which to obtain the Payload
for the initial SETUP frame.
Data and metadata should be formatted according to the MIME types specified via dataMimeType(String)
and metadataMimeType(String)
.setupPayloadMono
- the payload with data and/or metadata for the SETUP
frame.public RSocketConnector setupPayload(Payload payload)
setupPayload(Mono)
that accepts a Payload
instance.
Note: if the given payload is ByteBufPayload
, it is copied to a
DefaultPayload
and released immediately. This ensures it can re-used to obtain a
connection more than once.
payload
- the payload with data and/or metadata for the SETUP
frame.public RSocketConnector dataMimeType(String dataMimeType)
SETUP
frame sent to the server.
By default this is set to "application/binary"
.
dataMimeType
- the MIME type to be used for payload datapublic RSocketConnector metadataMimeType(String metadataMimeType)
SETUP
frame sent to the server.
For metadata encoding, consider using one of the following encoders:
For more on the above metadata formats, see the corresponding protocol extensions
By default this is set to "application/binary"
.
metadataMimeType
- the MIME type to be used for payload metadatapublic RSocketConnector keepAlive(Duration interval, Duration maxLifeTime)
KEEPALIVE
Frames" which is how frequently KEEPALIVE
frames should be emitted, and the "Max Lifetime" which is how long to allow between KEEPALIVE
frames from the remote end before concluding that connectivity is lost. Both
settings are specified in the initial SETUP
frame sent to the server. The spec mentions
the following:
KEEPALIVE
frames is 500ms.
KEEPALIVE
frames is often >
30,000ms.
By default these are set to 20 seconds and 90 seconds respectively.
interval
- how frequently to emit KEEPALIVE framesmaxLifeTime
- how long to allow between KEEPALIVE
frames from the remote end
before assuming that connectivity is lost; the value should be generous and allow for
multiple missed KEEPALIVE
frames.public RSocketConnector interceptors(Consumer<InterceptorRegistry> configurer)
configurer
- a configurer to customize interception with.LimitRateInterceptor
public RSocketConnector acceptor(SocketAcceptor acceptor)
SocketAcceptor
for responding to requests from the server.
A full-form example with access to the SETUP
frame and the "sending" RSocket (the
same as the one returned from connect(ClientTransport)
):
Mono<RSocket> rsocketMono =
RSocketConnector.create()
.acceptor((setup, sendingRSocket) -> Mono.just(new RSocket() {...}))
.connect(transport);
A shortcut example with just the handling RSocket:
Mono<RSocket> rsocketMono =
RSocketConnector.create()
.acceptor(SocketAcceptor.with(new RSocket() {...})))
.connect(transport);
A shortcut example handling only request-response:
Mono<RSocket> rsocketMono =
RSocketConnector.create()
.acceptor(SocketAcceptor.forRequestResponse(payload -> ...))
.connect(transport);
By default, new RSocket(){}
is used which rejects all requests from the server with
UnsupportedOperationException
.
acceptor
- the acceptor to use for responding to server requestspublic RSocketConnector reconnect(Retry retry)
Mono<RSocket>
that maintains a single, shared RSocket
for all subscribers:
Mono<RSocket> rsocketMono =
RSocketConnector.create()
.reconnect(Retry.fixedDelay(3, Duration.ofSeconds(1)))
.connect(transport);
RSocket r1 = rsocketMono.block();
RSocket r2 = rsocketMono.block();
assert r1 == r2;
The RSocket
remains cached until the connection is lost and after that, new attempts
to subscribe or re-subscribe trigger a reconnect and result in a new shared RSocket
:
Mono<RSocket> rsocketMono =
RSocketConnector.create()
.reconnect(Retry.fixedDelay(3, Duration.ofSeconds(1)))
.connect(transport);
RSocket r1 = rsocketMono.block();
RSocket r2 = rsocketMono.block();
r1.dispose();
RSocket r3 = rsocketMono.block();
RSocket r4 = rsocketMono.block();
assert r1 == r2;
assert r3 == r4;
assert r1 != r3;
Downstream subscribers for individual requests still need their own retry logic to determine if or when failed requests should be retried which in turn triggers the shared reconnect:
Mono<RSocket> rocketMono =
RSocketConnector.create()
.reconnect(Retry.fixedDelay(3, Duration.ofSeconds(1)))
.connect(transport);
rsocketMono.flatMap(rsocket -> rsocket.requestResponse(...))
.retryWhen(Retry.fixedDelay(1, Duration.ofSeconds(5)))
.subscribe()
Note: this feature is mutually exclusive with resume(Resume)
. If
both are enabled, "resume" takes precedence. Consider using "reconnect" when the server does
not have "resume" enabled or supported, or when you don't need to incur the overhead of saving
in-flight frames to be potentially replayed after a reconnect.
By default this is not enabled in which case a new connection is obtained per subscriber.
retry
- a retry spec that declares the rules for reconnectingpublic RSocketConnector resume(Resume resume)
See Resume
for settings to customize the Resume capability.
Note: this feature is mutually exclusive with reconnect(Retry)
. If
both are enabled, "resume" takes precedence. Consider using "reconnect" when the server does
not have "resume" enabled or supported, or when you don't need to incur the overhead of saving
in-flight frames to be potentially replayed after a reconnect.
By default this is not enabled.
resume
- configuration for the Resume capabilitypublic RSocketConnector lease()
LEASE
frames from the responder side.
Example usage:
Mono<RSocket> rocketMono =
RSocketConnector.create()
.lease()
.connect(transport);
By default this is not enabled.
public RSocketConnector lease(Consumer<LeaseSpec> leaseConfigurer)
LEASE
frames from the responder side.
Example usage:
Mono<RSocket> rocketMono =
RSocketConnector.create()
.lease(spec -> spec.maxPendingRequests(128))
.connect(transport);
By default this is not enabled.
leaseConfigurer
- consumer which accepts LeaseSpec
and use it for configuringpublic RSocketConnector maxInboundPayloadSize(int maxInboundPayloadSize)
By default this is not set in which case maximum reassembled payloads size is not controlled.
maxInboundPayloadSize
- the threshold size for reassembly, must no be less than 64 bytes.
Please note, maxInboundPayloadSize
must always be greater or equal to Transport.maxFrameLength()
, otherwise inbound frame can exceed the
maxInboundPayloadSize
public RSocketConnector fragment(int mtu)
By default this is not set in which case payloads are sent whole up to the maximum frame size of 16,777,215 bytes.
mtu
- the threshold size for fragmentation, must be no less than 64public RSocketConnector payloadDecoder(PayloadDecoder decoder)
PayloadDecoder
used to create Payload
's from incoming raw frame
buffers. The following decoders are available:
PayloadDecoder.DEFAULT
-- the data and metadata are independent copies of the
underlying frame ByteBuf
PayloadDecoder.ZERO_COPY
-- the data and metadata are retained slices of the
underlying ByteBuf
. That's more efficient but requires careful tracking and
release
of the payload when no longer needed.
By default this is set to PayloadDecoder.DEFAULT
in which case data and metadata are
copied and do not need to be tracked and released.
decoder
- the decoder to usepublic Mono<RSocket> connect(ClientTransport transport)
RSocket
to use for making requests.
Each subscriber to the returned Mono
receives a new connection, if neither reconnect
nor resume(Resume)
are enabled.
The following transports are available through additional RSocket Java modules:
TcpClientTransport
via
rsocket-transport-netty
.
WebsocketClientTransport
via rsocket-transport-netty
.
LocalClientTransport
via rsocket-transport-local
transport
- the transport of choice to connect withMono
with the connected RSocketpublic Mono<RSocket> connect(Supplier<ClientTransport> transportSupplier)
transportSupplier
- supplier for the transport to connect withMono
with the connected RSocket