Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

CORE-15552 Add findUnconsumedStatesByExactType paging API #1292

Merged
merged 4 commits into from
Oct 13, 2023
Merged

CORE-15552 Add findUnconsumedStatesByExactType paging API #1292

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
46ad03d
CORE-15552 Add `findUnconsumedStatesByExactType` paging API
lankydan Oct 11, 2023
d64f8f9
CORE-15552 Update JavaDoc
lankydan Oct 11, 2023
3a2c725
CORE-15552 Remove non paged api
lankydan Oct 13, 2023
1815602
CORE-15552 Version
lankydan Oct 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 0 additions & 13 deletions ...in/resources/avro/net/corda/data/ledger/persistence/FindUnconsumedVisibleExactStates.avsc
View file
Open in desktop

This file was deleted.

1 change: 0 additions & 1 deletion ...a/src/main/resources/avro/net/corda/data/ledger/persistence/LedgerPersistenceRequest.avsc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
2 changes: 1 addition & 1 deletion gradle.properties
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
63 changes: 48 additions & 15 deletions ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/UtxoLedgerService.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -16,6 +17,7 @@
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

import java.time.Instant;
import java.util.List;

/**
Expand All @@ -36,7 +38,7 @@ public interface UtxoLedgerService {
/**
* Resolves the specified {@link StateRef} instances into {@link StateAndRef} instances of the specified {@link ContractState} type.
*
* @param <T> The underlying {@link ContractState} type.
* @param <T> 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.
*/
Expand All @@ -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 <T> The underlying {@link ContractState} type.
* @param <T> The underlying {@link ContractState} type.
* @param stateRef The {@link StateRef} instances to resolve.
* @return Returns a {@link StateAndRef} of the specified {@link ContractState} type.
*/
Expand Down Expand Up @@ -92,7 +94,7 @@ public interface UtxoLedgerService {
* Only use this method if subclasses of {@code type} must be returned.
* <p>
* Use {@link #findUnconsumedStatesByExactType(Class<T>)} to return exact instances of the input {@code type}.
* This method is more performant than {@link #findUnconsumedStatesByType(Class<T>)}.
* This method is more performant than {@link #findUnconsumedStatesByExactType(Class, Integer, Instant)}.
* <p>
* Use {@link #query(String, Class)} for a more performant method of retrieving subclasses of a specified type.
*
Expand All @@ -106,14 +108,46 @@ public interface UtxoLedgerService {

/**
* Finds unconsumed states of the specified {@link ContractState} type in the vault.
* <p>
* This version supports paging, limiting the number of results returned in a single query call by setting the
* `limit` argument.
* <p>
* Example usage:
* <ul>
* <li>Kotlin:<pre>{@code
* val resultSet = utxoLedgerService.findUnconsumedStatesByExactType(MyState::class.java, 10, Instant.now())
*
* @param <T> 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)
* }
* }</pre></li>
* <li>Java:<pre>{@code
* PagedQuery.ResultSet<StateAndRef<MyState>> resultSet = utxoLedgerService.query(MyState.class, 10, Instant.now())
*
* processResultsWithApplicationLogic(resultSet.getResults());
*
* while (resultSet.hasNext()) {
* List<Integer> results = resultSet.next();
* processResultsWithApplicationLogic(results);
* }
* }</pre></li>
*
* @param <T> 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
<T extends ContractState> List<StateAndRef<T>> findUnconsumedStatesByExactType(@NotNull Class<T> type);
<T extends ContractState> ResultSet<StateAndRef<T>> findUnconsumedStatesByExactType(
@NotNull Class<T> type,
@NotNull Integer limit,
@NotNull Instant createdTimestampLimit
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Strictly speaking, this is a change beyond what is claimed by this PR. If we want to add this, then the PR title / description should reflect this as well.

Do we actually have a use-case for this? If the intent is just to limit it to what exists at the start of the query, then this could just be done internally. Or we could actually just allow it to get the latest results until it runs out of results to return, and not set any limit.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It keeps its functionality in line with the vault named query functionality. I think it makes sense to restrict it in the same way we do there, especially since the underlying mechanism is the same between them. We can do it internally if we wanted to, but either way it needs setting whether publicly or internally.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, then the question is whether we want to force users to have to provide it, or we provide another overload / a default argument that just sets it to now?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't like the fact users have to provide a timestamp on this API - there should at least be an override that defaults to now().

);

/**
* Verifies, signs, collects signatures, records and broadcasts a {@link UtxoSignedTransaction} to participants and observers.
Expand Down Expand Up @@ -174,8 +208,7 @@ FinalizationResult receiveFinality(
* }</pre>
*
* @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
Expand Down Expand Up @@ -203,8 +236,9 @@ UtxoTransactionBuilder receiveTransactionBuilder(
* which tracks the differences internally.
* If it is called with anything else, it throws InvalidParameterException.
* <p>
*
* @param transactionBuilder The {@link UtxoTransactionBuilder} to send.
* @param session The receiver {@link FlowSession}.
* @param session The receiver {@link FlowSession}.
*/
@Suspendable
void sendUpdatedTransactionBuilder(
Expand Down Expand Up @@ -260,15 +294,14 @@ void sendUpdatedTransactionBuilder(
* }
* }</pre></li>
*
* @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 <R> VaultNamedParameterizedQuery<R> query(@NotNull String queryName, @NotNull Class<R> resultClass);
@NotNull
<R> VaultNamedParameterizedQuery<R> query(@NotNull String queryName, @NotNull Class<R> resultClass);
}