<h1>Client RPC<aclass="headerlink"href="#client-rpc"title="Permalink to this headline">¶</a></h1>
<p>There are multiple ways to interact with a node from a <em>client program</em>, but if your client is written in a JVM
compatible language the easiest way to do so is using the client library. The library connects to your running
node using a message queue protocol and then provides a simple RPC interface to interact with it. You make calls
on a Java object as normal, and the marshalling back and forth is handled for you.</p>
<p>The starting point for the client library is the <aclass="reference external"href="api/net.corda.client/-corda-r-p-c-client/index.html">CordaRPCClient</a> class. This provides a <codeclass="docutils literal"><spanclass="pre">proxy</span></code> method that
returns an implementation of the <aclass="reference external"href="api/net.corda.node.services.messaging/-corda-r-p-c-ops/index.html">CordaRPCOps</a> interface. A timeout parameter can be specified, and observables that
are returned by RPCs can be subscribed to in order to receive an ongoing stream of updates from the node. More
detail on how to use this is provided in the docs for the proxy method.</p>
<divclass="admonition warning">
<pclass="first admonition-title">Warning</p>
<pclass="last">The returned object is somewhat expensive to create and consumes a small amount of server side
resources. When you’re done with it, cast it to <codeclass="docutils literal"><spanclass="pre">Closeable</span></code> or <codeclass="docutils literal"><spanclass="pre">AutoCloseable</span></code> and close it. Don’t create
one for every call you make - create a proxy and reuse it.</p>
<p>For a brief tutorial on how one can use the RPC API see <aclass="reference internal"href="tutorial-clientrpc-api.html"><spanclass="doc">Client RPC API Tutorial</span></a>.</p>
<h2>Observables<aclass="headerlink"href="#observables"title="Permalink to this headline">¶</a></h2>
<p>The RPC system handles observables in a special way. When a method returns an observable, whether directly or
as a sub-object of the response object graph, an observable is created on the client to match the one on the
server. Objects emitted by the server-side observable are pushed onto a queue which is then drained by the client.
The returned observable may even emit object graphs with even more observables in them, and it all works as you
would expect.</p>
<p>This feature comes with a cost: the server must queue up objects emitted by the server-side observable until you
download them. Therefore RPCs that use this feature are marked with the <codeclass="docutils literal"><spanclass="pre">@RPCReturnsObservables</span></code> annotation, and
you are expected to subscribe to all the observables returned. If you don’t want an observable then subscribe
then unsubscribe immediately to clear the buffers and indicate that you aren’t interested. If your app quits then
server side resources will be freed automatically.</p>
<p>When all the observables returned by an RPC are unsubscribed on the client side, that unsubscription propagates
through to the server where the corresponding server-side observables are also unsubscribed.</p>
<divclass="admonition warning">
<pclass="first admonition-title">Warning</p>
<pclass="last">If you leak an observable or proxy on the client side and it gets garbage collected, you will get
a warning printed to the logs and the proxy will be closed for you. But don’t rely on this, as garbage
collection is non-deterministic.</p>
</div>
</div>
<divclass="section"id="versioning">
<h2>Versioning<aclass="headerlink"href="#versioning"title="Permalink to this headline">¶</a></h2>
<p>The client RPC protocol is versioned with a simple incrementing integer. When a proxy is created the server is
queried for its protocol version, and you can specify your minimum requirement. Methods added in later versions
are tagged with the <codeclass="docutils literal"><spanclass="pre">@RPCSinceVersion</span></code> annotation. If you try to use a method that the server isn’t advertising
support of, an <codeclass="docutils literal"><spanclass="pre">UnsupportedOperationException</span></code> is thrown. If you want to know the version of the server, just
use the <codeclass="docutils literal"><spanclass="pre">protocolVersion</span></code> property (i.e. <codeclass="docutils literal"><spanclass="pre">getProtocolVersion</span></code> in Java).</p>
</div>
<divclass="section"id="thread-safety">
<h2>Thread safety<aclass="headerlink"href="#thread-safety"title="Permalink to this headline">¶</a></h2>
<p>A proxy is thread safe, blocking, and will only allow a single RPC to be in flight at once. Any observables that
are returned and you subscribe to will have objects emitted on a background thread. Observables returned as part
of one RPC and observables returned from another may have their callbacks invoked in parallel, but observables
returned as part of the same specific RPC invocation are processed serially and will not be invoked in parallel.</p>
<p>If you want to make multiple calls to the server in parallel you can do that by creating multiple proxies, but
be aware that the server itself may <em>not</em> process your work in parallel even if you make your requests that way.</p>
</div>
<divclass="section"id="error-handling">
<h2>Error handling<aclass="headerlink"href="#error-handling"title="Permalink to this headline">¶</a></h2>
<p>If something goes wrong with the RPC infrastructure itself, an <codeclass="docutils literal"><spanclass="pre">RPCException</span></code> is thrown. If you call a method that
requires a higher version of the protocol than the server supports, <codeclass="docutils literal"><spanclass="pre">UnsupportedOperationException</span></code> is thrown.
Otherwise, if the server implementation throws an exception, that exception is serialised and rethrown on the client
side as if it was thrown from inside the called RPC method. These exceptions can be caught as normal.</p>
</div>
<divclass="section"id="wire-protocol">
<h2>Wire protocol<aclass="headerlink"href="#wire-protocol"title="Permalink to this headline">¶</a></h2>
<p>The client RPC wire protocol is not currently documented. To use it you must use the client library provided.
<h2>Registering Classes With RPC Kryo<aclass="headerlink"href="#registering-classes-with-rpc-kryo"title="Permalink to this headline">¶</a></h2>
<p>In the present implementation of the node we use Kryo to generate the <em>on the wire</em> representation of contracts states
or any other classes that form part of the RPC arguments or response. To avoid the RPC interface being wide open to all
classes on the classpath, Cordapps will currently have to register any classes or custom serialisers they require with Kryo
if they are not one of those registered by default in <codeclass="docutils literal"><spanclass="pre">RPCKryo</span></code> via the plugin architecture. See <aclass="reference internal"href="creating-a-cordapp.html"><spanclass="doc">Creating a Cordapp</span></a>.
This will require some familiarity with Kryo. An example is shown in <aclass="reference internal"href="tutorial-clientrpc-api.html"><spanclass="doc">Client RPC API Tutorial</span></a>.</p>
<divclass="admonition warning">
<pclass="first admonition-title">Warning</p>
<pclass="last">We will be replacing the use of Kryo in RPC with a stable message format and this will mean that this plugin
customisation point will either go away completely or change.</p>
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> using a <ahref="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.
