2017-01-03 13:07:48 +00:00
<!-- If you edit this, then please make the same changes to layout_for_doc_website.html, as that is used for the web
doc site generation which we put analytics tracking on to identify any potential problem pages -->
2016-11-25 12:10:21 +00:00
<!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" >
2016-11-29 11:38:52 +00:00
< title > The Corda plugin framework — R3 Corda latest documentation< / title >
2016-11-25 12:10:21 +00:00
< link rel = "stylesheet" href = "_static/css/custom.css" type = "text/css" / >
< link rel = "top" title = "R3 Corda latest documentation" href = "index.html" / >
2016-11-29 11:38:52 +00:00
< link rel = "next" title = "Brief introduction to the node services" href = "node-services.html" / >
< link rel = "prev" title = "Node configuration" href = "corda-configuration-file.html" / >
2016-11-25 12:10:21 +00:00
< 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 >
2017-01-03 13:07:48 +00:00
< br >
< a href = "https://discourse.corda.net" > Discourse Forums< / a >
< br >
< a href = "http://slack.corda.net" > Slack< / a >
< br >
2016-11-25 12:10:21 +00:00
< / 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 >
2017-01-06 17:38:23 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "getting-set-up-fault-finding.html" > Troubleshooting< / a > < / li >
2016-11-25 12:10:21 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "running-the-demos.html" > Running the demos< / a > < / li >
2016-11-29 18:44:59 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "CLI-vs-IDE.html" > CLI vs IDE< / a > < / li >
2016-11-25 12:10:21 +00:00
< / 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 >
2016-11-29 11:38:52 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "merkle-trees.html" > Transaction tear-offs< / a > < / li >
2016-11-25 12:10:21 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "consensus.html" > Consensus model< / a > < / li >
2017-01-06 17:38:23 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "clauses.html" > Clauses< / a > < / li >
2016-11-29 18:44:59 +00:00
< / ul >
< p class = "caption" > < span class = "caption-text" > CorDapps< / span > < / p >
< ul >
2017-01-06 17:38:23 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "creating-a-cordapp.html" > CorDapp basics< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "tutorial-cordapp.html" > The CorDapp template< / a > < / li >
2016-11-25 12:10:21 +00:00
< / 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 >
2016-11-29 11:38:52 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "corda-configuration-file.html" > Node configuration< / 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" > Brief introduction to the node services< / 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 = "permissioning.html" > Network permissioning< / a > < / li >
2016-11-25 12:10:21 +00:00
< / ul >
< p class = "caption" > < span class = "caption-text" > Tutorials< / span > < / p >
< ul >
< 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 >
2017-01-06 17:38:23 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "tutorial-integration-testing.html" > Integration testing< / a > < / li >
2016-11-29 11:38:52 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "tutorial-clientrpc-api.html" > Client RPC API tutorial< / a > < / li >
2017-01-06 17:38:23 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "tutorial-building-transactions.html" > Building transactions< / a > < / li >
2016-11-25 12:10:21 +00:00
< 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 >
2016-11-29 11:38:52 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "running-a-notary.html" > Running a notary service< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "using-a-notary.html" > Using a notary service< / a > < / li >
2016-11-25 12:10:21 +00:00
< 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 >
< / 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 >
2016-11-29 11:38:52 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "contract-irs.html" > Interest rate swaps< / a > < / li >
2016-11-25 12:10:21 +00:00
< / 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 >
2017-01-06 17:38:23 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "setting-up-a-corda-network.html" > What is a corda network?< / a > < / li >
2016-11-25 12:10:21 +00:00
< 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-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 >
2017-01-03 13:07:48 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "publishing-corda.html" > Publishing Corda< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "azure-vm.html" > Working with the Corda Demo on Azure Marketplace< / a > < / li >
2016-11-25 12:10:21 +00:00
< / 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 >
2016-11-29 11:38:52 +00:00
< li > The Corda plugin framework< / li >
2016-11-25 12:10:21 +00:00
< 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" >
2016-11-29 11:38:52 +00:00
< h1 > The Corda plugin framework< a class = "headerlink" href = "#the-corda-plugin-framework" title = "Permalink to this headline" > ¶< / a > < / h1 >
2016-11-25 12:10:21 +00:00
< 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
2017-01-06 17:38:23 +00:00
< a class = "reference internal" href = "creating-a-cordapp.html" > < span class = "doc" > CorDapp basics< / span > < / a > .< / p >
2016-11-25 12:10:21 +00:00
< 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 >
2017-01-06 17:38:23 +00:00
reference. This reference provides access to functions such as querying
2016-11-25 12:10:21 +00:00
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
2017-01-06 17:38:23 +00:00
< code class = "docutils literal" > < span class = "pre" > servicePlugins< / span > < / code > the < code class = "docutils literal" > < span class = "pre" > webApis< / span > < / code > cannot register new protocols, or
2016-11-25 12:10:21 +00:00
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
2016-11-29 18:44:59 +00:00
< code class = "docutils literal" > < span class = "pre" > PluginServiceHub< / span > < / code > reference. They must also extend the abstract class
< code class = "docutils literal" > < span class = "pre" > SingletonSerializeAsToken< / span > < / code > which ensures that if any reference to your
service is captured in a flow checkpoint (i.e. serialized by Kryo as
part of Quasar checkpoints, either on the stack or by reference within
your flows) it is stored as a simple token representing your service.
When checkpoints are restored, after a node restart for example,
the latest instance of the service will be substituted back in place of
the token stored in the checkpoint.< / p >
2016-11-25 12:10:21 +00:00
< 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
2016-11-29 18:44:59 +00:00
flows to hold references to fields which are not
2016-11-25 12:10:21 +00:00
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" >
2016-11-29 11:38:52 +00:00
< a href = "node-services.html" class = "btn btn-neutral float-right" title = "Brief introduction to the node services" accesskey = "n" > Next < span class = "fa fa-arrow-circle-right" > < / span > < / a >
2016-11-25 12:10:21 +00:00
2016-11-29 11:38:52 +00:00
< a href = "corda-configuration-file.html" class = "btn btn-neutral" title = "Node configuration" accesskey = "p" > < span class = "fa fa-arrow-circle-left" > < / span > Previous< / a >
2016-11-25 12:10:21 +00:00
< / div >
< hr / >
< div role = "contentinfo" >
< p >
2016-11-29 18:44:59 +00:00
© Copyright 2016, R3 Limited.
2016-11-25 12:10:21 +00:00
< / 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 >
