Interface UtxoLedgerService
-
- All Implemented Interfaces:
@DoNotImplement() public interface UtxoLedgerService
Defines UTXO ledger services.
-
-
Method Summary
Modifier and Type Method Description abstract UtxoTransactionBuilder
createTransactionBuilder()
Gets a UTXO transaction builder. abstract <T extends ContractState> List<StateAndRef<T>>
resolve(@NotNull() Iterable<StateRef> stateRefs)
Resolves the specified StateRef instances into StateAndRef instances of the specified ContractState type. abstract <T extends ContractState> StateAndRef<T>
resolve(@NotNull() StateRef stateRef)
Resolves the specified StateRef instance into a StateAndRef instance of the specified ContractState type. abstract UtxoSignedTransaction
findSignedTransaction(@NotNull() SecureHash id)
Finds a UtxoSignedTransaction in the vault by the specified transaction ID. abstract UtxoLedgerTransaction
findLedgerTransaction(@NotNull() SecureHash id)
Finds a UtxoLedgerTransaction in the vault by the specified transaction ID. abstract UtxoFilteredTransactionBuilder
filterSignedTransaction(@NotNull() UtxoSignedTransaction transaction)
Filters a UtxoSignedTransaction to create a UtxoFilteredTransaction that only contains the components specified by the UtxoFilteredTransactionBuilder output from this method. abstract <T extends ContractState> List<StateAndRef<T>>
findUnconsumedStatesByType(@NotNull() Class<T> type)
Finds unconsumed states that are concrete implementations or subclasses of type
.abstract <T extends ContractState> PagedQuery.ResultSet<StateAndRef<T>>
findUnconsumedStatesByExactType(@NotNull() Class<T> type, @NotNull() Integer limit, @NotNull() Instant createdTimestampLimit)
Finds unconsumed states of the specified ContractState type in the vault. abstract FinalizationResult
finalize(@NotNull() UtxoSignedTransaction transaction, @NotNull() List<FlowSession> sessions)
Verifies, signs, collects signatures, records and broadcasts a UtxoSignedTransaction to participants and observers. abstract FinalizationResult
receiveFinality(@NotNull() FlowSession session, @NotNull() UtxoTransactionValidator validator)
Verifies, signs and records a UtxoSignedTransaction. abstract UtxoTransactionBuilder
sendAndReceiveTransactionBuilder(@NotNull() UtxoTransactionBuilder transactionBuilder, @NotNull() FlowSession session)
Sends a transaction builder to another session, waits for the other side to propose transaction builder components, applies the proposed components to a copy of the original builder, and returns that new builder. abstract UtxoTransactionBuilder
receiveTransactionBuilder(@NotNull() FlowSession session)
Receives a transaction builder from another session. abstract void
sendUpdatedTransactionBuilder(@NotNull() UtxoTransactionBuilder transactionBuilder, @NotNull() FlowSession session)
Sends the difference between the current transaction builder and the originally received one to another session with all dependent back chains. abstract <R> VaultNamedParameterizedQuery<R>
query(@NotNull() String queryName, @NotNull() Class<R> resultClass)
Creates a query object for a vault named query with the given name. -
-
Method Detail
-
createTransactionBuilder
@NotNull()@Suspendable() abstract UtxoTransactionBuilder createTransactionBuilder()
Gets a UTXO transaction builder.
-
resolve
@NotNull()@Suspendable() abstract <T extends ContractState> List<StateAndRef<T>> resolve(@NotNull() Iterable<StateRef> stateRefs)
Resolves the specified StateRef instances into StateAndRef instances of the specified ContractState type.
- Parameters:
stateRefs
- The StateRef instances to resolve.
-
resolve
@NotNull()@Suspendable() abstract <T extends ContractState> StateAndRef<T> resolve(@NotNull() StateRef stateRef)
Resolves the specified StateRef instance into a StateAndRef instance of the specified ContractState type.
- Parameters:
stateRef
- The StateRef instances to resolve.
-
findSignedTransaction
@Nullable()@Suspendable() abstract UtxoSignedTransaction findSignedTransaction(@NotNull() SecureHash id)
Finds a UtxoSignedTransaction in the vault by the specified transaction ID.
- Parameters:
id
- The ID of the UtxoSignedTransaction to find.
-
findLedgerTransaction
@Nullable()@Suspendable() abstract UtxoLedgerTransaction findLedgerTransaction(@NotNull() SecureHash id)
Finds a UtxoLedgerTransaction in the vault by the specified transaction ID.
- Parameters:
id
- The ID of the UtxoLedgerTransaction to find.
-
filterSignedTransaction
@NotNull()@Suspendable() abstract UtxoFilteredTransactionBuilder filterSignedTransaction(@NotNull() UtxoSignedTransaction transaction)
Filters a UtxoSignedTransaction to create a UtxoFilteredTransaction that only contains the components specified by the UtxoFilteredTransactionBuilder output from this method.
- Parameters:
transaction
- The UtxoSignedTransaction to filter.
-
findUnconsumedStatesByType
@Deprecated(since = "5.1", forRemoval = true)@NotNull()@Suspendable() abstract <T extends ContractState> List<StateAndRef<T>> findUnconsumedStatesByType(@NotNull() Class<T> type)
Finds unconsumed states that are concrete implementations or subclasses of
type
.- Parameters:
type
- The ContractState type to find in the vault.
-
findUnconsumedStatesByExactType
@NotNull()@Suspendable() abstract <T extends ContractState> PagedQuery.ResultSet<StateAndRef<T>> findUnconsumedStatesByExactType(@NotNull() Class<T> type, @NotNull() Integer limit, @NotNull() Instant createdTimestampLimit)
Finds unconsumed states of the specified 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:
val resultSet = utxoLedgerService.findUnconsumedStatesByExactType(MyState::class.java, 10, Instant.now()) processResultsWithApplicationLogic(resultSet.results) while (resultSet.hasNext()) { val results = resultSet.next() processResultsWithApplicationLogic(results) }
- Java:
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); }
- Parameters:
type
- The ContractState type to find in the vault.limit
- The size of each page.createdTimestampLimit
- The timestamp limit the underlying query enforces.
- Kotlin:
-
finalize
@NotNull()@Suspendable() abstract FinalizationResult finalize(@NotNull() UtxoSignedTransaction transaction, @NotNull() List<FlowSession> sessions)
Verifies, signs, collects signatures, records and broadcasts a UtxoSignedTransaction to participants and observers.
- Parameters:
transaction
- The UtxoSignedTransaction to verify, finalize and record.sessions
- The FlowSession instances of the participants or observers of the transaction.
-
receiveFinality
@NotNull()@Suspendable() abstract FinalizationResult receiveFinality(@NotNull() FlowSession session, @NotNull() UtxoTransactionValidator validator)
Verifies, signs and records a UtxoSignedTransaction.
This method should be called in response to finalize.
- Parameters:
session
- The FlowSession of the counter-party finalizing the UtxoSignedTransaction.validator
- Validates the received UtxoSignedTransaction.
-
sendAndReceiveTransactionBuilder
@NotNull()@Suspendable() abstract UtxoTransactionBuilder sendAndReceiveTransactionBuilder(@NotNull() UtxoTransactionBuilder transactionBuilder, @NotNull() FlowSession session)
Sends a transaction builder to another session, waits for the other side to propose transaction builder components, applies the proposed components to a copy of the original builder, and returns that new builder.
It supports similar workflows to the following:
Initiator:
val updatedTxBuilder = utxoLedgerService.sendAndReceiveTransactionBuilder(txBuilder, session)
The notary and time window from the proposal will get discarded and the original will be kept if both the original and the proposal have these components set. Duplications of input staterefs, reference staterefs, and signatories will be discarded.
Receiver:
val proposedTxBuilder = utxoLedgerService.receiveTransactionBuilder(session) proposedTxBuilder.add...(...) proposedTxBuilder.add...(...) proposedTxBuilder.add...(...) utxoLedgerService.replyTransactionBuilderProposal(proposedTxBuilder, session)
- Parameters:
transactionBuilder
- The UtxoTransactionBuilder to send.session
- The receiver FlowSession.
-
receiveTransactionBuilder
@NotNull()@Suspendable() abstract UtxoTransactionBuilder receiveTransactionBuilder(@NotNull() FlowSession session)
Receives a transaction builder from another session.
- Parameters:
session
- The FlowSession to receive the UtxoTransactionBuilder from.
-
sendUpdatedTransactionBuilder
@Suspendable() abstract void sendUpdatedTransactionBuilder(@NotNull() UtxoTransactionBuilder transactionBuilder, @NotNull() FlowSession session)
Sends the difference between the current transaction builder and the originally received one to another session with all dependent back chains. It works only with UtxoTransactionBuilders created from receiveTransactionBuilder which tracks the differences internally. If it is called with anything else, it throws InvalidParameterException.
- Parameters:
transactionBuilder
- The UtxoTransactionBuilder to send.session
- The receiver FlowSession.
-
query
@Suspendable()@NotNull() abstract <R> VaultNamedParameterizedQuery<R> query(@NotNull() String queryName, @NotNull() Class<R> resultClass)
Creates a query object for a vault named query with the given name. This query can be executed later by calling execute.
The vault named queries executed by this method must be defined within a VaultNamedQueryFactory.
Example usage:
- Kotlin:
val query = utxoLedgerService.query("FIND_BY_TEST_FIELD", Int::class.java) .setParameter("testField", "value") .setParameter("participants", listOf("something")) .setParameter("contractStateType", ContractState::class.java.name) .setParameter("in-memory-filter-parameter", "parameter") .setCreatedTimestampLimit(Instant.now()) .setOffset(0) .setLimit(100) val resultSet = query.execute() processResultsWithApplicationLogic(resultSet.results) while (resultSet.hasNext()) { val results = resultSet.next() processResultsWithApplicationLogic(results) }
- Java:
ParameterizedQuery<Integer> query = utxoLedgerService.query("FIND_BY_TEST_FIELD", Integer.class) .setParameter("testField", "value") .setParameter("participants", List.of("something")) .setParameter("contractStateType", ContractState.class.getName()) .setParameter("in-memory-filter-parameter", "parameter") .setTimestampLimit(Instant.now()) .setOffset(0) .setLimit(100); PagedQuery.ResultSet<Integer> resultSet = query.execute(); processResultsWithApplicationLogic(resultSet.getResults()); while (resultSet.hasNext()) { List<Integer> results = resultSet.next(); processResultsWithApplicationLogic(results); }
- Parameters:
queryName
- The name of the named ledger query to use.resultClass
- Type that the query should return when executed.
- Kotlin:
-
-
-
-