From 30e55737febe6424d846d180c6bcfcb3cc64293e Mon Sep 17 00:00:00 2001 From: "eunjee.yang" Date: Mon, 25 Sep 2023 08:55:57 +0100 Subject: [PATCH 1/7] CORE-16615: introduce new api to find an unconsumed states --- .../FindUnconsumedVisibleExactStates.avsc | 13 +++++++++++++ .../persistence/LedgerPersistenceRequest.avsc | 1 + ...gerPersistenceRequestSchemaCompatibilityTest.kt | 2 ++ .../corda/v5/ledger/utxo/UtxoLedgerService.java | 14 +++++++++++++- 4 files changed, 29 insertions(+), 1 deletion(-) create mode 100644 data/avro-schema/src/main/resources/avro/net/corda/data/ledger/persistence/FindUnconsumedVisibleExactStates.avsc diff --git a/data/avro-schema/src/main/resources/avro/net/corda/data/ledger/persistence/FindUnconsumedVisibleExactStates.avsc b/data/avro-schema/src/main/resources/avro/net/corda/data/ledger/persistence/FindUnconsumedVisibleExactStates.avsc new file mode 100644 index 0000000000..829f9821da --- /dev/null +++ b/data/avro-schema/src/main/resources/avro/net/corda/data/ledger/persistence/FindUnconsumedVisibleExactStates.avsc @@ -0,0 +1,13 @@ +{ + "type": "record", + "name": "FindUnconsumedStatesByExactType", + "doc": "Retrieve the unconsumed visible states of specific type. This only retrieves exact type excluding its states of subclass unlike {@link FindUnconsumedStatesByExactType}. One of several types of ledger persistence request {@link LedgerPersistenceRequest}", + "namespace": "net.corda.data.ledger.persistence", + "fields": [ + { + "name": "stateClassName", + "type": "string", + "doc": "The fully qualified state class name" + } + ] +} diff --git a/data/avro-schema/src/main/resources/avro/net/corda/data/ledger/persistence/LedgerPersistenceRequest.avsc b/data/avro-schema/src/main/resources/avro/net/corda/data/ledger/persistence/LedgerPersistenceRequest.avsc index f45bde6967..0fd22ccdf9 100644 --- a/data/avro-schema/src/main/resources/avro/net/corda/data/ledger/persistence/LedgerPersistenceRequest.avsc +++ b/data/avro-schema/src/main/resources/avro/net/corda/data/ledger/persistence/LedgerPersistenceRequest.avsc @@ -34,6 +34,7 @@ "net.corda.data.ledger.persistence.PersistTransactionIfDoesNotExist", "net.corda.data.ledger.persistence.FindTransaction", "net.corda.data.ledger.persistence.FindUnconsumedStatesByType", + "net.corda.data.ledger.persistence.FindUnconsumedStatesByExactType", "net.corda.data.ledger.persistence.ResolveStateRefs", "net.corda.data.ledger.persistence.UpdateTransactionStatus", "net.corda.data.persistence.FindWithNamedQuery", diff --git a/data/avro-schema/src/test/kotlin/net/corda/data/ledger/persistence/LedgerPersistenceRequestSchemaCompatibilityTest.kt b/data/avro-schema/src/test/kotlin/net/corda/data/ledger/persistence/LedgerPersistenceRequestSchemaCompatibilityTest.kt index 834a6bb292..83b9d4ac9e 100644 --- a/data/avro-schema/src/test/kotlin/net/corda/data/ledger/persistence/LedgerPersistenceRequestSchemaCompatibilityTest.kt +++ b/data/avro-schema/src/test/kotlin/net/corda/data/ledger/persistence/LedgerPersistenceRequestSchemaCompatibilityTest.kt @@ -50,6 +50,7 @@ class LedgerPersistenceRequestSchemaCompatibilityTest { "net.corda.data.ledger.persistence.PersistTransactionIfDoesNotExist", "net.corda.data.ledger.persistence.FindTransaction", "net.corda.data.ledger.persistence.FindUnconsumedStatesByType", + "net.corda.data.ledger.persistence.FindUnconsumedStatesByExactType", "net.corda.data.ledger.persistence.ResolveStateRefs", "net.corda.data.ledger.persistence.UpdateTransactionStatus", "net.corda.data.persistence.FindWithNamedQuery", @@ -74,6 +75,7 @@ class LedgerPersistenceRequestSchemaCompatibilityTest { PersistTransactionIfDoesNotExist::class.java.name to PersistTransactionIfDoesNotExist.`SCHEMA$`, FindTransaction::class.java.name to FindTransaction.`SCHEMA$`, FindUnconsumedStatesByType::class.java.name to FindUnconsumedStatesByType.`SCHEMA$`, + FindUnconsumedStatesByExactType::class.java.name to FindUnconsumedStatesByExactType.`SCHEMA$`, ResolveStateRefs::class.java.name to ResolveStateRefs.`SCHEMA$`, UpdateTransactionStatus::class.java.name to UpdateTransactionStatus.`SCHEMA$`, FindWithNamedQuery::class.java.name to FindWithNamedQuery.`SCHEMA$`, diff --git a/ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/UtxoLedgerService.java b/ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/UtxoLedgerService.java index 1603f3d86e..75bca9ffb0 100644 --- a/ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/UtxoLedgerService.java +++ b/ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/UtxoLedgerService.java @@ -87,7 +87,8 @@ public interface UtxoLedgerService { UtxoFilteredTransactionBuilder filterSignedTransaction(@NotNull UtxoSignedTransaction transaction); /** - * Finds unconsumed states of the specified {@link ContractState} type in the vault. + * Finds unconsumed states and subclasses of the states of the specified {@link ContractState} type in the vault. + * Only use this if you really care about catching all child classes, it has poor performance. * * @param The underlying {@link ContractState} type. * @param type The {@link ContractState} type to find in the vault. @@ -97,6 +98,17 @@ public interface UtxoLedgerService { @Suspendable List> findUnconsumedStatesByType(@NotNull Class type); + /** + * Finds unconsumed states of the specified {@link ContractState} type in the vault. + * + * @param The underlying {@link ContractState} type. + * @param type The {@link ContractState} type to find in the vault. + * @return Returns a {@link List} of {@link StateAndRef} of unconsumed states of the specified type, or an empty list if no states could be found. + */ + @NotNull + @Suspendable + List> findUnconsumedStatesByExactType(@NotNull Class type); + /** * Verifies, signs, collects signatures, records and broadcasts a {@link UtxoSignedTransaction} to participants and observers. * From c158c91e9c2e8fa9109716a0676341b4993233ea Mon Sep 17 00:00:00 2001 From: "eunjee.yang" Date: Mon, 25 Sep 2023 11:17:49 +0100 Subject: [PATCH 2/7] CORE-16615: update Kdoc --- .../main/java/net/corda/v5/ledger/utxo/UtxoLedgerService.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/UtxoLedgerService.java b/ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/UtxoLedgerService.java index 75bca9ffb0..d6eaf6727a 100644 --- a/ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/UtxoLedgerService.java +++ b/ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/UtxoLedgerService.java @@ -87,8 +87,8 @@ public interface UtxoLedgerService { UtxoFilteredTransactionBuilder filterSignedTransaction(@NotNull UtxoSignedTransaction transaction); /** - * Finds unconsumed states and subclasses of the states of the specified {@link ContractState} type in the vault. - * Only use this if you really care about catching all child classes, it has poor performance. + * Finds unconsumed states and subclasses of the states of the specified {@link ContractState} type and its subclasses in the vault. + * Only use this if you really care about catching all child classes. {@link findUnconsumedStatesByExactType} performs better for exact-matching use cases. * * @param The underlying {@link ContractState} type. * @param type The {@link ContractState} type to find in the vault. From aa6aebae456ae48c797fa7d1b21bde0b18949a4b Mon Sep 17 00:00:00 2001 From: "eunjee.yang" Date: Mon, 25 Sep 2023 11:54:28 +0100 Subject: [PATCH 3/7] CORE-16615: update javadoc --- .../main/java/net/corda/v5/ledger/utxo/UtxoLedgerService.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/UtxoLedgerService.java b/ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/UtxoLedgerService.java index d6eaf6727a..35c6b43b3f 100644 --- a/ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/UtxoLedgerService.java +++ b/ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/UtxoLedgerService.java @@ -88,7 +88,7 @@ public interface UtxoLedgerService { /** * Finds unconsumed states and subclasses of the states of the specified {@link ContractState} type and its subclasses in the vault. - * Only use this if you really care about catching all child classes. {@link findUnconsumedStatesByExactType} performs better for exact-matching use cases. + * Only use this if you really care about catching all child classes. {@link #findUnconsumedStatesByExactType(Class)} performs better for exact-matching use cases. * * @param The underlying {@link ContractState} type. * @param type The {@link ContractState} type to find in the vault. From d95921177f7b19157b0c4003a973d51d4c64b1a5 Mon Sep 17 00:00:00 2001 From: "eunjee.yang" Date: Mon, 25 Sep 2023 12:30:47 +0100 Subject: [PATCH 4/7] CORE-16615: bump version --- gradle.properties | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gradle.properties b/gradle.properties index 4c6f568ae3..2c23954d9b 100644 --- a/gradle.properties +++ b/gradle.properties @@ -9,7 +9,7 @@ cordaProductVersion = 5.1.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 = 22 +cordaApiRevision = 23 # Main kotlinVersion = 1.8.21 From 0ed5580ce3194f8741882ec179b2d1d66c1c3bc2 Mon Sep 17 00:00:00 2001 From: "eunjee.yang" Date: Mon, 25 Sep 2023 15:06:58 +0100 Subject: [PATCH 5/7] CORE-16615: update doc in avro record --- .../ledger/persistence/FindUnconsumedVisibleExactStates.avsc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/avro-schema/src/main/resources/avro/net/corda/data/ledger/persistence/FindUnconsumedVisibleExactStates.avsc b/data/avro-schema/src/main/resources/avro/net/corda/data/ledger/persistence/FindUnconsumedVisibleExactStates.avsc index 829f9821da..1f192264c0 100644 --- a/data/avro-schema/src/main/resources/avro/net/corda/data/ledger/persistence/FindUnconsumedVisibleExactStates.avsc +++ b/data/avro-schema/src/main/resources/avro/net/corda/data/ledger/persistence/FindUnconsumedVisibleExactStates.avsc @@ -1,7 +1,7 @@ { "type": "record", "name": "FindUnconsumedStatesByExactType", - "doc": "Retrieve the unconsumed visible states of specific type. This only retrieves exact type excluding its states of subclass unlike {@link FindUnconsumedStatesByExactType}. One of several types of ledger persistence request {@link LedgerPersistenceRequest}", + "doc": "Retrieve the unconsumed visible states of specific type. This only retrieves exact type excluding its states of subclass unlike {@link FindUnconsumedStatesByType}. One of several types of ledger persistence request {@link LedgerPersistenceRequest}", "namespace": "net.corda.data.ledger.persistence", "fields": [ { From 62791bf6c3ddbc4a5d1d5740391fb93538fdd654 Mon Sep 17 00:00:00 2001 From: "eunjee.yang" Date: Mon, 25 Sep 2023 16:00:07 +0100 Subject: [PATCH 6/7] CORE-16615: update java doc --- .../net/corda/v5/ledger/utxo/UtxoLedgerService.java | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/UtxoLedgerService.java b/ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/UtxoLedgerService.java index 35c6b43b3f..aa844829df 100644 --- a/ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/UtxoLedgerService.java +++ b/ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/UtxoLedgerService.java @@ -87,8 +87,14 @@ public interface UtxoLedgerService { UtxoFilteredTransactionBuilder filterSignedTransaction(@NotNull UtxoSignedTransaction transaction); /** - * Finds unconsumed states and subclasses of the states of the specified {@link ContractState} type and its subclasses in the vault. - * Only use this if you really care about catching all child classes. {@link #findUnconsumedStatesByExactType(Class)} performs better for exact-matching use cases. + * Finds unconsumed states that are concrete implementations or subclasses of {@code type}. + *

+ * Only use this method if subclasses of {@code type} must be returned. + *

+ * Use {@link #findUnconsumedStatesByExactType(Class)} to return exact instances of the input {@code type}. + * This method is more performant than {@link #findUnconsumedStatesByType(Class)}. + *

+ * Use {@link #query(String, Class)} for a more performant method of retrieving subclasses of a specified type. * * @param The underlying {@link ContractState} type. * @param type The {@link ContractState} type to find in the vault. From 6b452395add7c067a22bcf7b05067c5c0e5d8513 Mon Sep 17 00:00:00 2001 From: "eunjee.yang" Date: Mon, 25 Sep 2023 16:04:02 +0100 Subject: [PATCH 7/7] CORE-16615: remove findUnconsumedStatesByExactType from compatibility test --- .../LedgerPersistenceRequestSchemaCompatibilityTest.kt | 2 -- 1 file changed, 2 deletions(-) diff --git a/data/avro-schema/src/test/kotlin/net/corda/data/ledger/persistence/LedgerPersistenceRequestSchemaCompatibilityTest.kt b/data/avro-schema/src/test/kotlin/net/corda/data/ledger/persistence/LedgerPersistenceRequestSchemaCompatibilityTest.kt index 83b9d4ac9e..834a6bb292 100644 --- a/data/avro-schema/src/test/kotlin/net/corda/data/ledger/persistence/LedgerPersistenceRequestSchemaCompatibilityTest.kt +++ b/data/avro-schema/src/test/kotlin/net/corda/data/ledger/persistence/LedgerPersistenceRequestSchemaCompatibilityTest.kt @@ -50,7 +50,6 @@ class LedgerPersistenceRequestSchemaCompatibilityTest { "net.corda.data.ledger.persistence.PersistTransactionIfDoesNotExist", "net.corda.data.ledger.persistence.FindTransaction", "net.corda.data.ledger.persistence.FindUnconsumedStatesByType", - "net.corda.data.ledger.persistence.FindUnconsumedStatesByExactType", "net.corda.data.ledger.persistence.ResolveStateRefs", "net.corda.data.ledger.persistence.UpdateTransactionStatus", "net.corda.data.persistence.FindWithNamedQuery", @@ -75,7 +74,6 @@ class LedgerPersistenceRequestSchemaCompatibilityTest { PersistTransactionIfDoesNotExist::class.java.name to PersistTransactionIfDoesNotExist.`SCHEMA$`, FindTransaction::class.java.name to FindTransaction.`SCHEMA$`, FindUnconsumedStatesByType::class.java.name to FindUnconsumedStatesByType.`SCHEMA$`, - FindUnconsumedStatesByExactType::class.java.name to FindUnconsumedStatesByExactType.`SCHEMA$`, ResolveStateRefs::class.java.name to ResolveStateRefs.`SCHEMA$`, UpdateTransactionStatus::class.java.name to UpdateTransactionStatus.`SCHEMA$`, FindWithNamedQuery::class.java.name to FindWithNamedQuery.`SCHEMA$`,