CORE-11066 Create Json Factory interface and CorDapp property (#1033)

Create the main interface for contract state JSON factories. This interface will be implemented by CorDapps and one default internal factory for ContractState.

Added a new CorDapp property called Corda-Ledger-Vault-Json-Factory-Classes that will pick up the implementations from CorDapps.

cordapp-configuration/src/main/resources/net/corda/cordapp/cordapp-configuration.properties

@@ -14,6 +14,7 @@ Corda-InitiatedFlow-Classes=IMPLEMENTS;net.corda.v5.application.flows.ResponderF
 Corda-Subflow-Classes=IMPLEMENTS;net.corda.v5.application.flows.Subflow
 Corda-Token-Observer-Classes=IMPLEMENTS;net.corda.v5.ledger.utxo.observer.UtxoLedgerTokenStateObserver
 Corda-Ledger-Named-Query-Classes=IMPLEMENTS;net.corda.v5.ledger.utxo.query.VaultNamedQueryFactory
+Corda-Ledger-Vault-Json-Factory-Classes=IMPLEMENTS;net.corda.v5.ledger.utxo.query.json.ContractStateVaultJsonFactory
 
 # Corda should adjust this version over time, as required.
 Minimum-Corda-Plugins-Version=7.0.0

gradle.properties

@@ -10,7 +10,7 @@ cordaProductVersion = 5.0.0
 # NOTE: update this each time this module contains a breaking change
 ## NOTE: currently this is a top level revision, so all API versions will line up, but this could be moved to
 ##   a per module property in which case module versions can change independently.
-cordaApiRevision = 749
+cordaApiRevision = 750
 
 # Main
 kotlinVersion = 1.8.10

ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/query/VaultNamedQueryFactory.java

@@ -1,11 +1,15 @@
 package net.corda.v5.ledger.utxo.query;
 
+import net.corda.v5.ledger.utxo.query.json.ContractStateVaultJsonFactory;
 import net.corda.v5.ledger.utxo.query.registration.VaultNamedQueryBuilderFactory;
 import org.jetbrains.annotations.NotNull;
 
 /**
  * The main interface that needs to be implemented by the named ledger queries. Implementing this interface will define how
  * the named query will be built and stored.
+ *
+ * @see ContractStateVaultJsonFactory to define how a given state type will be represented as a JSON string.
+ *
  * <p>
  * Example usage:
  * <ul>

ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/query/json/ContractStateVaultJsonFactory.java

@@ -0,0 +1,83 @@
+package net.corda.v5.ledger.utxo.query.json;
+
+import net.corda.v5.application.marshalling.JsonMarshallingService;
+import net.corda.v5.ledger.utxo.ContractState;
+import net.corda.v5.ledger.utxo.UtxoLedgerService;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Implement a {@link ContractStateVaultJsonFactory} to create a JSON representation of a state to store alongside
+ * the state in the vault. This JSON representation can be used to query states from flows using
+ * {@link UtxoLedgerService#query}.
+ * <p>
+ * Classes that implement {@link ContractStateVaultJsonFactory} will be executed in a hierarchical way. That means
+ * every factory that belongs to a given state or that given state's ancestors will be executed and the end result
+ * will be a combined JSON. The combined JSON will be keyed by the state type specified by the factory.
+ * <p>
+ * In order to perform a "query by state" query using `UtxoLedgerService.query` for a particular state type,
+ * a factory for that given type must be present, even if it's just returning an empty JSON string.
+ * <p>
+ * Please note that only one factory can be registered for a state type.
+ * <p>
+ * Example usage:
+ * <ul>
+ * <li>Kotlin:<pre>{@code
+ * class TestUtxoStateVaultJsonFactory: ContractStateVaultJsonFactory<TestUtxoState> {
+ *
+ *     private data class TestUtxoStatePojo(val testField: String)
+ *
+ *     override val stateType: Class<TestUtxoState> = TestUtxoState::class.java
+ *
+ *     override fun append(state: TestUtxoState, jsonMarshallingService: JsonMarshallingService): String {
+ *         return jsonMarshallingService.format(TestUtxoStatePojo(state.testField))
+ *     }
+ * }
+ *
+ * }</pre></li>
+ * <li>Java:<pre>{@code
+ * public class TestUtxoStateVaultJsonFactory implements ContractStateVaultJsonFactory<TestUtxoState> {
+ *
+ *     private class TestUtxoStatePojo {
+ *         private String testField;
+ *
+ *         TestUtxoStatePojo(String testField) {
+ *             this.testField = testField;
+ *         }
+ *
+ *         String getTestField() {
+ *             return this.testField;
+ *         }
+ *     }
+ *
+ *     @Override
+ *     public Class<T> getStateType() {
+ *         return TestUtxoState.class;
+ *     }
+ *
+ *     @Override
+ *     public String append(TestUtxoState state, JsonMarshallingService jsonMarshallingService) {
+ *         return jsonMarshallingService.format(new TestUtxoStatePojo(state.getTestField()));
+ *     }
+ * }
+ * }</pre></li></ul>
+ *
+ * @param <T> The type of the state that this class belongs to. Must be a subtype of {@link ContractState}.
+ */
+public interface ContractStateVaultJsonFactory<T extends ContractState> {
+
+    /**
+     * @return The type of the state this factory belongs to.
+     */
+    @NotNull Class<T> getStateType();
+
+    /**
+     * The function that defines how the given state can be represented as a JSON string.
+     *
+     * @param state The state object.
+     * @param jsonMarshallingService An instance of a {@link JsonMarshallingService} that can be used when creating a
+     * JSON representation.
+     *
+     * @return The JSON representation as a String.
+     */
+    @NotNull String create(@NotNull T state, @NotNull JsonMarshallingService jsonMarshallingService);
+}

ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/query/json/package-info.java

@@ -0,0 +1,4 @@
+@Export
+package net.corda.v5.ledger.utxo.query.json;
+
+import org.osgi.annotation.bundle.Export;