CordaRPCClient
Keywords: net.corda.client.rpc.CordaRPCClient class
Date: 2023-09-18

net.corda.client.rpc

## Class CordaRPCClient

- net.corda.client.rpc.CordaRPCClient

-     public class CordaRPCClient

  An RPC client connects to the specified server and allows you to make calls to the server that perform various useful tasks. Please see the Client RPC section of docs.corda.net to learn more about how this API works. A brief description is provided here.

  Calling `start` returns an `interface RPCConnection` containing a proxy that lets you invoke RPCs on the server. Calls on it block, and if the server throws an exception then it will be rethrown on the client. Proxies are thread safe and may be used to invoke multiple RPCs in parallel.

  RPC sends and receives are logged on the net.corda.rpc logger.

  The `interface CordaRPCOps` defines what client RPCs are available. If an RPC returns an rx.Observable anywhere in the object graph returned then the server-side observable is transparently forwarded to the client side here. You are expected to use it. The server will begin sending messages immediately that will be buffered on the client, you are expected to drain by subscribing to the returned observer. You can opt-out of this by simply calling the `net.corda.client.rpc.notUsed` method on it.

  You don't have to explicitly close the observable if you actually subscribe to it: it will close itself and free up the server-side resources either when the client or JVM itself is shutdown, or when there are no more subscribers to it. Once all the subscribers to a returned observable are unsubscribed or the observable completes successfully or with an error, the observable is closed and you can't then re-subscribe again: you'll have to re-request a fresh observable with another RPC.

  In case of loss of connection to the server, the client will try to reconnect using the settings provided via `class CordaRPCClientConfiguration`. If the client was created using a list of hosts via haAddressPool, automatic failover will occur (the servers have to be started in HA mode). While attempting failover, current and future RPC calls will throw `exception RPCException` and previously returned observables will call onError().

  If you want to enable a more graceful form of reconnection, you can make use of the gracefulReconnect argument of the `start` method. If this is set to true, then:

  - The client will automatically reconnect, when the connection is broken regardless of whether you provided a single or multiple addresses.

  - Simple RPC calls that return data (e.g. `CordaRPCOps.networkParameters`) will block and return after the connection has been re-established and the node is up.

  - RPC calls that return rx.Observables (e.g. `CordaRPCOps.vaultTrack`) will automatically reconnect and keep sending events for the subscribed rx.Observables. Note: In this approach, some events might be lost during a re-connection and not sent in the subscribed rx.Observables.

  - RPC calls that invoke flows (e.g. `CordaRPCOps.startFlowDynamic`) will fail during a disconnection throwing a `exception CouldNotStartFlowException`.

  See Also:
    `start`, `interface RPCConnection`, `interface CordaRPCOps`, `net.corda.client.rpc.notUsed`, `class CordaRPCClientConfiguration`, `exception RPCException`, `start`, `CordaRPCOps.networkParameters`, `CordaRPCOps.vaultTrack`, `CordaRPCOps.startFlowDynamic`, `exception CouldNotStartFlowException`

- - ### Field Detail

    - #### Companion

          public static net.corda.client.rpc.CordaRPCClient.Companion Companion

  - ### Constructor Detail

    - #### CordaRPCClient

          @JvmOverloads
          public CordaRPCClient(@NotNull
                                              NetworkHostAndPort hostAndPort,
                                              @NotNull
                                              CordaRPCClientConfiguration configuration)

    - #### CordaRPCClient

          @JvmOverloads
          public CordaRPCClient(@NotNull
                                              NetworkHostAndPort hostAndPort)

    - #### CordaRPCClient

          public CordaRPCClient(@NotNull
                                NetworkHostAndPort hostAndPort,
                                @NotNull
                                CordaRPCClientConfiguration configuration,
                                @NotNull
                                java.lang.ClassLoader classLoader)

    - #### CordaRPCClient

          public CordaRPCClient(@NotNull
                                NetworkHostAndPort hostAndPort,
                                @Nullable
                                ClientRpcSslOptions sslConfiguration,
                                @Nullable
                                java.lang.ClassLoader classLoader)

    - #### CordaRPCClient

          @JvmOverloads
          public CordaRPCClient(@NotNull
                                              NetworkHostAndPort hostAndPort,
                                              @NotNull
                                              CordaRPCClientConfiguration configuration,
                                              @Nullable
                                              ClientRpcSslOptions sslConfiguration,
                                              @Nullable
                                              java.lang.ClassLoader classLoader)

    - #### CordaRPCClient

          @JvmOverloads
          public CordaRPCClient(@NotNull
                                              NetworkHostAndPort hostAndPort,
                                              @NotNull
                                              CordaRPCClientConfiguration configuration,
                                              @Nullable
                                              ClientRpcSslOptions sslConfiguration)

    - #### CordaRPCClient

          @JvmOverloads
          public CordaRPCClient(@NotNull
                                              java.util.List<net.corda.core.utilities.NetworkHostAndPort> haAddressPool,
                                              @NotNull
                                              CordaRPCClientConfiguration configuration,
                                              @Nullable
                                              ClientRpcSslOptions sslConfiguration,
                                              @Nullable
                                              java.lang.ClassLoader classLoader)

    - #### CordaRPCClient

          @JvmOverloads
          public CordaRPCClient(@NotNull
                                              java.util.List<net.corda.core.utilities.NetworkHostAndPort> haAddressPool,
                                              @NotNull
                                              CordaRPCClientConfiguration configuration,
                                              @Nullable
                                              ClientRpcSslOptions sslConfiguration)

    - #### CordaRPCClient

          @JvmOverloads
          public CordaRPCClient(@NotNull
                                              java.util.List<net.corda.core.utilities.NetworkHostAndPort> haAddressPool,
                                              @NotNull
                                              CordaRPCClientConfiguration configuration)

    - #### CordaRPCClient

          @JvmOverloads
          public CordaRPCClient(@NotNull
                                              java.util.List<net.corda.core.utilities.NetworkHostAndPort> haAddressPool)

    - #### CordaRPCClient

          @JvmOverloads
          public CordaRPCClient(@NotNull
                                              NetworkHostAndPort hostAndPort,
                                              @NotNull
                                              CordaRPCClientConfiguration configuration,
                                              @Nullable
                                              ClientRpcSslOptions sslConfiguration,
                                              @Nullable
                                              java.lang.ClassLoader classLoader,
                                              @Nullable
                                              java.util.Set<? extends net.corda.core.serialization.SerializationCustomSerializer<?,?>> customSerializers)

    - #### CordaRPCClient

          @JvmOverloads
          public CordaRPCClient(@NotNull
                                              NetworkHostAndPort hostAndPort,
                                              @NotNull
                                              CordaRPCClientConfiguration configuration,
                                              @Nullable
                                              ClientRpcSslOptions sslConfiguration,
                                              @Nullable
                                              java.util.Set<? extends net.corda.core.serialization.SerializationCustomSerializer<?,?>> customSerializers)

    - #### CordaRPCClient

          @JvmOverloads
          public CordaRPCClient(@NotNull
                                              NetworkHostAndPort hostAndPort,
                                              @NotNull
                                              CordaRPCClientConfiguration configuration,
                                              @Nullable
                                              java.util.Set<? extends net.corda.core.serialization.SerializationCustomSerializer<?,?>> customSerializers)

    - #### CordaRPCClient

          @JvmOverloads
          public CordaRPCClient(@NotNull
                                              NetworkHostAndPort hostAndPort,
                                              @Nullable
                                              java.util.Set<? extends net.corda.core.serialization.SerializationCustomSerializer<?,?>> customSerializers)

    - #### CordaRPCClient

          @JvmOverloads
          public CordaRPCClient(@NotNull
                                              java.util.List<net.corda.core.utilities.NetworkHostAndPort> haAddressPool,
                                              @NotNull
                                              CordaRPCClientConfiguration configuration,
                                              @Nullable
                                              ClientRpcSslOptions sslConfiguration,
                                              @Nullable
                                              java.lang.ClassLoader classLoader,
                                              @Nullable
                                              java.util.Set<? extends net.corda.core.serialization.SerializationCustomSerializer<?,?>> customSerializers)

    - #### CordaRPCClient

          @JvmOverloads
          public CordaRPCClient(@NotNull
                                              java.util.List<net.corda.core.utilities.NetworkHostAndPort> haAddressPool,
                                              @NotNull
                                              CordaRPCClientConfiguration configuration,
                                              @Nullable
                                              ClientRpcSslOptions sslConfiguration,
                                              @Nullable
                                              java.util.Set<? extends net.corda.core.serialization.SerializationCustomSerializer<?,?>> customSerializers)

    - #### CordaRPCClient

          @JvmOverloads
          public CordaRPCClient(@NotNull
                                              java.util.List<net.corda.core.utilities.NetworkHostAndPort> haAddressPool,
                                              @NotNull
                                              CordaRPCClientConfiguration configuration,
                                              @Nullable
                                              java.util.Set<? extends net.corda.core.serialization.SerializationCustomSerializer<?,?>> customSerializers)

    - #### CordaRPCClient

          @JvmOverloads
          public CordaRPCClient(@NotNull
                                              java.util.List<net.corda.core.utilities.NetworkHostAndPort> haAddressPool,
                                              @Nullable
                                              java.util.Set<? extends net.corda.core.serialization.SerializationCustomSerializer<?,?>> customSerializers)

  - ### Method Detail

    - #### getRegisteredCustomSerializers

          @CordaInternal
           @VisibleForTesting
           @NotNull
          public java.util.List<net.corda.core.serialization.SerializationCustomSerializer> getRegisteredCustomSerializers()

    - #### start

          @JvmOverloads
           @NotNull
          public CordaRPCConnection start(@NotNull
                                                                  java.lang.String username,
                                                                  @NotNull
                                                                  java.lang.String password,
                                                                  @Nullable
                                                                  GracefulReconnect gracefulReconnect)

      Logs in to the target server and returns an active connection. The returned connection is a java.io.Closeable and can be used with a try-with-resources statement. If you don't use that, you should use the `RPCConnection.notifyServerAndClose` or `RPCConnection.forceClose` methods to dispose of the connection object when done.

      Parameters:
        `username` - The username to authenticate with.
        `password` - The password to authenticate with.
        `gracefulReconnect` - a `class GracefulReconnect` class containing callback logic when the RPC is dis/reconnected unexpectedly
      Throws:
        `RPCException` - if the server version is too low or if the server isn't reachable within a reasonable timeout.
      See Also:
        java.io.Closeable, `RPCConnection.notifyServerAndClose`, `RPCConnection.forceClose`

    - #### start

          @JvmOverloads
           @NotNull
          public CordaRPCConnection start(@NotNull
                                                                  java.lang.String username,
                                                                  @NotNull
                                                                  java.lang.String password)

      Logs in to the target server and returns an active connection. The returned connection is a java.io.Closeable and can be used with a try-with-resources statement. If you don't use that, you should use the `RPCConnection.notifyServerAndClose` or `RPCConnection.forceClose` methods to dispose of the connection object when done.

      Parameters:
        `username` - The username to authenticate with.
        `password` - The password to authenticate with.
      Throws:
        `RPCException` - if the server version is too low or if the server isn't reachable within a reasonable timeout.
      See Also:
        java.io.Closeable, `RPCConnection.notifyServerAndClose`, `RPCConnection.forceClose`

    - #### start

          @JvmOverloads
           @NotNull
          public CordaRPCConnection start(@NotNull
                                                                  java.lang.String username,
                                                                  @NotNull
                                                                  java.lang.String password,
                                                                  @NotNull
                                                                  CordaX500Name targetLegalIdentity,
                                                                  @Nullable
                                                                  GracefulReconnect gracefulReconnect)

      Logs in to the target server and returns an active connection. The returned connection is a java.io.Closeable and can be used with a try-with-resources statement. If you don't use that, you should use the `RPCConnection.notifyServerAndClose` or `RPCConnection.forceClose` methods to dispose of the connection object when done.

      Parameters:
        `username` - The username to authenticate with.
        `password` - The password to authenticate with.
        `targetLegalIdentity` - in case of multi-identity RPC endpoint specific legal identity to which the calls must be addressed.
        `gracefulReconnect` - a `class GracefulReconnect` class containing callback logic when the RPC is dis/reconnected unexpectedly
      Throws:
        `RPCException` - if the server version is too low or if the server isn't reachable within a reasonable timeout.
      See Also:
        java.io.Closeable, `RPCConnection.notifyServerAndClose`, `RPCConnection.forceClose`

    - #### start

          @JvmOverloads
           @NotNull
          public CordaRPCConnection start(@NotNull
                                                                  java.lang.String username,
                                                                  @NotNull
                                                                  java.lang.String password,
                                                                  @NotNull
                                                                  CordaX500Name targetLegalIdentity)

      Logs in to the target server and returns an active connection. The returned connection is a java.io.Closeable and can be used with a try-with-resources statement. If you don't use that, you should use the `RPCConnection.notifyServerAndClose` or `RPCConnection.forceClose` methods to dispose of the connection object when done.

      Parameters:
        `username` - The username to authenticate with.
        `password` - The password to authenticate with.
        `targetLegalIdentity` - in case of multi-identity RPC endpoint specific legal identity to which the calls must be addressed.
      Throws:
        `RPCException` - if the server version is too low or if the server isn't reachable within a reasonable timeout.
      See Also:
        java.io.Closeable, `RPCConnection.notifyServerAndClose`, `RPCConnection.forceClose`

    - #### start

          @JvmOverloads
           @NotNull
          public CordaRPCConnection start(@NotNull
                                                                  java.lang.String username,
                                                                  @NotNull
                                                                  java.lang.String password,
                                                                  @Nullable
                                                                  Trace externalTrace,
                                                                  @Nullable
                                                                  Actor impersonatedActor,
                                                                  @Nullable
                                                                  GracefulReconnect gracefulReconnect)

      Logs in to the target server and returns an active connection. The returned connection is a java.io.Closeable and can be used with a try-with-resources statement. If you don't use that, you should use the `RPCConnection.notifyServerAndClose` or `RPCConnection.forceClose` methods to dispose of the connection object when done.

      Parameters:
        `username` - The username to authenticate with.
        `password` - The password to authenticate with.
        `externalTrace` - external `class Trace` for correlation.
        `impersonatedActor` - the actor on behalf of which all the invocations will be made.
        `gracefulReconnect` - a `class GracefulReconnect` class containing callback logic when the RPC is dis/reconnected unexpectedly
      Throws:
        `RPCException` - if the server version is too low or if the server isn't reachable within a reasonable timeout.
      See Also:
        java.io.Closeable, `RPCConnection.notifyServerAndClose`, `RPCConnection.forceClose`

    - #### start

          @JvmOverloads
           @NotNull
          public CordaRPCConnection start(@NotNull
                                                                  java.lang.String username,
                                                                  @NotNull
                                                                  java.lang.String password,
                                                                  @Nullable
                                                                  Trace externalTrace,
                                                                  @Nullable
                                                                  Actor impersonatedActor)

      Logs in to the target server and returns an active connection. The returned connection is a java.io.Closeable and can be used with a try-with-resources statement. If you don't use that, you should use the `RPCConnection.notifyServerAndClose` or `RPCConnection.forceClose` methods to dispose of the connection object when done.

      Parameters:
        `username` - The username to authenticate with.
        `password` - The password to authenticate with.
        `externalTrace` - external `class Trace` for correlation.
        `impersonatedActor` - the actor on behalf of which all the invocations will be made.
      Throws:
        `RPCException` - if the server version is too low or if the server isn't reachable within a reasonable timeout.
      See Also:
        java.io.Closeable, `RPCConnection.notifyServerAndClose`, `RPCConnection.forceClose`

    - #### start

          @JvmOverloads
           @NotNull
          public CordaRPCConnection start(@NotNull
                                                                  java.lang.String username,
                                                                  @NotNull
                                                                  java.lang.String password,
                                                                  @Nullable
                                                                  Trace externalTrace,
                                                                  @Nullable
                                                                  Actor impersonatedActor,
                                                                  @Nullable
                                                                  CordaX500Name targetLegalIdentity,
                                                                  @Nullable
                                                                  GracefulReconnect gracefulReconnect)

      Logs in to the target server and returns an active connection. The returned connection is a java.io.Closeable and can be used with a try-with-resources statement. If you don't use that, you should use the `RPCConnection.notifyServerAndClose` or `RPCConnection.forceClose` methods to dispose of the connection object when done.

      Parameters:
        `username` - The username to authenticate with.
        `password` - The password to authenticate with.
        `externalTrace` - external `class Trace` for correlation.
        `impersonatedActor` - the actor on behalf of which all the invocations will be made.
        `targetLegalIdentity` - in case of multi-identity RPC endpoint specific legal identity to which the calls must be addressed.
        `gracefulReconnect` - a `class GracefulReconnect` class containing callback logic when the RPC is dis/reconnected unexpectedly.Note that when using graceful reconnect the values for CordaRPCClientConfiguration.connectionMaxRetryInterval andCordaRPCClientConfiguration.maxReconnectAttempts will be overridden in order to mangage the reconnects.
      Throws:
        `RPCException` - if the server version is too low or if the server isn't reachable within a reasonable timeout.
      See Also:
        java.io.Closeable, `RPCConnection.notifyServerAndClose`, `RPCConnection.forceClose`

    - #### start

          @JvmOverloads
           @NotNull
          public CordaRPCConnection start(@NotNull
                                                                  java.lang.String username,
                                                                  @NotNull
                                                                  java.lang.String password,
                                                                  @Nullable
                                                                  Trace externalTrace,
                                                                  @Nullable
                                                                  Actor impersonatedActor,
                                                                  @Nullable
                                                                  CordaX500Name targetLegalIdentity)

      Logs in to the target server and returns an active connection. The returned connection is a java.io.Closeable and can be used with a try-with-resources statement. If you don't use that, you should use the `RPCConnection.notifyServerAndClose` or `RPCConnection.forceClose` methods to dispose of the connection object when done.

      Parameters:
        `username` - The username to authenticate with.
        `password` - The password to authenticate with.
        `externalTrace` - external `class Trace` for correlation.
        `impersonatedActor` - the actor on behalf of which all the invocations will be made.
        `targetLegalIdentity` - in case of multi-identity RPC endpoint specific legal identity to which the calls must be addressed.
      Throws:
        `RPCException` - if the server version is too low or if the server isn't reachable within a reasonable timeout.
      See Also:
        java.io.Closeable, `RPCConnection.notifyServerAndClose`, `RPCConnection.forceClose`

    - #### use

          public <A> A use(@NotNull
                           java.lang.String username,
                           @NotNull
                           java.lang.String password,
                           @NotNull
                           kotlin.jvm.functions.Function1<? super net.corda.client.rpc.CordaRPCConnection,? extends A> block)

      A helper for Kotlin users that simply closes the connection after the block has executed. Be careful not to over-use this, as setting up and closing connections takes time.