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.
ArtemisMessagingComponent.Companion, ArtemisMessagingComponent.ConnectionDirection, ArtemisMessagingComponent.NetworkMapAddress, ArtemisMessagingComponent.NodeAddress, ArtemisMessagingComponent.ServiceAddress
Modifier and Type | Field and Description |
---|---|
static net.corda.node.services.messaging.CordaRPCClient.Companion |
Companion |
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 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.
|
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.
|
checkStorePasswords, expectedOnDefaultFileSystem, getConfig, tcpTransport, toHostAndPort
toToken
toToken
public static net.corda.node.services.messaging.CordaRPCClient.Companion Companion
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.
config
- The config object is used to pass in the passwords for the certificate KeyStore and TrustStorehost
- 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 not be authenticated, nor will RPC traffic be encrypted.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.
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.
public void close()
Shuts down the client and lets the server know it can free the used resources (in a nice way).
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.
interface CordaRPCOps
,
Closeable,
AutoCloseable,
Closeable,
AutoCloseablepublic 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.
interface CordaRPCOps
,
Closeable,
AutoCloseable,
Closeable,
AutoCloseablepublic 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.
interface CordaRPCOps
,
Closeable,
AutoCloseable,
Closeable,
AutoCloseablepublic com.google.common.net.HostAndPort getHost()
public SSLConfiguration getConfig()
The config object is used to pass in the passwords for the certificate KeyStore and TrustStore
public kotlin.jvm.functions.Function1<org.apache.activemq.artemis.api.core.client.ServerLocator,kotlin.Unit> getServiceConfigurationOverride()