RSocketConnector (rsocket-core 1.1.1 API)

java.lang.Object
- io.rsocket.core.RSocketConnector

public class RSocketConnector
extends Object

The main class to use to establish a connection to an RSocket server.

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);

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
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)` Variant of `connect(ClientTransport)` with a `Supplier` for the `ClientTransport`.
`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.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - create
```
public static RSocketConnector create()
```
    Static factory method to create an RSocketConnector instance and customize default settings before connecting. To connect only, use connectWith(ClientTransport).
  - connectWith
```
public static Mono<RSocket> connectWith(ClientTransport transport)
```
    Static factory method to connect with default settings, effectively a shortcut for:
```
 RSocketConnector.create().connect(transport);
 
```
    Parameters:
    
    transport - the transport of choice to connect with
    
    Returns:
    
    a Mono with the connected RSocket
  - setupPayload
```
public RSocketConnector setupPayload(Mono<Payload> setupPayloadMono)
```
    Provide a 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).
    
    Parameters:
    
    setupPayloadMono - the payload with data and/or metadata for the SETUP frame.
    
    Returns:
    
    the same instance for method chaining
    
    Since:
    
    1.0.2
    
    See Also:
    
    SETUP Frame
  - setupPayload
```
public RSocketConnector setupPayload(Payload payload)
```
    Variant of 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.
    
    Parameters:
    
    payload - the payload with data and/or metadata for the SETUP frame.
    
    Returns:
    
    the same instance for method chaining
    
    See Also:
    
    SETUP Frame
  - dataMimeType
```
public RSocketConnector dataMimeType(String dataMimeType)
```
    Set the MIME type to use for formatting payload data on the established connection. This is set in the initial SETUP frame sent to the server.
    By default this is set to "application/binary".
    
    Parameters:
    
    dataMimeType - the MIME type to be used for payload data
    
    Returns:
    
    the same instance for method chaining
    
    See Also:
    
    SETUP Frame
  - metadataMimeType
```
public RSocketConnector metadataMimeType(String metadataMimeType)
```
    Set the MIME type to use for formatting payload metadata on the established connection. This is set in the initial 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".
    Parameters:
    
    metadataMimeType - the MIME type to be used for payload metadata
    
    Returns:
    
    the same instance for method chaining
    
    See Also:
    
    SETUP Frame
  - keepAlive
```
public 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. Both settings are specified in the initial SETUP frame sent to the server. The spec mentions the following:
    - For server-to-server connections, a reasonable time interval between client KEEPALIVE frames is 500ms.
    - For mobile-to-server connections, the time interval between client KEEPALIVE frames is often > 30,000ms.
    By default these are set to 20 seconds and 90 seconds respectively.
    Parameters:
    
    interval - how frequently to emit KEEPALIVE frames
    
    maxLifeTime - 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.
    
    Returns:
    
    the same instance for method chaining
    
    See Also:
    
    SETUP Frame
  - interceptors
```
public 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
    Parameters:
    
    configurer - a configurer to customize interception with.
    
    Returns:
    
    the same instance for method chaining
    
    See Also:
    
    LimitRateInterceptor
  - acceptor
```
public RSocketConnector acceptor(SocketAcceptor acceptor)
```
    Configure a client-side 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.
    Parameters:
    
    acceptor - the acceptor to use for responding to server requests
    
    Returns:
    
    the same instance for method chaining
  - reconnect
```
public 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:
```
 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.
    Parameters:
    
    retry - a retry spec that declares the rules for reconnecting
    
    Returns:
    
    the same instance for method chaining
  - resume
```
public 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. For this to work the server must also support and have the Resume capability enabled.
    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.
    
    Parameters:
    
    resume - configuration for the Resume capability
    
    Returns:
    
    the same instance for method chaining
    
    See Also:
    
    Resuming Operation
  - lease
```
public 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.
    Example usage:
```
 Mono<RSocket> rocketMono =
         RSocketConnector.create()
                         .lease()
                         .connect(transport);
 
```
    By default this is not enabled.
    Returns:
    
    the same instance for method chaining
    
    See Also:
    
    Lease Semantics
  - lease
```
public 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.
    Example usage:
```
 Mono<RSocket> rocketMono =
         RSocketConnector.create()
                         .lease(spec -> spec.maxPendingRequests(128))
                         .connect(transport);
 
```
    By default this is not enabled.
    Parameters:
    
    leaseConfigurer - consumer which accepts LeaseSpec and use it for configuring
    
    Returns:
    
    the same instance for method chaining
    
    See Also:
    
    Lease Semantics
  - maxInboundPayloadSize
```
public RSocketConnector maxInboundPayloadSize(int maxInboundPayloadSize)
```
    When this is set, frames reassembler control maximum payload size which can be reassembled.
    By default this is not set in which case maximum reassembled payloads size is not controlled.
    
    Parameters:
    
    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
    
    Returns:
    
    the same instance for method chaining
    
    See Also:
    
    Fragmentation and Reassembly
  - fragment
```
public 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.
    By default this is not set in which case payloads are sent whole up to the maximum frame size of 16,777,215 bytes.
    
    Parameters:
    
    mtu - the threshold size for fragmentation, must be no less than 64
    
    Returns:
    
    the same instance for method chaining
    
    See Also:
    
    Fragmentation and Reassembly
  - payloadDecoder
```
public RSocketConnector payloadDecoder(PayloadDecoder decoder)
```
    Configure the 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.
    Parameters:
    
    decoder - the decoder to use
    
    Returns:
    
    the same instance for method chaining
  - connect
```
public Mono<RSocket> connect(ClientTransport transport)
```
    Connect with the given transport and obtain a live 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
    Parameters:
    
    transport - the transport of choice to connect with
    
    Returns:
    
    a Mono with the connected RSocket
  - connect
```
public Mono<RSocket> connect(Supplier<ClientTransport> transportSupplier)
```
    Variant of connect(ClientTransport) with a Supplier for the ClientTransport.
    // TODO: when to use?
    
    Parameters:
    
    transportSupplier - supplier for the transport to connect with
    
    Returns:
    
    a Mono with the connected RSocket

Class RSocketConnector

Method Summary

Methods inherited from class java.lang.Object

Method Detail

create

connectWith

setupPayload

setupPayload

dataMimeType

metadataMimeType

keepAlive

interceptors

acceptor

reconnect

resume

lease

lease

maxInboundPayloadSize

fragment

payloadDecoder

connect

connect