<p>To enable these plugins to register dynamically with the Corda framework
the node uses the Java <codeclass="docutils literal"><spanclass="pre">ServiceLoader</span></code> to locate and load the plugin
components during the <codeclass="docutils literal"><spanclass="pre">AbstractNode.start</span></code> call. Therefore,
to be recognised as a plugin the component must:</p>
<p>1. Include a default constructable class extending from
<codeclass="docutils literal"><spanclass="pre">net.corda.core.node.CordaPluginRegistry</span></code> which overrides the relevant
registration methods.</p>
<p>2. Include a resource file named
<codeclass="docutils literal"><spanclass="pre">net.corda.core.node.CordaPluginRegistry</span></code> in the <codeclass="docutils literal"><spanclass="pre">META-INF.services</span></code>
path. This must include a line containing the fully qualified name of
the <codeclass="docutils literal"><spanclass="pre">CordaPluginRegistry</span></code> implementation class. Multiple plugin
registries are allowed in this file if desired.</p>
<p>3. The plugin component must be on the classpath. In the normal use this
means that it should be present within the plugins subfolder of the
node’s workspace.</p>
<p>4. As a plugin the registered components are then allowed access to some
of the node internal subsystems.</p>
<p>5. The overridden properties on the registry class information about the different
extensions to be created, or registered at startup. In particular:</p>
<blockquote>
<div><p>a. The <codeclass="docutils literal"><spanclass="pre">webApis</span></code> property is a list of JAX-RS annotated REST access
classes. These classes will be constructed by the embedded web server
and must have a single argument constructor taking a <codeclass="docutils literal"><spanclass="pre">ServiceHub</span></code>
reference. This reference provides acccess to functions such as querying
for states through the <codeclass="docutils literal"><spanclass="pre">VaultService</span></code> interface, or access to the
<codeclass="docutils literal"><spanclass="pre">NetworkMapCache</span></code> to identify services on remote nodes. The framework will
provide a database transaction in scope during the lifetime of the web
call, so full access to database data is valid. Unlike
<codeclass="docutils literal"><spanclass="pre">servicePlugins</span></code> the <codeclass="docutils literal"><spanclass="pre">webApis</span></code> cannnot register new protocols, or
initiate threads. (N.B. The intent is to move the Web support into a
separate helper process using the RPC mechanism to control access.)</p>
<p>b. The <codeclass="docutils literal"><spanclass="pre">staticServeDirs</span></code> property maps static web content to virtual
paths and allows simple web demos to be distributed within the CorDapp
jars. (N.B. The intent is to move the Web support into a separate helper
process using the RPC mechanism to control access.)</p>
<p>c. The <codeclass="docutils literal"><spanclass="pre">requiredFlows</span></code> property is used to declare new protocols in
the plugin jar. Specifically the property must return a map with a key
naming each exposed top level flow class and a value which is a set
naming every parameter class that will be passed to the flow’s
constructor. Standard <codeclass="docutils literal"><spanclass="pre">java.lang.*</span></code> and <codeclass="docutils literal"><spanclass="pre">kotlin.*</span></code> types do not need
to be included, but all other parameter types, or concrete interface
implementations need declaring. Declaring a specific flow in this map
white lists it for activation by the <codeclass="docutils literal"><spanclass="pre">FlowLogicRefFactory</span></code>. White
listing is not strictly required for <codeclass="docutils literal"><spanclass="pre">subFlows</span></code> used internally, but
is required for any top level flow, or a flow which is invoked through
the scheduler.</p>
<p>d. The <codeclass="docutils literal"><spanclass="pre">servicePlugins</span></code> property returns a list of classes which will
be instantiated once during the <codeclass="docutils literal"><spanclass="pre">AbstractNode.start</span></code> call. These
classes must provide a single argument constructor which will receive a
<codeclass="docutils literal"><spanclass="pre">PluginServiceHub</span></code> reference. These singleton instances are regarded
as trusted components and can be used for a number of purposes.</p>
<blockquote>
<div><p>i. Firstly, they can call <codeclass="docutils literal"><spanclass="pre">PluginServiceHub.registerFlowInitiator</span></code> and
register flows that will be initiated locally in response to remote flow
requests.</p>
<p>ii. Second, the service can hold a long lived reference to the
PluginServiceHub and to other private data, so the service can be used
to provide Oracle functionality. This Oracle functionality would
typically be exposed to other nodes by flows which are given a reference
to the service plugin when initiated (as defined by the
<codeclass="docutils literal"><spanclass="pre">registerFlowInitiator</span></code> call). The flow can then call into functions
on the plugin service singleton. Note, care should be taken to not allow
flows to hold references to plugin services, or fields which are not
also <codeclass="docutils literal"><spanclass="pre">SingletonSerializeAsToken</span></code>, otherwise Quasar suspension in the
<codeclass="docutils literal"><spanclass="pre">StateMachineManager</span></code> will fail with exceptions. An example oracle can
be seen in <codeclass="docutils literal"><spanclass="pre">NodeInterestRates.kt</span></code> in the irs-demo sample.</p>
<p>iii. The final
use case for service plugins is that they can spawn threads, or register
to monitor vault updates. This allows them to provide long lived active
functions inside the node, for instance to initiate workflows when
certain conditions are met.</p>
</div></blockquote>
<p>e. The <codeclass="docutils literal"><spanclass="pre">registerRPCKryoTypes</span></code> function allows custom Kryo serialisers
to be registered and whitelisted for the RPC client interface. For
instance new state types passed to flows started via RPC will need
to be explicitly registered. This will be called at various points on
various threads and needs to be stable and thread safe.</p>
<ahref="node-services.html"class="btn btn-neutral float-right"title="Brief introduction to the node services"accesskey="n">Next <spanclass="fa fa-arrow-circle-right"></span></a>
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>.
