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| Modifier and Type | Interface and Description |
|---|---|
static class |
VaultService.DefaultImpls
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! |
| Modifier and Type | Method and Description |
|---|---|
<T extends ContractState> |
_queryBy(QueryCriteria criteria,
PageSpecification paging,
Sort sorting,
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: |
<T extends ContractState> |
_trackBy(QueryCriteria criteria,
PageSpecification paging,
Sort sorting,
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 Vault.PageAndUpdates object containing |
void |
addNoteToTransaction(SecureHash txnId,
java.lang.String noteText)
Add a note to an existing LedgerTransaction given by its unique
class SecureHash id
Multiple notes may be attached to the same LedgerTransaction.
These are additively and immutably persisted within the node local vault database in a single textual field
using a semi-colon separator |
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.
|
java.lang.Iterable<java.lang.String> |
getTransactionNotes(SecureHash txnId) |
rx.Observable<net.corda.core.node.services.Vault.Update> |
getUpdates()
Get a synchronous Observable of updates. When observations are pushed to the Observer, the Vault will already incorporate
the update, and the database transaction associated with the update will have been committed and closed.
|
<T extends ContractState> |
queryBy(java.lang.Class<? extends T> contractStateType) |
<T extends ContractState> |
queryBy(java.lang.Class<? extends T> contractStateType,
QueryCriteria criteria) |
<T extends ContractState> |
queryBy(java.lang.Class<? extends T> contractStateType,
QueryCriteria criteria,
PageSpecification paging) |
<T extends ContractState> |
queryBy(java.lang.Class<? extends T> contractStateType,
QueryCriteria criteria,
Sort sorting) |
<T extends ContractState> |
queryBy(java.lang.Class<? extends T> contractStateType,
QueryCriteria criteria,
PageSpecification paging,
Sort sorting) |
void |
softLockRelease(java.util.UUID lockId,
NonEmptySet<net.corda.core.contracts.StateRef> stateRefs)
Release all or an explicitly specified set of
class StateRef for a given UUID unique identifier.
A vault soft lock manager is automatically notified of a Flows that are terminated, such that any soft locked states
may be released.
In the case of coin selection, softLock are automatically released once previously gathered unconsumed input refs
are consumed as part of cash spending. |
void |
softLockReserve(java.util.UUID lockId,
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.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. interface CordaService instances.
In the case of coin selection, soft locks are automatically taken upon gathering relevant unconsumed input refs. |
<T extends ContractState> |
trackBy(java.lang.Class<? extends T> contractStateType) |
<T extends ContractState> |
trackBy(java.lang.Class<? extends T> contractStateType,
QueryCriteria criteria) |
<T extends ContractState> |
trackBy(java.lang.Class<? extends T> contractStateType,
QueryCriteria criteria,
PageSpecification paging) |
<T extends ContractState> |
trackBy(java.lang.Class<? extends T> contractStateType,
QueryCriteria criteria,
Sort sorting) |
<T extends ContractState> |
trackBy(java.lang.Class<? extends T> contractStateType,
QueryCriteria criteria,
PageSpecification paging,
Sort sorting) |
<T extends FungibleAsset<U>,U> |
tryLockFungibleStatesForSpending(java.util.UUID lockId,
QueryCriteria eligibleStatesQuery,
Amount<U> amount,
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 FungibleAsset states. |
CordaFuture<net.corda.core.node.services.Vault.Update> |
whenConsumed(StateRef ref)
Provide a
interface CordaFuture for when a class StateRef is consumed, which can be very useful in building tests. |
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 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 Vault may not incorporate the update due to racing with committing the current database transaction.
rx.Observable<net.corda.core.node.services.Vault.Update> getUpdates()
Get a synchronous Observable of updates. When observations are pushed to the Observer, the Vault will already incorporate the update, and the database transaction associated with the update will have been committed and closed.
CordaFuture<net.corda.core.node.services.Vault.Update> whenConsumed(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(SecureHash txnId, java.lang.String noteText)
Add a note to an existing LedgerTransaction given by its unique class SecureHash id
Multiple notes may be attached to the same LedgerTransaction.
These are additively and immutably persisted within the node local vault database in a single textual field
using a semi-colon separator
class SecureHash,
LedgerTransactionjava.lang.Iterable<java.lang.String> getTransactionNotes(SecureHash txnId)
void softLockReserve(java.util.UUID lockId,
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.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. interface CordaService instances.
In the case of coin selection, soft locks are automatically taken upon gathering relevant unconsumed input refs.
class StateRefclass StateRef,
FlowLogic.runId.uuid,
interface CordaServicevoid softLockRelease(java.util.UUID lockId,
NonEmptySet<net.corda.core.contracts.StateRef> stateRefs)
Release all or an explicitly specified set of class StateRef for a given UUID unique identifier.
A vault soft lock manager is automatically notified of a Flows that are terminated, such that any soft locked states
may be released.
In the case of coin selection, softLock are automatically released once previously gathered unconsumed input refs
are consumed as part of cash spending.
class StateRef<T extends FungibleAsset<U>,U> java.util.List<net.corda.core.contracts.StateAndRef> tryLockFungibleStatesForSpending(java.util.UUID lockId, QueryCriteria eligibleStatesQuery, Amount<U> amount, 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 FungibleAsset states.
lockId - The FlowLogic.runId.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 the
contractStateType. e.g. by selecting on account, issuer, etc. The query is internally augmented with the UNCONSUMED,
soft lock and contract type requirements.amount - The required amount of the asset, but with the issuer stripped off.
It is assumed that compatible issuer states will be filtered out by the eligibleStatesQuery.contractStateType - class type of the result set.interface FungibleAsset<T extends ContractState> Vault.Page<T> _queryBy(QueryCriteria criteria, PageSpecification paging, Sort sorting, 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: UNCONSUMED, CONSUMED, ALL
other results (aggregate functions with/without using value groups)
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<T extends ContractState> DataFeed<net.corda.core.node.services.Vault.Page,net.corda.core.node.services.Vault.Update> _trackBy(QueryCriteria criteria, PageSpecification paging, Sort sorting, 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 Vault.PageAndUpdates object containing
a snapshot as a class Vault.Page (described previously in queryBy)
an Observable of class Vault.Update
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 class QueryCriteria applies to both snapshot and deltas (streaming updates).
class QueryCriteria,
class PageSpecification,
class Sort,
Vault.PageAndUpdates,
class Vault.Page,
class Vault.Update<T extends ContractState> Vault.Page<T> queryBy(java.lang.Class<? extends T> contractStateType)
<T extends ContractState> Vault.Page<T> queryBy(java.lang.Class<? extends T> contractStateType, QueryCriteria criteria)
<T extends ContractState> Vault.Page<T> queryBy(java.lang.Class<? extends T> contractStateType, QueryCriteria criteria, PageSpecification paging)
<T extends ContractState> Vault.Page<T> queryBy(java.lang.Class<? extends T> contractStateType, QueryCriteria criteria, Sort sorting)
<T extends ContractState> Vault.Page<T> queryBy(java.lang.Class<? extends T> contractStateType, QueryCriteria criteria, PageSpecification paging, Sort sorting)
<T extends ContractState> DataFeed<net.corda.core.node.services.Vault.Page,net.corda.core.node.services.Vault.Update> trackBy(java.lang.Class<? extends T> contractStateType)
<T extends ContractState> DataFeed<net.corda.core.node.services.Vault.Page,net.corda.core.node.services.Vault.Update> trackBy(java.lang.Class<? extends T> contractStateType, QueryCriteria criteria)
<T extends ContractState> DataFeed<net.corda.core.node.services.Vault.Page,net.corda.core.node.services.Vault.Update> trackBy(java.lang.Class<? extends T> contractStateType, QueryCriteria criteria, PageSpecification paging)
<T extends ContractState> DataFeed<net.corda.core.node.services.Vault.Page,net.corda.core.node.services.Vault.Update> trackBy(java.lang.Class<? extends T> contractStateType, QueryCriteria criteria, Sort sorting)
<T extends ContractState> DataFeed<net.corda.core.node.services.Vault.Page,net.corda.core.node.services.Vault.Update> trackBy(java.lang.Class<? extends T> contractStateType, QueryCriteria criteria, PageSpecification paging, Sort sorting)