mirror of
https://github.com/corda/corda.git
synced 2024-12-23 06:42:33 +00:00
353 lines
16 KiB
HTML
353 lines
16 KiB
HTML
|
|
|
|
<!DOCTYPE html>
|
|
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
|
|
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
|
|
<head>
|
|
<meta charset="utf-8">
|
|
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
|
|
<title>The Corda Plugin Framework — R3 Corda latest documentation</title>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<link rel="stylesheet" href="_static/css/custom.css" type="text/css" />
|
|
|
|
|
|
|
|
|
|
|
|
<link rel="top" title="R3 Corda latest documentation" href="index.html"/>
|
|
<link rel="next" title="A Brief Introduction To The Node Services" href="node-services.html"/>
|
|
<link rel="prev" title="The Corda Configuration File" href="corda-configuration-files.html"/>
|
|
|
|
|
|
<script src="_static/js/modernizr.min.js"></script>
|
|
|
|
</head>
|
|
|
|
<body class="wy-body-for-nav" role="document">
|
|
|
|
<div class="wy-grid-for-nav">
|
|
|
|
|
|
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
|
<div class="wy-side-scroll">
|
|
<div class="wy-side-nav-search">
|
|
|
|
|
|
|
|
|
|
<a href="index.html" class="icon icon-home"> R3 Corda
|
|
|
|
|
|
|
|
</a>
|
|
|
|
|
|
|
|
|
|
<div class="version">
|
|
latest
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div role="search">
|
|
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
|
|
<input type="text" name="q" placeholder="Search docs" />
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|
<input type="hidden" name="area" value="default" />
|
|
</form>
|
|
</div>
|
|
|
|
|
|
<br>
|
|
<a href="api/index.html">API reference</a>
|
|
|
|
</div>
|
|
|
|
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
|
|
|
|
|
|
|
<p class="caption"><span class="caption-text">Getting started</span></p>
|
|
<ul>
|
|
<li class="toctree-l1"><a class="reference internal" href="inthebox.html">What’s included?</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="getting-set-up.html">Getting set up</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="running-the-demos.html">Running the demos</a></li>
|
|
</ul>
|
|
<p class="caption"><span class="caption-text">Key concepts</span></p>
|
|
<ul>
|
|
<li class="toctree-l1"><a class="reference internal" href="data-model.html">Data model</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="transaction-data-types.html">Data types</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="merkle-trees.html">Transaction Tear-offs</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="consensus.html">Consensus model</a></li>
|
|
</ul>
|
|
<p class="caption"><span class="caption-text">The Corda node</span></p>
|
|
<ul class="current">
|
|
<li class="toctree-l1"><a class="reference internal" href="clientrpc.html">Client RPC</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="messaging.html">Networking and messaging</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="persistence.html">Persistence</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="node-administration.html">Node administration</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="corda-configuration-files.html">The Corda Configuration File</a></li>
|
|
<li class="toctree-l1 current"><a class="current reference internal" href="#">The Corda Plugin Framework</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="node-services.html">A Brief Introduction To The Node Services</a></li>
|
|
</ul>
|
|
<p class="caption"><span class="caption-text">CorDapps</span></p>
|
|
<ul>
|
|
<li class="toctree-l1"><a class="reference internal" href="creating-a-cordapp.html">Creating a Cordapp</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="creating-a-cordapp.html#gradle-plugins-for-cordapps">Gradle Plugins for Cordapps</a></li>
|
|
</ul>
|
|
<p class="caption"><span class="caption-text">Tutorials</span></p>
|
|
<ul>
|
|
<li class="toctree-l1"><a class="reference internal" href="where-to-start.html">Where to start</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="tutorial-contract.html">Writing a contract</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="tutorial-contract-clauses.html">Writing a contract using clauses</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="tutorial-test-dsl.html">Writing a contract test</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="tutorial-clientrpc-api.html">Client RPC API Tutorial</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="flow-state-machines.html">Writing flows</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="flow-testing.html">Writing flow tests</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="oracles.html">Writing oracle services</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="tutorial-attachments.html">Using attachments</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="event-scheduling.html">Event scheduling</a></li>
|
|
</ul>
|
|
<p class="caption"><span class="caption-text">Other</span></p>
|
|
<ul>
|
|
<li class="toctree-l1"><a class="reference internal" href="network-simulator.html">Network Simulator</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="node-explorer.html">Node Explorer</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="initial-margin-agreement.html">Initial Margin Agreements</a></li>
|
|
</ul>
|
|
<p class="caption"><span class="caption-text">Component library</span></p>
|
|
<ul>
|
|
<li class="toctree-l1"><a class="reference internal" href="contract-catalogue.html">Contract catalogue</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="contract-irs.html">Interest Rate Swaps</a></li>
|
|
</ul>
|
|
<p class="caption"><span class="caption-text">Appendix</span></p>
|
|
<ul>
|
|
<li class="toctree-l1"><a class="reference internal" href="loadtesting.html">Load testing</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="secure-coding-guidelines.html">Secure coding guidelines</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="release-process.html">Release process</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="release-process.html#steps-to-cut-a-release">Steps to cut a release</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="release-notes.html">Release notes</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="codestyle.html">Code style guide</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="building-the-docs.html">Building the documentation</a></li>
|
|
</ul>
|
|
<p class="caption"><span class="caption-text">Glossary</span></p>
|
|
<ul>
|
|
<li class="toctree-l1"><a class="reference internal" href="glossary.html">Glossary</a></li>
|
|
</ul>
|
|
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</nav>
|
|
|
|
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
|
|
|
|
|
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
|
|
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
|
<a href="index.html">R3 Corda</a>
|
|
</nav>
|
|
|
|
|
|
|
|
<div class="wy-nav-content">
|
|
<div class="rst-content">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div role="navigation" aria-label="breadcrumbs navigation">
|
|
<ul class="wy-breadcrumbs">
|
|
<li><a href="index.html">Docs</a> »</li>
|
|
|
|
<li>The Corda Plugin Framework</li>
|
|
<li class="wy-breadcrumbs-aside">
|
|
|
|
|
|
<a href="_sources/corda-plugins.txt" rel="nofollow"> View page source</a>
|
|
|
|
|
|
</li>
|
|
</ul>
|
|
<hr/>
|
|
</div>
|
|
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
|
<div itemprop="articleBody">
|
|
|
|
<div class="section" id="the-corda-plugin-framework">
|
|
<h1>The Corda Plugin Framework<a class="headerlink" href="#the-corda-plugin-framework" title="Permalink to this headline">¶</a></h1>
|
|
<p>The intention is that Corda is a common platform, which will be extended
|
|
by numerous application extensions (CorDapps). These extensions will
|
|
package together all of the Corda contract code, state structures,
|
|
protocols/flows to create and modify state as well as RPC extensions for
|
|
node clients. Details of writing these CorDapps is given elsewhere
|
|
<a class="reference internal" href="creating-a-cordapp.html"><span class="doc">Creating a Cordapp</span></a>.</p>
|
|
<p>To enable these plugins to register dynamically with the Corda framework
|
|
the node uses the Java <code class="docutils literal"><span class="pre">ServiceLoader</span></code> to locate and load the plugin
|
|
components during the <code class="docutils literal"><span class="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
|
|
<code class="docutils literal"><span class="pre">net.corda.core.node.CordaPluginRegistry</span></code> which overrides the relevant
|
|
registration methods.</p>
|
|
<p>2. Include a resource file named
|
|
<code class="docutils literal"><span class="pre">net.corda.core.node.CordaPluginRegistry</span></code> in the <code class="docutils literal"><span class="pre">META-INF.services</span></code>
|
|
path. This must include a line containing the fully qualified name of
|
|
the <code class="docutils literal"><span class="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 <code class="docutils literal"><span class="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 <code class="docutils literal"><span class="pre">ServiceHub</span></code>
|
|
reference. This reference provides acccess to functions such as querying
|
|
for states through the <code class="docutils literal"><span class="pre">VaultService</span></code> interface, or access to the
|
|
<code class="docutils literal"><span class="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
|
|
<code class="docutils literal"><span class="pre">servicePlugins</span></code> the <code class="docutils literal"><span class="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 <code class="docutils literal"><span class="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 <code class="docutils literal"><span class="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 <code class="docutils literal"><span class="pre">java.lang.*</span></code> and <code class="docutils literal"><span class="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 <code class="docutils literal"><span class="pre">FlowLogicRefFactory</span></code>. White
|
|
listing is not strictly required for <code class="docutils literal"><span class="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 <code class="docutils literal"><span class="pre">servicePlugins</span></code> property returns a list of classes which will
|
|
be instantiated once during the <code class="docutils literal"><span class="pre">AbstractNode.start</span></code> call. These
|
|
classes must provide a single argument constructor which will receive a
|
|
<code class="docutils literal"><span class="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 <code class="docutils literal"><span class="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
|
|
<code class="docutils literal"><span class="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 <code class="docutils literal"><span class="pre">SingletonSerializeAsToken</span></code>, otherwise Quasar suspension in the
|
|
<code class="docutils literal"><span class="pre">StateMachineManager</span></code> will fail with exceptions. An example oracle can
|
|
be seen in <code class="docutils literal"><span class="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 <code class="docutils literal"><span class="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>
|
|
</div></blockquote>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
<footer>
|
|
|
|
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
|
|
|
|
<a href="node-services.html" class="btn btn-neutral float-right" title="A Brief Introduction To The Node Services" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
|
|
|
|
|
|
<a href="corda-configuration-files.html" class="btn btn-neutral" title="The Corda Configuration File" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
|
|
|
|
</div>
|
|
|
|
|
|
<hr/>
|
|
|
|
<div role="contentinfo">
|
|
<p>
|
|
© Copyright 2016, Distributed Ledger Group, LLC.
|
|
|
|
</p>
|
|
</div>
|
|
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
|
|
|
</footer>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
<script type="text/javascript">
|
|
var DOCUMENTATION_OPTIONS = {
|
|
URL_ROOT:'./',
|
|
VERSION:'latest',
|
|
COLLAPSE_INDEX:false,
|
|
FILE_SUFFIX:'.html',
|
|
HAS_SOURCE: true
|
|
};
|
|
</script>
|
|
<script type="text/javascript" src="_static/jquery.js"></script>
|
|
<script type="text/javascript" src="_static/underscore.js"></script>
|
|
<script type="text/javascript" src="_static/doctools.js"></script>
|
|
|
|
|
|
|
|
|
|
|
|
<script type="text/javascript" src="_static/js/theme.js"></script>
|
|
|
|
|
|
|
|
|
|
<script type="text/javascript">
|
|
jQuery(function () {
|
|
SphinxRtdTheme.StickyNav.enable();
|
|
});
|
|
</script>
|
|
|
|
|
|
</body>
|
|
</html> |