ef7ccd3147
* Check array size before accessing * Review fixes * CORDA-540: Make Verifier work in AMQP mode (#1870) * reference to finance module via not hardcoded group ID (#1515) * generic way to reference to group id when loading finance.jar via cordapp * Fixed the node shell to work with the DataFeed class * Attempt to make NodeStatePersistenceTests more stable (#1895) By ensuring that the nodes are properly started and aware of each other before firing any flows through them. Also minor refactoring. * Disable unstable test on Windows (#1899) * CORDA-530 Don't soft-lock non-fungible states (#1794) * Don't run unlock query if nothing was locked * Constructors should not have side-effects * [CORDA-442] let Driver run without network map (#1890) * [CORDA-442] let Driver run without network map - Nodes started by driver run without a networkMapNode. - Driver does not take a networkMapStartStrategy anymore - a new parameter in the configuration "noNetworkMapServiceMode" allows for a node not to be a networkMapNode nor to connect to one. - Driver now waits for each node to write its own NodeInfo file to disk and then copies it into each other node. - When driver starts a node N, it waits for every node to be have N nodes in their network map. Note: the code to copy around the NodeInfo files was already in DemoBench, the NodeInfoFilesCopier class was just moved from DemoBench into core (I'm very open to core not being the best place, please advise) * Added missing cordappPackage dependencies. (#1894) * Eliminate circular dependency of NodeSchedulerService on ServiceHub. (#1891) * Update customSchemas documentation. (#1902) * [CORDA-694] Commands visibility for Oracles (without sacrificing privacy) (#1835) new checkCommandVisibility feature for Oracles * CORDA-599 PersistentNetworkMapCache no longer circularly depends on SH (#1652) * CORDA-725 - Change AMQP identifier to officially assigned value This does change our header format so pre-cached test files need regenerating * CORDA-725 - update changelog * CORDA-680 Update cordapp packages documentation (#1901) * Introduce MockNetworkParameters * Cordformation in Kotlin (#1873) Cordformation rewritten in kotlin. * Kotlin migration * Review Comments * CORDA-704: Implement `@DoNotImplement` annotation (#1903) * Enhance the API Scanner plugin to monitor class annotations. * Implement @DoNotImplement annotation, and apply it. * Update API definition. * Update API change detection to handle @DoNotImplement. * Document the `@DoNotImplement` annotation. * Experimental support for PostgreSQL (#1525) * Cash selection refactoring such that 3d party DB providers are only required to implement Coin Selection SQL logic. * Re-added debug logging statement. * Updated to include PR review feedback from VK * Refactoring following rebase from master. * Fix broken JUnits following rebase. * Use JDBC ResultSet getBlob() and added custom serializer to address concern raised by tomtau in PR. * Fix failing JUnits. * Experimental support for PostgreSQL: CashSelection done using window functions * Moved postgresql version information into corda/build.gradle * Using a PreparedStatement in CashSelectionPostgreSQLImpl * Changed the PostgreSQL Cash Selection implementation to use the new refactored AbstractCashSelection * * Retire MockServiceHubInternal (#1909) * Introduce rigorousMock * Add test-utils and node-driver to generated documentation * Fix-up: Bank Of Corda sample (#1912) In the previous version when running with `--role ISSUER` the application failed to start. The reason was that in spite of `quantity` and `currency` were optional, un-necessary `requestParams` been constructed regardless. * move SMM * Interface changes for multi-threading * CORDA-351: added dependency check plugin to gradle build script (#1911) * CORDA-351: added dependency check plugin to gradle build script * CORDA-351: Added suppression stub file with example * CORDA-351: added suppresionFile property * CORDA-435 - Ensure Kryo only tests use Kryo serializatin context Also correct lambda typos (from lamba) * Network map service REST API wrapper (#1907) * Network map client - WIP * Java doc and doc for doc site * remove javax.ws dependency * NetworkParameter -> NetworkParameters * move network map client to node * Fix jetty test dependencies * NetworkParameter -> NetworkParameters * Address PR issues * Address PR issues and unit test fix * Address PR issues * Fixing Bank-Of-Corda Demo in `master` (#1922) * Fix-up: Bank Of Corda sample Use correct CorDapp packages to scan (cherry picked from commit2caa134) * Set adequate permissions for the nodes such that NodeExplorer can connect (cherry picked from commitae88242) * Set adequate permissions for the nodes such that NodeExplorer can connect (cherry picked from commitae88242) * Correct run configuration * Fix-up port numbers * CORDA-435 - AMQP serialisation cannot work with private vals They won't be reported as properties by the introspector and thus we will fail to find a constructor for them. This makes sense as we will be unable to serialise an object whose members we cannot read * CORDA-435 - AMQP enablement fixes AMQP has different serialization rules than Kryo surrounding the way we introspect objects to work out how to construct them * [CORDA-442] make MockNetwork not start a networkmap node (#1908) * [CORDA-442] make MockNetwork not start a networkmap node Now MockNetwork will put the appropriate NodeInfos inside each running node networkMapCache. Tests relating to networkmap node starting and interaction have been removed since they where relaying on MockNetwork * Minor fix for api checker script to support macOS * Retrofit changes from Enterprise PR #61 (#1934) * Introduce MockNodeParameters/Args (#1923) * CORDA-736 Add some new features to corda.jar via node.conf for testing (#1926) * CORDA-699 Add injection or modification of memory network messages (#1920) * Updated API stability changeset to reflect new schema attribute name.
8.3 KiB
API: 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.
../../core/src/main/kotlin/net/corda/core/schemas/PersistentTypes.kt
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.
../../node/src/main/kotlin/net/corda/node/services/api/SchemaService.kt
../../core/src/main/kotlin/net/corda/core/schemas/PersistentTypes.kt
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 configurable. 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.
Custom schema registration
Custom contract schemas are automatically registered at startup time for CorDapps. The node bootstrap process will scan for schemas (any class that extends the MappedSchema interface) in the plugins configuration directory in your CorDapp jar.
For testing purposes it is necessary to manually register the packages containing custom schemas as follows:
- Tests using
MockNetworkandMockNodemust explicitly register packages using the cordappPackages parameter ofMockNetwork - Tests using
MockServicesmust explicitly register packages using the cordappPackages parameter of theMockServicesmakeTestDatabaseAndMockServices() helper method.
Note
Tests using the DriverDSL will automatically register your custom schemas if they are in the same project structure as the driver call.
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.
../../finance/src/main/kotlin/net/corda/finance/schemas/CashSchemaV1.kt
Identity mapping
Schema entity attributes defined by identity types (AbstractParty, Party, AnonymousParty) are automatically processed to ensure only the X500Name of the identity is persisted where an identity is well known, otherwise a null value is stored in the associated column. To preserve privacy, identity keys are never persisted. Developers should use the IdentityService to resolve keys from well know X500 identity names.
JDBC session
Apps may also interact directly with the underlying Node's database by using a standard JDBC connection (session) as described by the Java SQL Connection API
Use the ServiceHub jdbcSession function to obtain a JDBC connection as illustrated in the following example:
../../node/src/test/kotlin/net/corda/node/services/database/HibernateConfigurationTest.kt
JDBC session's can be used in Flows and Service Plugins (see "flow-state-machines")
The following example illustrates the creation of a custom corda service using a jdbcSession:
../../docs/source/example-code/src/main/kotlin/net/corda/docs/CustomVaultQuery.kt
which is then referenced within a custom flow:
../../docs/source/example-code/src/main/kotlin/net/corda/docs/CustomVaultQuery.kt