# Persistence

Corda offers developers the option to expose all or some part of a contract state to an Object Relational Mapping (ORM) tool to be persisted in a RDBMS. The purpose of this is to assist vault 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.

The ORM mapping is specified using the Java Persistence API (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.

Note

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 “Node administration” for details.

## Schemas

Every `ContractState` can implement the `QueryableState` interface if it wishes to be inserted into the node’s local database and accessible using SQL.

    /**
     * A contract state that may be mapped to database schemas configured for this node to support querying for,
     * or filtering of, states.
     */
    interface QueryableState : ContractState {
        /**
         * Enumerate the schemas this state can export representations of itself as.
         */
        fun supportedSchemas(): Iterable<MappedSchema>

        /**
         * Export a representation for the given schema.
         */
        fun generateMappedObject(schema: MappedSchema): PersistentState
    }

The `QueryableState` 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 `MappedSchema` object return by the `supportedSchemas()` method. Once a schema is selected it must generate that representation when requested via the `generateMappedObject()` method which is then passed to the ORM.

Nodes have an internal `SchemaService` which decides what to persist and what not by selecting the `MappedSchema` to use.

    /**
     * A configuration and customisation point for Object Relational Mapping of contract state objects.
     */
    interface SchemaService {
        /**
         * Represents any options configured on the node for a schema.
         */
        data class SchemaOptions(val databaseSchema: String?, val tablePrefix: String?)

        /**
         * Options configured for this node's schemas.  A missing entry for a schema implies all properties are null.
         */
        val schemaOptions: Map<MappedSchema, SchemaOptions>

        /**
         * Given a state, select schemas to map it to that are supported by [generateMappedObject] and that are configured
         * for this node.
         */
        fun selectSchemas(state: QueryableState): Iterable<MappedSchema>

        /**
         * Map a state to a [PersistentState] for the given schema, either via direct support from the state
         * or via custom logic in this service.
         */
        fun generateMappedObject(state: QueryableState, schema: MappedSchema): PersistentState
    }

    /**
     * A database schema that might be configured for this node.  As well as a name and version for identifying the schema,
     * also list the classes that may be used in the generated object graph in order to configure the ORM tool.
     *
     * @param schemaFamily A class to fully qualify the name of a schema family (i.e. excludes version)
     * @param version The version number of this instance within the family.
     * @param mappedTypes The JPA entity classes that the ORM layer needs to be configure with for this schema.
     */
    abstract class MappedSchema(schemaFamily: Class<*>,
                                val version: Int,
                                val mappedTypes: Iterable<Class<*>>) {
        val name: String = schemaFamily.name
        override fun toString(): String = "${this.javaClass.simpleName}(name=$name, version=$version)"
    }

The `SchemaService` 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 `MappedSchema` offered by a `QueryableState`, automatically upgrade to a later version of a schema or even provide a `MappedSchema` not originally offered by the `QueryableState`.

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.

`MappedSchema` offer a family name that is disambiguated using Java package style name-spacing derived from the class name of a schema family class that is constant across versions, allowing the `SchemaService` to select a preferred version of a schema.

The `SchemaService` is also responsible for the `SchemaOptions` that can be configured for a particular `MappedSchema` which allow the configuration of a database schema or table name prefixes to avoid any clash with other `MappedSchema`.

Note

It is intended that there should be plugin support for the `SchemaService` 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 `QueryableState` being persisted. This will change in due course. Similarly, it does not currently support configuring `SchemaOptions` but will do so in the future.

## Object relational mapping

The persisted representation of a `QueryableState` should be an instance of a `PersistentState` subclass, constructed either by the state itself or a plugin to the `SchemaService`. This allows the ORM layer to always associate a `StateRef` with a persisted representation of a `ContractState` and allows joining with the set of unconsumed states in the vault.

The `PersistentState` subclass should be marked up as a JPA 2.1 Entity 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 flat. The `MappedSchema` must provide a list of all of the JPA entity classes for that schema in order to initialise the ORM layer.

Several examples of entities and mappings are provided in the codebase, including `Cash.State` and `CommercialPaper.State`. For example, here’s the first version of the cash schema.

    package net.corda.schemas

    import net.corda.core.schemas.MappedSchema
    import net.corda.core.schemas.PersistentState
    import javax.persistence.Column
    import javax.persistence.Entity
    import javax.persistence.Table

    /**
     * An object used to fully qualify the [CashSchema] family name (i.e. independent of version).
     */
    object CashSchema

    /**
     * First version of a cash contract ORM schema that maps all fields of the [Cash] contract state as it stood
     * at the time of writing.
     */
    object CashSchemaV1 : MappedSchema(schemaFamily = CashSchema.javaClass, version = 1, mappedTypes = listOf(PersistentCashState::class.java)) {
        @Entity
        @Table(name = "cash_states")
        class PersistentCashState(
                @Column(name = "encumbrance")
                var encumbrance: Int?,

                @Column(name = "owner_key")
                var owner: String,

                @Column(name = "pennies")
                var pennies: Long,

                @Column(name = "ccy_code", length = 3)
                var currency: String,

                @Column(name = "issuer_key")
                var issuerParty: String,

                @Column(name = "issuer_ref")
                var issuerRef: ByteArray
        ) : PersistentState()
    }