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 deleted file mode 100644 index 1f192264c0..0000000000 --- a/data/avro-schema/src/main/resources/avro/net/corda/data/ledger/persistence/FindUnconsumedVisibleExactStates.avsc +++ /dev/null @@ -1,13 +0,0 @@ -{ - "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 FindUnconsumedStatesByType}. 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 cddfd596f0..d2a1676686 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,7 +34,6 @@ "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/gradle.properties b/gradle.properties index d1df236c86..11c6a2a6c7 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 = 35 +cordaApiRevision = 36 # Main kotlinVersion = 1.8.21 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 44f0a8c951..e802588c3f 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 @@ -2,6 +2,7 @@ import net.corda.v5.application.messaging.FlowSession; import net.corda.v5.application.persistence.PagedQuery; +import net.corda.v5.application.persistence.PagedQuery.ResultSet; import net.corda.v5.base.annotations.DoNotImplement; import net.corda.v5.base.annotations.Suspendable; import net.corda.v5.crypto.SecureHash; @@ -16,6 +17,7 @@ import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; +import java.time.Instant; import java.util.List; /** @@ -36,7 +38,7 @@ public interface UtxoLedgerService { /** * Resolves the specified {@link StateRef} instances into {@link StateAndRef} instances of the specified {@link ContractState} type. * - * @param The underlying {@link ContractState} type. + * @param The underlying {@link ContractState} type. * @param stateRefs The {@link StateRef} instances to resolve. * @return Returns a {@link List} of {@link StateAndRef} of the specified {@link ContractState} type. */ @@ -47,7 +49,7 @@ public interface UtxoLedgerService { /** * Resolves the specified {@link StateRef} instance into a {@link StateAndRef} instance of the specified {@link ContractState} type. * - * @param The underlying {@link ContractState} type. + * @param The underlying {@link ContractState} type. * @param stateRef The {@link StateRef} instances to resolve. * @return Returns a {@link StateAndRef} of the specified {@link ContractState} type. */ @@ -92,7 +94,7 @@ public interface UtxoLedgerService { * 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)}. + * This method is more performant than {@link #findUnconsumedStatesByExactType(Class, Integer, Instant)}. *

* Use {@link #query(String, Class)} for a more performant method of retrieving subclasses of a specified type. * @@ -106,14 +108,46 @@ public interface UtxoLedgerService { /** * Finds unconsumed states of the specified {@link ContractState} type in the vault. + *

+ * This version supports paging, limiting the number of results returned in a single query call by setting the + * `limit` argument. + *

+ * Example usage: + *

    + *
  • Kotlin:
    {@code
+     * val resultSet = utxoLedgerService.findUnconsumedStatesByExactType(MyState::class.java, 10, Instant.now())
      *
-     * @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.
+     * processResultsWithApplicationLogic(resultSet.results)
+     *
+     * while (resultSet.hasNext()) {
+     *     val results = resultSet.next()
+     *     processResultsWithApplicationLogic(results)
+     * }
+     * }
    • + *
  • Java:
    {@code
+     * PagedQuery.ResultSet> resultSet = utxoLedgerService.query(MyState.class, 10, Instant.now())
+     *
+     * processResultsWithApplicationLogic(resultSet.getResults());
+     *
+     * while (resultSet.hasNext()) {
+     *     List results = resultSet.next();
+     *     processResultsWithApplicationLogic(results);
+     * }
+     * }
    • + * + * @param The underlying {@link ContractState} type. + * @param type The {@link ContractState} type to find in the vault. + * @param limit The size of each page. + * @param createdTimestampLimit The timestamp limit the underlying query enforces. + * @return Returns a {@link ResultSet} of {@link StateAndRef} of unconsumed states of the specified type. */ @NotNull @Suspendable - List> findUnconsumedStatesByExactType(@NotNull Class type); + ResultSet> findUnconsumedStatesByExactType( + @NotNull Class type, + @NotNull Integer limit, + @NotNull Instant createdTimestampLimit + ); /** * Verifies, signs, collects signatures, records and broadcasts a {@link UtxoSignedTransaction} to participants and observers. @@ -174,8 +208,7 @@ FinalizationResult receiveFinality( * } * * @param transactionBuilder The {@link UtxoTransactionBuilder} to send. - * @param session The receiver {@link FlowSession}. - * + * @param session The receiver {@link FlowSession}. * @return A new merged builder of the original and proposed components. */ @NotNull @@ -203,8 +236,9 @@ UtxoTransactionBuilder receiveTransactionBuilder( * which tracks the differences internally. * If it is called with anything else, it throws InvalidParameterException. *

    + * * @param transactionBuilder The {@link UtxoTransactionBuilder} to send. - * @param session The receiver {@link FlowSession}. + * @param session The receiver {@link FlowSession}. */ @Suspendable void sendUpdatedTransactionBuilder( @@ -260,15 +294,14 @@ void sendUpdatedTransactionBuilder( * } * } * - * @param queryName The name of the named ledger query to use. + * @param queryName The name of the named ledger query to use. * @param resultClass Type that the query should return when executed. - * * @return A {@link VaultNamedParameterizedQuery} query object that can be executed or modified further on. - * * @see VaultNamedParameterizedQuery - * @see PagedQuery.ResultSet + * @see ResultSet * @see VaultNamedQueryFactory */ @Suspendable - @NotNull VaultNamedParameterizedQuery query(@NotNull String queryName, @NotNull Class resultClass); + @NotNull + VaultNamedParameterizedQuery query(@NotNull String queryName, @NotNull Class resultClass); }