<h1>Persistence<aclass="headerlink"href="#persistence"title="Permalink to this headline">¶</a></h1>
<p>Corda offers developers the option to expose all or some part of a contract state to an <em>Object Relational Mapping</em> (ORM) tool
to be persisted in a RDBMS. The purpose of this is to assist <em>vault</em> development by effectively indexing
persisted contract states held in the vault for the purpose of running queries over them and to allow relational joins
between Corda data and private data local to the organisation owning a node.</p>
<p>The ORM mapping is specified using the <aclass="reference external"href="https://en.wikipedia.org/wiki/Java_Persistence_API">Java Persistence API</a> (JPA)
as annotations and is converted to database table rows by the node automatically every time a state is recorded in the
node’s local vault as part of a transaction.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">Presently the node includes an instance of the H2 database but any database that supports JDBC is a candidate and
the node will in the future support a range of database implementations via their JDBC drivers. Much of the node
internal state is also persisted there. You can access the internal H2 database via JDBC, please see the info
in “<aclass="reference internal"href="node-administration.html"><spanclass="doc">Node administration</span></a>” for details.</p>
</div>
<divclass="section"id="schemas">
<h2>Schemas<aclass="headerlink"href="#schemas"title="Permalink to this headline">¶</a></h2>
<p>Every <codeclass="docutils literal"><spanclass="pre">ContractState</span></code> can implement the <codeclass="docutils literal"><spanclass="pre">QueryableState</span></code> interface if it wishes to be inserted into the node’s local
database and accessible using SQL.</p>
<p>The <codeclass="docutils literal"><spanclass="pre">QueryableState</span></code> interface requires the state to enumerate the different relational schemas it supports, for instance in
cases where the schema has evolved, with each one being represented by a <codeclass="docutils literal"><spanclass="pre">MappedSchema</span></code> object return by the
<codeclass="docutils literal"><spanclass="pre">supportedSchemas()</span></code> method. Once a schema is selected it must generate that representation when requested via the
<codeclass="docutils literal"><spanclass="pre">generateMappedObject()</span></code> method which is then passed to the ORM.</p>
<p>Nodes have an internal <codeclass="docutils literal"><spanclass="pre">SchemaService</span></code> which decides what to persist and what not by selecting the <codeclass="docutils literal"><spanclass="pre">MappedSchema</span></code>
to use.</p>
<p>The <codeclass="docutils literal"><spanclass="pre">SchemaService</span></code> can be configured by a node administrator to select the schemas used by each app. In this way the
relational view of ledger states can evolve in a controlled fashion in lock-step with internal systems or other
integration points and not necessarily with every upgrade to the contract code.
It can select from the <codeclass="docutils literal"><spanclass="pre">MappedSchema</span></code> offered by a <codeclass="docutils literal"><spanclass="pre">QueryableState</span></code>, automatically upgrade to a
later version of a schema or even provide a <codeclass="docutils literal"><spanclass="pre">MappedSchema</span></code> not originally offered by the <codeclass="docutils literal"><spanclass="pre">QueryableState</span></code>.</p>
<p>It is expected that multiple different contract state implementations might provide mappings to some common schema.
For example an Interest Rate Swap contract and an Equity OTC Option contract might both provide a mapping to a common
Derivative schema. The schemas should typically not be part of the contract itself and should exist independently of it
to encourage re-use of a common set within a particular business area or Cordapp.</p>
<p><codeclass="docutils literal"><spanclass="pre">MappedSchema</span></code> offer a family name that is disambiguated using Java package style name-spacing derived from the class name
of a <em>schema family</em> class that is constant across versions, allowing the <codeclass="docutils literal"><spanclass="pre">SchemaService</span></code> to select a preferred version
of a schema.</p>
<p>The <codeclass="docutils literal"><spanclass="pre">SchemaService</span></code> is also responsible for the <codeclass="docutils literal"><spanclass="pre">SchemaOptions</span></code> that can be configured for a particular <codeclass="docutils literal"><spanclass="pre">MappedSchema</span></code>
which allow the configuration of a database schema or table name prefixes to avoid any clash with other <codeclass="docutils literal"><spanclass="pre">MappedSchema</span></code>.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">It is intended that there should be plugin support for the <codeclass="docutils literal"><spanclass="pre">SchemaService</span></code> to offer the version upgrading and
additional schemas as part of Cordapps, and that the active schemas be confgurable. However the present implementation
offers none of this and simply results in all versions of all schemas supported by a <codeclass="docutils literal"><spanclass="pre">QueryableState</span></code> being persisted.
This will change in due course. Similarly, it does not currently support configuring <codeclass="docutils literal"><spanclass="pre">SchemaOptions</span></code> but will do so in
<h2>Object Relational Mapping<aclass="headerlink"href="#object-relational-mapping"title="Permalink to this headline">¶</a></h2>
<p>The persisted representation of a <codeclass="docutils literal"><spanclass="pre">QueryableState</span></code> should be an instance of a <codeclass="docutils literal"><spanclass="pre">PersistentState</span></code> subclass, constructed
either by the state itself or a plugin to the <codeclass="docutils literal"><spanclass="pre">SchemaService</span></code>. This allows the ORM layer to always associate a
<codeclass="docutils literal"><spanclass="pre">StateRef</span></code> with a persisted representation of a <codeclass="docutils literal"><spanclass="pre">ContractState</span></code> and allows joining with the set of unconsumed states
in the vault.</p>
<p>The <codeclass="docutils literal"><spanclass="pre">PersistentState</span></code> subclass should be marked up as a JPA 2.1 <em>Entity</em> with a defined table name and having
properties (in Kotlin, getters/setters in Java) annotated to map to the appropriate columns and SQL types. Additional
entities can be included to model these properties where they are more complex, for example collections, so the mapping
does not have to be <em>flat</em>. The <codeclass="docutils literal"><spanclass="pre">MappedSchema</span></code> must provide a list of all of the JPA entity classes for that schema in order
to initialise the ORM layer.</p>
<p>Several examples of entities and mappings are provided in the codebase, including <codeclass="docutils literal"><spanclass="pre">Cash.State</span></code> and
<codeclass="docutils literal"><spanclass="pre">CommercialPaper.State</span></code>. For example, here’s the first version of the cash schema.</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>.
