net.corda.node.services.messaging

## Class CordaRPCClient

- SingletonSerializeAsToken
- - ArtemisMessagingComponent
  - - net.corda.node.services.messaging.CordaRPCClient

- All Implemented Interfaces:
    SerializeAsToken

      public class CordaRPCClient
      extends ArtemisMessagingComponent

  An RPC client connects to the specified server and allows you to make calls to the server that perform various useful tasks. See the documentation for proxy or review the docsite to learn more about how this API works.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class net.corda.node.services.messaging.ArtemisMessagingComponent

      `ArtemisMessagingComponent.Companion, ArtemisMessagingComponent.ConnectionDirection, ArtemisMessagingComponent.NetworkMapAddress, ArtemisMessagingComponent.NodeAddress, ArtemisMessagingComponent.ServiceAddress`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static net.corda.node.services.messaging.CordaRPCClient.Companion` | `Companion`

    - ### Fields inherited from class net.corda.node.services.messaging.ArtemisMessagingComponent

      `CLIENTS_PREFIX, INTERNAL_PREFIX, NETWORK_MAP_QUEUE, NODE_USER, NOTIFICATIONS_ADDRESS, P2P_QUEUE, PEERS_PREFIX, PEER_USER, RPC_QUEUE_REMOVALS_QUEUE, RPC_REQUESTS_QUEUE, SERVICES_PREFIX, VERIFY_PEER_COMMON_NAME`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CordaRPCClient(com.google.common.net.HostAndPort host, SSLConfiguration config, kotlin.jvm.functions.Function1<? super org.apache.activemq.artemis.api.core.client.ServerLocator,kotlin.Unit> serviceConfigurationOverride)` An RPC client connects to the specified server and allows you to make calls to the server that perform various useful tasks. See the documentation for proxy or review the docsite to learn more about how this API works.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Shuts down the client and lets the server know it can free the used resources (in a nice way).
    `SSLConfiguration` | `getConfig()` The config object is used to pass in the passwords for the certificate KeyStore and TrustStore
    `com.google.common.net.HostAndPort` | `getHost()`
    `kotlin.jvm.functions.Function1<org.apache.activemq.artemis.api.core.client.ServerLocator,kotlin.Unit>` | `getServiceConfigurationOverride()`
    `CordaRPCOps` | `proxy(java.time.Duration timeout, int minVersion)` Returns a fresh 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 but only one RPC can be in flight at once. If you'd like to perform multiple RPCs in parallel, use this function multiple times to get multiple proxies.
    `CordaRPCOps` | `proxy(java.time.Duration timeout)` Returns a fresh 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 but only one RPC can be in flight at once. If you'd like to perform multiple RPCs in parallel, use this function multiple times to get multiple proxies.
    `CordaRPCOps` | `proxy()` Returns a fresh 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 but only one RPC can be in flight at once. If you'd like to perform multiple RPCs in parallel, use this function multiple times to get multiple proxies.
    `CordaRPCClient` | `start(java.lang.String username, java.lang.String password)` Opens the connection to the server with the given username and password, then returns itself. Registers a JVM shutdown hook to cleanly disconnect.
    `<T> T` | `use(java.lang.String username, java.lang.String password, kotlin.jvm.functions.Function1<? super net.corda.core.messaging.CordaRPCOps,? extends T> block)` A convenience function that opens a connection with the given credentials, executes the given code block with all available RPCs in scope and shuts down the RPC connection again. It's meant for quick prototyping and demos. For more control you probably want to control the lifecycle of the client and proxies independently, as well as configuring a timeout and other such features via the proxy method.

    - ### Methods inherited from class net.corda.node.services.messaging.ArtemisMessagingComponent

      `checkStorePasswords, expectedOnDefaultFileSystem, getConfig, tcpTransport, toHostAndPort`

    - ### Methods inherited from class net.corda.core.serialization.SingletonSerializeAsToken

      `toToken`

    - ### Methods inherited from interface net.corda.core.serialization.SerializeAsToken

      `toToken`

- - ### Field Detail

    - #### Companion

          public static net.corda.node.services.messaging.CordaRPCClient.Companion Companion

  - ### Constructor Detail

    - #### CordaRPCClient

          public CordaRPCClient(com.google.common.net.HostAndPort host,
                                SSLConfiguration config,
                                kotlin.jvm.functions.Function1<? super org.apache.activemq.artemis.api.core.client.ServerLocator,kotlin.Unit> serviceConfigurationOverride)

      An RPC client connects to the specified server and allows you to make calls to the server that perform various useful tasks. See the documentation for proxy or review the docsite to learn more about how this API works.

      Parameters:
        `config` - The config object is used to pass in the passwords for the certificate KeyStore and TrustStore
        `host` - The hostname and messaging port of the node.
        `config` - If specified, the SSL configuration to use. If not specified, SSL will be disabled and the node will only be authenticated on non-SSL RPC port, the RPC traffic with not be encrypted when SSL is disabled.

  - ### Method Detail

    - #### start

          public CordaRPCClient start(java.lang.String username,
                                      java.lang.String password)

      Opens the connection to the server with the given username and password, then returns itself. Registers a JVM shutdown hook to cleanly disconnect.

    - #### use

          public <T> T use(java.lang.String username,
                           java.lang.String password,
                           kotlin.jvm.functions.Function1<? super net.corda.core.messaging.CordaRPCOps,? extends T> block)

      A convenience function that opens a connection with the given credentials, executes the given code block with all available RPCs in scope and shuts down the RPC connection again. It's meant for quick prototyping and demos. For more control you probably want to control the lifecycle of the client and proxies independently, as well as configuring a timeout and other such features via the proxy method.

      After this method returns the client is closed and can't be restarted.

    - #### close

          public void close()

      Shuts down the client and lets the server know it can free the used resources (in a nice way).

    - #### proxy

          public CordaRPCOps proxy(java.time.Duration timeout,
                                   int minVersion)

      Returns a fresh 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 but only one RPC can be in flight at once. If you'd like to perform multiple RPCs in parallel, use this function multiple times to get multiple proxies.

      Creation of a proxy is a somewhat expensive operation that involves calls to the server, so if you want to do calls from many threads at once you should cache one proxy per thread and reuse them. This function itself is thread safe though so requires no extra synchronisation.

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

      By default there are no timeouts on calls. This is deliberate, RPCs without timeouts can survive restarts, maintenance downtime and moves of the server. RPCs can survive temporary losses or changes in client connectivity, like switching between wifi networks. You can specify a timeout on the level of a proxy. If a call times out it will throw RPCException.Deadline.

      The `interface CordaRPCOps` defines what client RPCs are available. If an RPC returns an Observable anywhere in the object graph returned then the server-side observable is transparently linked to a messaging queue, and that queue linked to another observable on the client side here. You are expected to use it. The server will begin buffering messages immediately that it will expect you to drain by subscribing to the returned observer. You can opt-out of this by simply casting the Observable to Closeable or AutoCloseable and then calling the close 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, the observable is closed and you can't then re-subscribe again: you'll have to re-request a fresh observable with another RPC.

      The proxy and linked observables consume some small amount of resources on the server. It's OK to just exit your process and let the server clean up, but in a long running process where you only need something for a short amount of time it is polite to cast the objects to Closeable or AutoCloseable and close it when you are done. Finalizers are in place to warn you if you lose a reference to an unclosed proxy or observable.

      Throws:
        - if the server version is too low or if the server isn't reachable within the given time.
      See Also:
        RPCException.Deadline, `interface CordaRPCOps`, Closeable, AutoCloseable, Closeable, AutoCloseable

    - #### proxy

          public CordaRPCOps proxy(java.time.Duration timeout)

      Returns a fresh 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 but only one RPC can be in flight at once. If you'd like to perform multiple RPCs in parallel, use this function multiple times to get multiple proxies.

      Creation of a proxy is a somewhat expensive operation that involves calls to the server, so if you want to do calls from many threads at once you should cache one proxy per thread and reuse them. This function itself is thread safe though so requires no extra synchronisation.

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

      By default there are no timeouts on calls. This is deliberate, RPCs without timeouts can survive restarts, maintenance downtime and moves of the server. RPCs can survive temporary losses or changes in client connectivity, like switching between wifi networks. You can specify a timeout on the level of a proxy. If a call times out it will throw RPCException.Deadline.

      The `interface CordaRPCOps` defines what client RPCs are available. If an RPC returns an Observable anywhere in the object graph returned then the server-side observable is transparently linked to a messaging queue, and that queue linked to another observable on the client side here. You are expected to use it. The server will begin buffering messages immediately that it will expect you to drain by subscribing to the returned observer. You can opt-out of this by simply casting the Observable to Closeable or AutoCloseable and then calling the close 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, the observable is closed and you can't then re-subscribe again: you'll have to re-request a fresh observable with another RPC.

      The proxy and linked observables consume some small amount of resources on the server. It's OK to just exit your process and let the server clean up, but in a long running process where you only need something for a short amount of time it is polite to cast the objects to Closeable or AutoCloseable and close it when you are done. Finalizers are in place to warn you if you lose a reference to an unclosed proxy or observable.

      Throws:
        - if the server version is too low or if the server isn't reachable within the given time.
      See Also:
        RPCException.Deadline, `interface CordaRPCOps`, Closeable, AutoCloseable, Closeable, AutoCloseable

    - #### proxy

          public CordaRPCOps proxy()

      Returns a fresh 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 but only one RPC can be in flight at once. If you'd like to perform multiple RPCs in parallel, use this function multiple times to get multiple proxies.

      Creation of a proxy is a somewhat expensive operation that involves calls to the server, so if you want to do calls from many threads at once you should cache one proxy per thread and reuse them. This function itself is thread safe though so requires no extra synchronisation.

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

      By default there are no timeouts on calls. This is deliberate, RPCs without timeouts can survive restarts, maintenance downtime and moves of the server. RPCs can survive temporary losses or changes in client connectivity, like switching between wifi networks. You can specify a timeout on the level of a proxy. If a call times out it will throw RPCException.Deadline.

      The `interface CordaRPCOps` defines what client RPCs are available. If an RPC returns an Observable anywhere in the object graph returned then the server-side observable is transparently linked to a messaging queue, and that queue linked to another observable on the client side here. You are expected to use it. The server will begin buffering messages immediately that it will expect you to drain by subscribing to the returned observer. You can opt-out of this by simply casting the Observable to Closeable or AutoCloseable and then calling the close 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, the observable is closed and you can't then re-subscribe again: you'll have to re-request a fresh observable with another RPC.

      The proxy and linked observables consume some small amount of resources on the server. It's OK to just exit your process and let the server clean up, but in a long running process where you only need something for a short amount of time it is polite to cast the objects to Closeable or AutoCloseable and close it when you are done. Finalizers are in place to warn you if you lose a reference to an unclosed proxy or observable.

      Throws:
        - if the server version is too low or if the server isn't reachable within the given time.
      See Also:
        RPCException.Deadline, `interface CordaRPCOps`, Closeable, AutoCloseable, Closeable, AutoCloseable

    - #### getHost

          public com.google.common.net.HostAndPort getHost()

    - #### getConfig

          public SSLConfiguration getConfig()

      The config object is used to pass in the passwords for the certificate KeyStore and TrustStore

    - #### getServiceConfigurationOverride

          public kotlin.jvm.functions.Function1<org.apache.activemq.artemis.api.core.client.ServerLocator,kotlin.Unit> getServiceConfigurationOverride()