net.corda.client / CordaRPCClient / proxy

proxy

fun proxy(timeout: Duration? = null, minVersion: Int = 0): CordaRPCOps

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 youd 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. RPCs can survive temporary losses or changes in 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 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 dont 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 cant then re-subscribe again: youll have to re-request a fresh observable with another RPC.

The proxy and linked observables consume some small amount of resources on the server. Its 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.



Exceptions

RPCException - if the server version is too low or if the server isnt reachable within the given time.