@DoNotImplement public VaultService
A interface VaultService is responsible for securely and safely persisting the current state of a vault to storage. The
vault service vends immutable snapshots of the current vault for working with: if you build a transaction based
on a vault that isn't current, be aware that it may end up being invalid if the states that were used have been
consumed by someone else first!
Note that transactions we've seen are held by the storage service, not the vault.
interface VaultService@NotNull rx.Observable<net.corda.core.node.services.Vault.Update> getRawUpdates()
Prefer the use of updates unless you know why you want to use this instead.
Get a synchronous Observable of updates. When observations are pushed to the Observer, the class Vault will already
incorporate the update, and the database transaction associated with the update will still be open and current.
If for some reason the processing crosses outside of the database transaction (for example, the update is pushed
outside the current JVM or across to another Thread, which is executing in a different database transaction),
then the class Vault may not incorporate the update due to racing with committing the current database transaction.
updates,
class Vault,
Thread,
class Vault@NotNull rx.Observable<net.corda.core.node.services.Vault.Update> getUpdates()
Get a synchronous Observable of updates. When observations are pushed to the Observer, the class Vault will
already incorporate the update and the database transaction associated with the update will have been committed
and closed.
class Vault@NotNull CordaFuture<net.corda.core.node.services.Vault.Update> whenConsumed(@NotNull StateRef ref)
Provide a interface CordaFuture for when a class StateRef is consumed, which can be very useful in building tests.
interface CordaFuture,
class StateRefvoid addNoteToTransaction(@NotNull
SecureHash txnId,
@NotNull
java.lang.String noteText)
Add a note to an existing class LedgerTransaction given by its unique class SecureHash id.
Multiple notes may be attached to the same class LedgerTransaction.
These are additively and immutably persisted within the node local vault database in a single textual field.
using a semi-colon separator.
@NotNull
java.lang.Iterable<java.lang.String> getTransactionNotes(@NotNull
SecureHash txnId)
void softLockReserve(@NotNull
java.util.UUID lockId,
@NotNull
NonEmptySet<net.corda.core.contracts.StateRef> stateRefs)
Reserve a set of class StateRef for a given UUID unique identifier.
Typically, the unique identifier will refer to a FlowLogic.runId's UUID associated with an in-flight flow.
In this case if the flow terminates the locks will automatically be freed, even if there is an error.
However, the user can specify their own UUID and manage this manually, possibly across the lifetime of multiple
flows, or from other thread contexts e.g. annotationclass CordaService instances.
In the case of coin selection, soft locks are automatically taken upon gathering relevant unconsumed input refs.
StatesNotAvailableException - when not possible to soft-lock all of requested class StateRef.class StateRef,
UUID,
FlowLogic.runId,
UUID,
UUID,
annotationclass CordaServicevoid softLockRelease(@NotNull
java.util.UUID lockId,
@Nullable
NonEmptySet<net.corda.core.contracts.StateRef> stateRefs)
Release all or an explicitly specified set of class StateRef for a given UUID unique identifier.
A class Vault soft-lock manager is automatically notified from flows that are terminated, such that any soft locked
states may be released.
In the case of coin selection, soft-locks are automatically released once previously gathered unconsumed
input refs are consumed as part of cash spending.
class StateRef,
UUID,
class Vault@Suspendable @NotNull <T extends FungibleState<?>> java.util.List<net.corda.core.contracts.StateAndRef> tryLockFungibleStatesForSpending(@NotNull java.util.UUID lockId, @NotNull QueryCriteria eligibleStatesQuery, @NotNull Amount<?> amount, @NotNull java.lang.Class<? extends T> contractStateType)
Helper function to determine spendable states and soft locking them.
Currently performance will be worse than for the hand optimised version in
Cash.unconsumedCashStatesForSpending. However, this is fully generic and can operate with custom interface FungibleState
and interface FungibleAsset states.
lockId - The FlowLogic.runId's UUID of the current flow used to soft lock the states.eligibleStatesQuery - A custom query object that selects down to the appropriate subset of all states of thecontractStateType. e.g. by selecting on account, issuer, etc. The query is internally augmented with theStateStatus.UNCONSUMED, soft lock and contract type requirements.amount - The required amount of the asset. It is assumed that compatible issuer states will be filtered outby the eligibleStatesQuery. This method accepts both AmountcontractStateType - class type of the result set.eligibleStatesQuery sufficient to satisfy the requested amount,
or else an empty list and no change in the stored lock states when their are insufficient resources available.interface FungibleState,
interface FungibleAsset@NotNull <T extends ContractState> net.corda.core.node.services.Vault.Page<T> _queryBy(@NotNull QueryCriteria criteria, @NotNull PageSpecification paging, @NotNull Sort sorting, @NotNull java.lang.Class<? extends T> contractStateType)
Generic vault query function which takes a class QueryCriteria object to define filters,
optional class PageSpecification and optional class Sort modification criteria (default unsorted),
and returns a class Vault.Page object containing the following:
states as a List of (page number and size defined by class PageSpecification)
states metadata as a List of class Vault.StateMetadata held in the Vault States table.
total number of results available if class PageSpecification supplied (otherwise returns -1).
status types used in this query: StateStatus.UNCONSUMED, StateStatus.CONSUMED, StateStatus.ALL.
other results (aggregate functions with/without using value groups).
VaultQueryException - if the query cannot be executed for any reason (missing criteria or parsing error, paging errors, unsupported query, underlying database error).
Notes
If no class PageSpecification is provided, a maximum of DEFAULT_PAGE_SIZE results will be returned.
API users must specify a class PageSpecification if they are expecting more than DEFAULT_PAGE_SIZE results,
otherwise a exception VaultQueryException will be thrown alerting to this condition.
It is the responsibility of the API user to request further pages and/or specify a more suitable class PageSpecification.
class QueryCriteria,
class PageSpecification,
class Sort,
class Vault.Page,
class PageSpecification,
class Vault.StateMetadata,
class PageSpecification@NotNull <T extends ContractState> DataFeed<net.corda.core.node.services.Vault.Page,net.corda.core.node.services.Vault.Update> _trackBy(@NotNull QueryCriteria criteria, @NotNull PageSpecification paging, @NotNull Sort sorting, @NotNull java.lang.Class<? extends T> contractStateType)
Generic vault query function which takes a class QueryCriteria object to define filters,
optional class PageSpecification and optional class Sort modification criteria (default unsorted),
and returns a class DataFeed object containing:
a snapshot as a class Vault.Page (described previously in queryBy).
an Observable of class Vault.Update.
VaultQueryException - if the query cannot be executed for any reason.
Notes:
- The snapshot part of the query adheres to the same behaviour as the queryBy function.
- The update part of the query currently only supports query criteria filtering by contract
type(s) and state status(es). CID-731 <> proposes
adding the complete set of class QueryCriteria filtering.
class QueryCriteria,
class PageSpecification,
class Sort,
class DataFeed,
class Vault.Page,
queryBy,
class Vault.Update@NotNull <T extends ContractState> net.corda.core.node.services.Vault.Page<T> queryBy(@NotNull java.lang.Class<? extends T> contractStateType)
@NotNull <T extends ContractState> net.corda.core.node.services.Vault.Page<T> queryBy(@NotNull java.lang.Class<? extends T> contractStateType, @NotNull QueryCriteria criteria)
@NotNull <T extends ContractState> net.corda.core.node.services.Vault.Page<T> queryBy(@NotNull java.lang.Class<? extends T> contractStateType, @NotNull PageSpecification paging)
@NotNull <T extends ContractState> net.corda.core.node.services.Vault.Page<T> queryBy(@NotNull java.lang.Class<? extends T> contractStateType, @NotNull QueryCriteria criteria, @NotNull PageSpecification paging)
@NotNull <T extends ContractState> net.corda.core.node.services.Vault.Page<T> queryBy(@NotNull java.lang.Class<? extends T> contractStateType, @NotNull QueryCriteria criteria, @NotNull Sort sorting)
@NotNull <T extends ContractState> net.corda.core.node.services.Vault.Page<T> queryBy(@NotNull java.lang.Class<? extends T> contractStateType, @NotNull QueryCriteria criteria, @NotNull PageSpecification paging, @NotNull Sort sorting)
@NotNull <T extends ContractState> DataFeed<net.corda.core.node.services.Vault.Page,net.corda.core.node.services.Vault.Update> trackBy(@NotNull java.lang.Class<? extends T> contractStateType)
@NotNull <T extends ContractState> DataFeed<net.corda.core.node.services.Vault.Page,net.corda.core.node.services.Vault.Update> trackBy(@NotNull java.lang.Class<? extends T> contractStateType, @NotNull QueryCriteria criteria)
@NotNull <T extends ContractState> DataFeed<net.corda.core.node.services.Vault.Page,net.corda.core.node.services.Vault.Update> trackBy(@NotNull java.lang.Class<? extends T> contractStateType, @NotNull PageSpecification paging)
@NotNull <T extends ContractState> DataFeed<net.corda.core.node.services.Vault.Page,net.corda.core.node.services.Vault.Update> trackBy(@NotNull java.lang.Class<? extends T> contractStateType, @NotNull QueryCriteria criteria, @NotNull PageSpecification paging)
@NotNull <T extends ContractState> DataFeed<net.corda.core.node.services.Vault.Page,net.corda.core.node.services.Vault.Update> trackBy(@NotNull java.lang.Class<? extends T> contractStateType, @NotNull QueryCriteria criteria, @NotNull Sort sorting)
@NotNull <T extends ContractState> DataFeed<net.corda.core.node.services.Vault.Page,net.corda.core.node.services.Vault.Update> trackBy(@NotNull java.lang.Class<? extends T> contractStateType, @NotNull QueryCriteria criteria, @NotNull PageSpecification paging, @NotNull Sort sorting)