corda / net.corda.client.rpc / CordaRPCClient

CordaRPCClient

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 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 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 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 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:

Parameters

hostAndPort - The network address to connect to.

configuration - An optional configuration used to tweak client behaviour.

sslConfiguration - An optional ClientRpcSslOptions used to enable secure communication with the server.

haAddressPool - A list of NetworkHostAndPort representing the addresses of servers in HA mode. The client will attempt to connect to a live server by trying each address in the list. If the servers are not in HA mode, the client will round-robin from the beginning of the list and try all servers.

classLoader - a classloader, which will be used (if provided) to discover available SerializationCustomSerializers and SerializationWhitelists. If no classloader is provided, the classloader of the current class will be used by default for the aforementioned discovery process.

customSerializers - a set of SerializationCustomSerializers to be used. If this parameter is specified, then no classpath scanning will be performed for custom serializers, the provided ones will be used instead. This parameter serves as a more user-friendly option to specify your serializers and disable the classpath scanning (e.g. for performance reasons).

Constructors

<init>

CordaRPCClient(hostAndPort: NetworkHostAndPort, configuration: CordaRPCClientConfiguration = CordaRPCClientConfiguration.DEFAULT)
CordaRPCClient(hostAndPort: NetworkHostAndPort, configuration: CordaRPCClientConfiguration = CordaRPCClientConfiguration.DEFAULT, classLoader: ClassLoader)
CordaRPCClient(hostAndPort: NetworkHostAndPort, sslConfiguration: ClientRpcSslOptions? = null, classLoader: ClassLoader? = null)
CordaRPCClient(hostAndPort: NetworkHostAndPort, configuration: CordaRPCClientConfiguration, sslConfiguration: ClientRpcSslOptions?, classLoader: ClassLoader? = null)
CordaRPCClient(haAddressPool: List<NetworkHostAndPort>, configuration: CordaRPCClientConfiguration = CordaRPCClientConfiguration.DEFAULT, sslConfiguration: ClientRpcSslOptions? = null, classLoader: ClassLoader? = null)
CordaRPCClient(hostAndPort: NetworkHostAndPort, configuration: CordaRPCClientConfiguration = CordaRPCClientConfiguration.DEFAULT, sslConfiguration: ClientRpcSslOptions? = null, classLoader: ClassLoader? = null, customSerializers: Set<SerializationCustomSerializer<*, *>>?)
CordaRPCClient(haAddressPool: List<NetworkHostAndPort>, configuration: CordaRPCClientConfiguration = CordaRPCClientConfiguration.DEFAULT, sslConfiguration: ClientRpcSslOptions? = null, classLoader: ClassLoader? = null, customSerializers: Set<SerializationCustomSerializer<*, *>>?)

Functions

getRegisteredCustomSerializers

fun getRegisteredCustomSerializers(): List<SerializationCustomSerializer<*, *>>

start

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.

fun start(username: String, password: String, gracefulReconnect: GracefulReconnect? = null): CordaRPCConnection
fun start(username: String, password: String, targetLegalIdentity: CordaX500Name, gracefulReconnect: GracefulReconnect? = null): CordaRPCConnection
fun start(username: String, password: String, externalTrace: Trace?, impersonatedActor: Actor?, gracefulReconnect: GracefulReconnect? = null): CordaRPCConnection
fun start(username: String, password: String, externalTrace: Trace?, impersonatedActor: Actor?, targetLegalIdentity: CordaX500Name?, gracefulReconnect: GracefulReconnect? = null): CordaRPCConnection

use

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.

fun <A> use(username: String, password: String, block: (CordaRPCConnection) -> A): A