ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2024-12-22 22:32:26 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity
9a2963bca9
corda/docs/build/html/node-services.html
Clinton Alexander 9a2963bca9 Docs regen.
2017-02-22 10:59:02 +00:00

658 lines
44 KiB
HTML
Raw Blame History

<!-- 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 -->
<!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>Brief introduction to the node services &mdash; 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="Node Explorer" href="node-explorer.html"/>
<link rel="prev" title="The Corda plugin framework" href="corda-plugins.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>
API reference: <a href="api/kotlin/corda/index.html">Kotlin</a>/ <a href="api/javadoc/index.html">JavaDoc</a>
<br>
<a href="https://discourse.corda.net">Discourse Forums</a>
<br>
<a href="http://slack.corda.net">Slack</a>
<br>
</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&#8217;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="getting-set-up-fault-finding.html">Troubleshooting</a></li>
<li class="toctree-l1"><a class="reference internal" href="running-the-demos.html">Running the demos</a></li>
<li class="toctree-l1"><a class="reference internal" href="CLI-vs-IDE.html">CLI vs IDE</a></li>
</ul>
<p class="caption"><span class="caption-text">Key concepts</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="key-concepts.html">Overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-ecosystem.html">Corda ecosystem</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-data-model.html">Data model</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-core-types.html">Core types</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-financial-model.html">Financial model</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-flow-framework.html">Flow framework</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-consensus-notaries.html">Consensus and notaries</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-vault.html">Vault</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-security-model.html">Security model</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">CorDapp basics</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-cordapp.html">The example CorDapp</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-file.html">Node configuration</a></li>
<li class="toctree-l1"><a class="reference internal" href="corda-plugins.html">The Corda plugin framework</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Brief introduction to the node services</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#services-within-the-node">Services within the node</a></li>
<li class="toctree-l2"><a class="reference internal" href="#key-management-and-identity-services">Key management and identity services</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#inmemoryidentityservice">InMemoryIdentityService</a></li>
<li class="toctree-l3"><a class="reference internal" href="#persistentkeymanagementservice-and-e2etestkeymanagementservice">PersistentKeyManagementService and E2ETestKeyManagementService</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#messaging-and-network-management-services">Messaging and network management services</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#artemismessagingserver">ArtemisMessagingServer</a></li>
<li class="toctree-l3"><a class="reference internal" href="#nodemessagingclient">NodeMessagingClient</a></li>
<li class="toctree-l3"><a class="reference internal" href="#inmemorynetworkmapcache">InMemoryNetworkMapCache</a></li>
<li class="toctree-l3"><a class="reference internal" href="#persistentnetworkmapservice-and-networkmapservice">PersistentNetworkMapService and NetworkMapService</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#storage-and-persistence-related-services">Storage and persistence related services</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#storageserviceimpl">StorageServiceImpl</a></li>
<li class="toctree-l3"><a class="reference internal" href="#dbcheckpointstorage">DBCheckpointStorage</a></li>
<li class="toctree-l3"><a class="reference internal" href="#dbtransactionmappingstorage-and-inmemorystatemachinerecordedtransactionmappingstorage">DBTransactionMappingStorage and InMemoryStateMachineRecordedTransactionMappingStorage</a></li>
<li class="toctree-l3"><a class="reference internal" href="#dbtransactionstorage">DBTransactionStorage</a></li>
<li class="toctree-l3"><a class="reference internal" href="#nodeattachmentservice">NodeAttachmentService</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#flow-framework-and-event-scheduling-services">Flow framework and event scheduling services</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#statemachinemanager">StateMachineManager</a></li>
<li class="toctree-l3"><a class="reference internal" href="#nodeschedulerservice">NodeSchedulerService</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#notary-flow-implementation-services">Notary flow implementation services</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#persistentuniquenessprovider-inmemoryuniquenessprovider-and-raftuniquenessprovider">PersistentUniquenessProvider, InMemoryUniquenessProvider and RaftUniquenessProvider</a></li>
<li class="toctree-l3"><a class="reference internal" href="#notaryservice-simplenotaryservice-validatingnotaryservice-raftvalidatingnotaryservice">NotaryService (SimpleNotaryService, ValidatingNotaryService, RaftValidatingNotaryService)</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#vault-related-services">Vault related services</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#nodevaultservice">NodeVaultService</a></li>
<li class="toctree-l3"><a class="reference internal" href="#nodeschemaservice-and-hibernateobserver">NodeSchemaService and HibernateObserver</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#node-web-server">Node Web Server</a></li>
</ul>
</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>
</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>
<li class="toctree-l1"><a class="reference internal" href="contract-upgrade.html">Upgrading Contracts</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-integration-testing.html">Integration testing</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="tutorial-building-transactions.html">Building transactions</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="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>
<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="clauses.html">Clauses</a></li>
<li class="toctree-l1"><a class="reference internal" href="merkle-trees.html">Transaction tear-offs</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="setting-up-a-corda-network.html">What is a corda network?</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-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>
<li class="toctree-l1"><a class="reference internal" href="further-notes-on-kotlin.html">Further notes on Kotlin</a></li>
<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>
</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> &raquo;</li>
<li>Brief introduction to the node services</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/node-services.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="brief-introduction-to-the-node-services">
<h1>Brief introduction to the node services<a class="headerlink" href="#brief-introduction-to-the-node-services" title="Permalink to this headline"></a></h1>
<p>This document is intended as a very brief introduction to the current
service components inside the node. Whilst not at all exhaustive it is
hoped that this will give some context when writing applications and
code that use these services, or which are operated upon by the internal
components of Corda.</p>
<div class="section" id="services-within-the-node">
<h2>Services within the node<a class="headerlink" href="#services-within-the-node" title="Permalink to this headline"></a></h2>
<p>The node services represent the various sub functions of the Corda node.
Some are directly accessible to contracts and flows through the
<code class="docutils literal"><span class="pre">ServiceHub</span></code>, whilst others are the framework internals used to host
the node functions. Any public service interfaces are defined in the
<code class="docutils literal"><span class="pre">:core</span></code> gradle project in the
<code class="docutils literal"><span class="pre">src/main/kotlin/net/corda/core/node/services</span></code> folder. The
<code class="docutils literal"><span class="pre">ServiceHub</span></code> interface exposes functionality suitable for flows.
The implementation code for all standard services lives in the gradle
<code class="docutils literal"><span class="pre">:node</span></code> project under the <code class="docutils literal"><span class="pre">src/main/kotlin/net/corda/node/services</span></code>
folder. The <code class="docutils literal"><span class="pre">src/main/kotlin/net/corda/node/services/api</span></code> folder
contains declarations for internal only services and for interoperation
between services.</p>
<p>All the services are constructed in the <code class="docutils literal"><span class="pre">AbstractNode</span></code> <code class="docutils literal"><span class="pre">start</span></code>
method (and the extension in <code class="docutils literal"><span class="pre">Node</span></code>). They may also register a
shutdown handler during initialisation, which will be called in reverse
order to the start registration sequence when the <code class="docutils literal"><span class="pre">Node.stop</span></code>
is called.</p>
<p>As well as the standard services trusted CorDapp plugins may register
custom services. These plugin services are passed a reference to the
<code class="docutils literal"><span class="pre">PluginServiceHub</span></code> which allows some more powerful functions e.g.
starting flows.</p>
<p>For unit testing a number of non-persistent, memory only services are
defined in the <code class="docutils literal"><span class="pre">:node</span></code> and <code class="docutils literal"><span class="pre">:test-utils</span></code> projects. The
<code class="docutils literal"><span class="pre">:test-utils</span></code> project also provides an in-memory networking simulation
to allow unit testing of flows and service functions.</p>
<p>The roles of the individual services are described below.</p>
</div>
<div class="section" id="key-management-and-identity-services">
<h2>Key management and identity services<a class="headerlink" href="#key-management-and-identity-services" title="Permalink to this headline"></a></h2>
<div class="section" id="inmemoryidentityservice">
<h3>InMemoryIdentityService<a class="headerlink" href="#inmemoryidentityservice" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal"><span class="pre">InMemoryIdentityService</span></code> implements the <code class="docutils literal"><span class="pre">IdentityService</span></code>
interface and provides a store of remote mappings between <code class="docutils literal"><span class="pre">CompositeKey</span></code>
and remote <code class="docutils literal"><span class="pre">Parties</span></code>. It is automatically populated from the
<code class="docutils literal"><span class="pre">NetworkMapCache</span></code> updates and is used when translating <code class="docutils literal"><span class="pre">CompositeKey</span></code>
exposed in transactions into fully populated <code class="docutils literal"><span class="pre">Party</span></code> identities. This
service is also used in the default JSON mapping of parties in the web
server, thus allowing the party names to be used to refer to other nodes&#8217;
legal identities. In the future the Identity service will be made
persistent and extended to allow anonymised session keys to be used in
flows where the well-known <code class="docutils literal"><span class="pre">CompositeKey</span></code> of nodes need to be hidden
to non-involved parties.</p>
</div>
<div class="section" id="persistentkeymanagementservice-and-e2etestkeymanagementservice">
<h3>PersistentKeyManagementService and E2ETestKeyManagementService<a class="headerlink" href="#persistentkeymanagementservice-and-e2etestkeymanagementservice" title="Permalink to this headline"></a></h3>
<p>Typical usage of these services is to locate an appropriate
<code class="docutils literal"><span class="pre">PrivateKey</span></code> to complete and sign a verified transaction as part of a
flow. The normal node legal identifier keys are typically accessed via
helper extension methods on the <code class="docutils literal"><span class="pre">ServiceHub</span></code>, but these ultimately
fetch the keys from the <code class="docutils literal"><span class="pre">KeyManagementService</span></code>. The
<code class="docutils literal"><span class="pre">KeyManagementService</span></code> interface also allows other keys to be
generated if anonymous keys are needed in a flow. Note that this
interface works at the level of individual <code class="docutils literal"><span class="pre">PublicKey</span></code>/<code class="docutils literal"><span class="pre">PrivateKey</span></code>
pairs, but the signing authority will be represented by a
<code class="docutils literal"><span class="pre">CompositeKey</span></code> on the <code class="docutils literal"><span class="pre">NodeInfo</span></code> to allow key clustering and
threshold schemes.</p>
<p>The <code class="docutils literal"><span class="pre">PersistentKeyManagementService</span></code> is a persistent implementation of
the <code class="docutils literal"><span class="pre">KeyManagementService</span></code> interface that records the key pairs to a
key-value storage table in the database. <code class="docutils literal"><span class="pre">E2ETestKeyManagementService</span></code>
is a simple implementation of the <code class="docutils literal"><span class="pre">KeyManagementService</span></code> that is used
to track our <code class="docutils literal"><span class="pre">KeyPairs</span></code> for use in unit testing when no database is
available.</p>
</div>
</div>
<div class="section" id="messaging-and-network-management-services">
<h2>Messaging and network management services<a class="headerlink" href="#messaging-and-network-management-services" title="Permalink to this headline"></a></h2>
<div class="section" id="artemismessagingserver">
<h3>ArtemisMessagingServer<a class="headerlink" href="#artemismessagingserver" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal"><span class="pre">ArtemisMessagingServer</span></code> service is run internally by the Corda
node to host the <code class="docutils literal"><span class="pre">ArtemisMQ</span></code> messaging broker that is used for
reliable node communications. Although the node can be configured to
disable this and connect to a remote broker by setting the
<code class="docutils literal"><span class="pre">messagingServerAddress</span></code> configuration to be the remote broker
address. (The <code class="docutils literal"><span class="pre">MockNode</span></code> used during testing does not use this
service, and has a simplified in-memory network layer instead.) This
service is not exposed to any CorDapp code as it is an entirely internal
infrastructural component. However, the developer may need to be aware
of this component, because the <code class="docutils literal"><span class="pre">ArtemisMessagingServer</span></code> is responsible
for configuring the network ports (based upon settings in <code class="docutils literal"><span class="pre">node.conf</span></code>)
and the service configures the security settings of the <code class="docutils literal"><span class="pre">ArtemisMQ</span></code>
middleware and acts to form bridges between node mailbox queues based
upon connection details advertised by the <code class="docutils literal"><span class="pre">NetworkMapService</span></code>. The
<code class="docutils literal"><span class="pre">ArtemisMQ</span></code> broker is configured to use TLS1.2 with a custom
<code class="docutils literal"><span class="pre">TrustStore</span></code> containing a Corda root certificate and a <code class="docutils literal"><span class="pre">KeyStore</span></code>
with a certificate and key signed by a chain back to this root
certificate. These keystores typically reside in the <code class="docutils literal"><span class="pre">certificates</span></code>
sub folder of the node workspace. For the nodes to be able to connect to
each other it is essential that the entire set of nodes are able to
authenticate against each other and thus typically that they share a
common root certificate. Also note that the address configuration
defined for the server is the basis for the address advertised in the
NetworkMapService and thus must be externally connectable by all nodes
in the network.</p>
</div>
<div class="section" id="nodemessagingclient">
<h3>NodeMessagingClient<a class="headerlink" href="#nodemessagingclient" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal"><span class="pre">NodeMessagingClient</span></code> is the implementation of the
<code class="docutils literal"><span class="pre">MessagingService</span></code> interface operating across the <code class="docutils literal"><span class="pre">ArtemisMQ</span></code>
middleware layer. It typically connects to the local <code class="docutils literal"><span class="pre">ArtemisMQ</span></code>
hosted within the <code class="docutils literal"><span class="pre">ArtemisMessagingServer</span></code> service. However, the
<code class="docutils literal"><span class="pre">messagingServerAddress</span></code> configuration can be set to a remote broker
address if required. The responsibilities of this service include
managing the node&#8217;s persistent mailbox, sending messages to remote peer
nodes, acknowledging properly consumed messages and deduplicating any
resent messages. The service also handles the incoming requests from new
RPC client sessions and hands them to the <code class="docutils literal"><span class="pre">CordaRPCOpsImpl</span></code> to carry
out the requests.</p>
</div>
<div class="section" id="inmemorynetworkmapcache">
<h3>InMemoryNetworkMapCache<a class="headerlink" href="#inmemorynetworkmapcache" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal"><span class="pre">InMemoryNetworkMapCache</span></code> implements the <code class="docutils literal"><span class="pre">NetworkMapCache</span></code>
interface and is responsible for tracking the identities and advertised
services of authorised nodes provided by the remote
<code class="docutils literal"><span class="pre">NetworkMapService</span></code>. Typical use is to search for nodes hosting
specific advertised services e.g. a Notary service, or an Oracle
service. Also, this service allows mapping of friendly names, or
<code class="docutils literal"><span class="pre">Party</span></code> identities to the full <code class="docutils literal"><span class="pre">NodeInfo</span></code> which is used in the
<code class="docutils literal"><span class="pre">StateMachineManager</span></code> to convert between the <code class="docutils literal"><span class="pre">CompositeKey</span></code>, or
<code class="docutils literal"><span class="pre">Party</span></code> based addressing used in the flows/contracts and the
physical host and port information required for the physical
<code class="docutils literal"><span class="pre">ArtemisMQ</span></code> messaging layer.</p>
</div>
<div class="section" id="persistentnetworkmapservice-and-networkmapservice">
<h3>PersistentNetworkMapService and NetworkMapService<a class="headerlink" href="#persistentnetworkmapservice-and-networkmapservice" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal"><span class="pre">NetworkMapService</span></code> is a node internal component responsible for
managing and communicating the directory of authenticated registered
nodes and advertised services in the Corda network. Only a single node
in the network (in future this will be a clustered service) should host
the NetworkMapService implementation. All other Corda nodes initiate
their remote connection to the <code class="docutils literal"><span class="pre">NetworkMapService</span></code> early in the
start-up sequence and wait to synchronise their local
<code class="docutils literal"><span class="pre">NetworkMapCache</span></code> before activating any flows. For the
<code class="docutils literal"><span class="pre">PersistentNetworkMapService</span></code> registered <code class="docutils literal"><span class="pre">NodeInfo</span></code> data is
persisted and will include nodes that are not currently active. The
networking layer will persist any messages directed at such inactive
nodes with the expectation that they will be delivered eventually, or
else that the source flow will be terminated by admin intervention.
An <code class="docutils literal"><span class="pre">InMemoryNetworkMapService</span></code> is also available for unit tests
without a database.</p>
<p>The <code class="docutils literal"><span class="pre">NetworkMapService</span></code> should not be used by any flows, or
contracts. Instead they should access the NetworkMapCache service to
access this data.</p>
</div>
</div>
<div class="section" id="storage-and-persistence-related-services">
<h2>Storage and persistence related services<a class="headerlink" href="#storage-and-persistence-related-services" title="Permalink to this headline"></a></h2>
<div class="section" id="storageserviceimpl">
<h3>StorageServiceImpl<a class="headerlink" href="#storageserviceimpl" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal"><span class="pre">StorageServiceImpl</span></code> service simply hold references to the various
persistence related services and provides a single grouped interface on
the <code class="docutils literal"><span class="pre">ServiceHub</span></code>.</p>
</div>
<div class="section" id="dbcheckpointstorage">
<h3>DBCheckpointStorage<a class="headerlink" href="#dbcheckpointstorage" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal"><span class="pre">DBCheckpointStorage</span></code> service is used from within the
<code class="docutils literal"><span class="pre">StateMachineManager</span></code> code to persist the progress of flows. Thus
ensuring that if the program terminates the flow can be restarted
from the same point and complete the flow. This service should not
be used by any CorDapp components.</p>
</div>
<div class="section" id="dbtransactionmappingstorage-and-inmemorystatemachinerecordedtransactionmappingstorage">
<h3>DBTransactionMappingStorage and InMemoryStateMachineRecordedTransactionMappingStorage<a class="headerlink" href="#dbtransactionmappingstorage-and-inmemorystatemachinerecordedtransactionmappingstorage" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal"><span class="pre">DBTransactionMappingStorage</span></code> is used within the
<code class="docutils literal"><span class="pre">StateMachineManager</span></code> code to relate transactions and flows. This
relationship is exposed in the eventing interface to the RPC clients,
thus allowing them to track the end result of a flow and map to the
actual transactions/states completed. Otherwise this service is unlikely
to be accessed by any CorDapps. The
<code class="docutils literal"><span class="pre">InMemoryStateMachineRecordedTransactionMappingStorage</span></code> service is
available as a non-persistent implementation for unit tests with no database.</p>
</div>
<div class="section" id="dbtransactionstorage">
<h3>DBTransactionStorage<a class="headerlink" href="#dbtransactionstorage" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal"><span class="pre">DBTransactionStorage</span></code> service is a persistent implementation of
the <code class="docutils literal"><span class="pre">TransactionStorage</span></code> interface and allows flows read-only
access to full transactions, plus transaction level event callbacks.
Storage of new transactions must be made via the <code class="docutils literal"><span class="pre">recordTransactions</span></code>
method on the <code class="docutils literal"><span class="pre">ServiceHub</span></code>, not via a direct call to this service, so
that the various event notifications can occur.</p>
</div>
<div class="section" id="nodeattachmentservice">
<h3>NodeAttachmentService<a class="headerlink" href="#nodeattachmentservice" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal"><span class="pre">NodeAttachmentService</span></code> provides an implementation of the
<code class="docutils literal"><span class="pre">AttachmentStorage</span></code> interface exposed on the <code class="docutils literal"><span class="pre">ServiceHub</span></code> allowing
transactions to add documents, copies of the contract code and binary
data to transactions. The data is persisted to the local file system
inside the attachments subfolder of the node workspace. The service is
also interfaced to by the web server, which allows files to be uploaded
via an HTTP post request.</p>
</div>
</div>
<div class="section" id="flow-framework-and-event-scheduling-services">
<h2>Flow framework and event scheduling services<a class="headerlink" href="#flow-framework-and-event-scheduling-services" title="Permalink to this headline"></a></h2>
<div class="section" id="statemachinemanager">
<h3>StateMachineManager<a class="headerlink" href="#statemachinemanager" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal"><span class="pre">StateMachineManager</span></code> is the service that runs the active
flows of the node whether initiated by an RPC client, the web
interface, a scheduled state activity, or triggered by receipt of a
message from another node. The <code class="docutils literal"><span class="pre">StateMachineManager</span></code> wraps the
flow code (extensions of the <code class="docutils literal"><span class="pre">FlowLogic</span></code> class) inside an
instance of the <code class="docutils literal"><span class="pre">FlowStateMachineImpl</span></code> class, which is a
<code class="docutils literal"><span class="pre">Quasar</span></code> <code class="docutils literal"><span class="pre">Fiber</span></code>. This allows the <code class="docutils literal"><span class="pre">StateMachineManager</span></code> to suspend
flows at all key lifecycle points and persist their serialized state
to the database via the <code class="docutils literal"><span class="pre">DBCheckpointStorage</span></code> service. This process
uses the facilities of the <code class="docutils literal"><span class="pre">Quasar</span></code> <code class="docutils literal"><span class="pre">Fibers</span></code> library to manage this
process and hence the requirement for the node to run the <code class="docutils literal"><span class="pre">Quasar</span></code>
java instrumentation agent in its JVM.</p>
<p>In operation the <code class="docutils literal"><span class="pre">StateMachineManager</span></code> is typically running an active
flow on its server thread until it encounters a blocking, or
externally visible operation, such as sending a message, waiting for a
message, or initiating a <code class="docutils literal"><span class="pre">subFlow</span></code>. The fiber is then suspended
and its stack frames serialized to the database, thus ensuring that if
the node is stopped, or crashes at this point the flow will restart
with exactly the same action again. To further ensure consistency, every
event which resumes a flow opens a database transaction, which is
committed during this suspension process ensuring that the database
modifications e.g. state commits stay in sync with the mutating changes
of the flow. Having recorded the fiber state the
<code class="docutils literal"><span class="pre">StateMachineManager</span></code> then carries out the network actions as required
(internally one flow message exchanged may actually involve several
physical session messages to authenticate and invoke registered
flows on the remote nodes). The flow will stay suspended until
the required message is returned and the scheduler will resume
processing of other activated flows. On receipt of the expected
response message from the network layer the <code class="docutils literal"><span class="pre">StateMachineManager</span></code>
locates the appropriate flow, resuming it immediately after the
blocking step with the received message. Thus from the perspective of
the flow the code executes as a simple linear progression of
processing, even if there were node restarts and possibly message
resends (the messaging layer deduplicates messages based on an id that
is part of the checkpoint).</p>
<p>The <code class="docutils literal"><span class="pre">StateMachineManager</span></code> service is not directly exposed to the
flows, or contracts themselves.</p>
</div>
<div class="section" id="nodeschedulerservice">
<h3>NodeSchedulerService<a class="headerlink" href="#nodeschedulerservice" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal"><span class="pre">NodeSchedulerService</span></code> implements the <code class="docutils literal"><span class="pre">SchedulerService</span></code>
interface and monitors the Vault updates to track any new states that
implement the <code class="docutils literal"><span class="pre">SchedulableState</span></code> interface and require automatic
scheduled flow initiation. At the scheduled due time the
<code class="docutils literal"><span class="pre">NodeSchedulerService</span></code> will create a new flow instance passing it
a reference to the state that triggered the event. The flow can then
begin whatever action is required. Note that the scheduled activity
occurs in all nodes holding the state in their Vault, it may therefore
be required for the flow to exit early if the current node is not
the intended initiator.</p>
</div>
</div>
<div class="section" id="notary-flow-implementation-services">
<h2>Notary flow implementation services<a class="headerlink" href="#notary-flow-implementation-services" title="Permalink to this headline"></a></h2>
<div class="section" id="persistentuniquenessprovider-inmemoryuniquenessprovider-and-raftuniquenessprovider">
<h3>PersistentUniquenessProvider, InMemoryUniquenessProvider and RaftUniquenessProvider<a class="headerlink" href="#persistentuniquenessprovider-inmemoryuniquenessprovider-and-raftuniquenessprovider" title="Permalink to this headline"></a></h3>
<p>These variants of <code class="docutils literal"><span class="pre">UniquenessProvider</span></code> service are used by the notary
flows to track consumed states and thus reject double-spend
scenarios. The <code class="docutils literal"><span class="pre">InMemoryUniquenessProvider</span></code> is for unit testing only,
the default being the <code class="docutils literal"><span class="pre">PersistentUniquenessProvider</span></code> which records the
changes to the DB. When the Raft based notary is active the states are
tracked by the whole cluster using a <code class="docutils literal"><span class="pre">RaftUniquenessProvider</span></code>. Outside
of the notary flows themselves this service should not be accessed
by any CorDapp components.</p>
</div>
<div class="section" id="notaryservice-simplenotaryservice-validatingnotaryservice-raftvalidatingnotaryservice">
<h3>NotaryService (SimpleNotaryService, ValidatingNotaryService, RaftValidatingNotaryService)<a class="headerlink" href="#notaryservice-simplenotaryservice-validatingnotaryservice-raftvalidatingnotaryservice" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal"><span class="pre">NotaryService</span></code> is an abstract base class for the various concrete
implementations of the Notary server flow. By default, a node does
not run any <code class="docutils literal"><span class="pre">NotaryService</span></code> server component. However, the appropriate
implementation service is automatically started if the relevant
<code class="docutils literal"><span class="pre">ServiceType</span></code> id is included in the node&#8217;s
<code class="docutils literal"><span class="pre">extraAdvertisedServiceIds</span></code> configuration property. The node will then
advertise itself as a Notary via the <code class="docutils literal"><span class="pre">NetworkMapService</span></code> and may then
participate in controlling state uniqueness when contacted by nodes
using the <code class="docutils literal"><span class="pre">NotaryFlow.Client</span></code> <code class="docutils literal"><span class="pre">subFlow</span></code>. The
<code class="docutils literal"><span class="pre">SimpleNotaryService</span></code> only offers protection against double spend, but
does no further verification. The <code class="docutils literal"><span class="pre">ValidatingNotaryService</span></code> checks
that proposed transactions are correctly signed by all keys listed in
the commands and runs the contract verify to ensure that the rules of
the state transition are being followed. The
<code class="docutils literal"><span class="pre">RaftValidatingNotaryService</span></code> further extends the flow to operate
against a cluster of nodes running shared consensus state across the
RAFT protocol (note this requires the additional configuration of the
<code class="docutils literal"><span class="pre">notaryClusterAddresses</span></code> property).</p>
</div>
</div>
<div class="section" id="vault-related-services">
<h2>Vault related services<a class="headerlink" href="#vault-related-services" title="Permalink to this headline"></a></h2>
<div class="section" id="nodevaultservice">
<h3>NodeVaultService<a class="headerlink" href="#nodevaultservice" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal"><span class="pre">NodeVaultService</span></code> implements the <code class="docutils literal"><span class="pre">VaultService</span></code> interface to
allow access to the node&#8217;s own set of unconsumed states. The service
does this by tracking update notifications from the
<code class="docutils literal"><span class="pre">TransactionStorage</span></code> service and processing relevant updates to delete
consumed states and insert new states. The resulting update is then
persisted to the database. The <code class="docutils literal"><span class="pre">VaultService</span></code> then exposes query and
event notification APIs to flows and CorDapp plugins to allow them
to respond to updates, or query for states meeting various conditions to
begin the formation of new transactions consuming them. The equivalent
services are also forwarded to RPC clients, so that they may show
updating views of states held by the node.</p>
</div>
<div class="section" id="nodeschemaservice-and-hibernateobserver">
<h3>NodeSchemaService and HibernateObserver<a class="headerlink" href="#nodeschemaservice-and-hibernateobserver" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal"><span class="pre">HibernateObserver</span></code> runs within the node framework and listens for
vault state updates, the <code class="docutils literal"><span class="pre">HibernateObserver</span></code> then uses the mapping
services of the <code class="docutils literal"><span class="pre">NodeSchemaService</span></code> to record the states in auxiliary
database tables. This allows Corda state updates to be exposed to
external legacy systems by insertion of unpacked data into existing
tables. To enable these features the contract state must implement the
<code class="docutils literal"><span class="pre">QueryableState</span></code> interface to define the mappings.</p>
</div>
</div>
<div class="section" id="node-web-server">
<h2>Node Web Server<a class="headerlink" href="#node-web-server" title="Permalink to this headline"></a></h2>
<p>A web server comes bundled with the node by default, but is not started
automatically. This web server exposes both RPC backed API calls and
static content serving. The web server is not automatically started,
you must explicitly start it in the node driver or define a web port
in your <a href="#id1"><span class="problematic" id="id2">`Cordformation`_</span></a> configuration.</p>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="node-explorer.html" class="btn btn-neutral float-right" title="Node Explorer" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="corda-plugins.html" class="btn btn-neutral" title="The Corda plugin framework" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2016, R3 Limited.
</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>
Reference in New Issue View Git Blame Copy Permalink