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 class DataFeed object containing: |
void |
addNoteToTransaction(SecureHash txnId,
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. |
NonExistentClass |
getRawUpdates()
Prefer the use of
VaultService.getUpdates unless you know why you want to use this instead. |
java.lang.Iterable<java.lang.String> |
getTransactionNotes(SecureHash txnId) |
NonExistentClass |
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. |
<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,
PageSpecification paging) |
<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 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. |
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.getRunId '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. 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,
PageSpecification paging) |
<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 FungibleState<?>> |
tryLockFungibleStatesForSpending(java.util.UUID lockId,
QueryCriteria eligibleStatesQuery,
Amount<?> 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 FungibleState
and 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. |
NonExistentClass getRawUpdates()
Prefer the use of VaultService.getUpdates
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.
VaultService.getUpdates
,
Observable,
class Vault
,
Thread,
class Vault
NonExistentClass 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
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 StateRef
void addNoteToTransaction(SecureHash txnId, 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.
java.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.getRunId
'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. interface CordaService
instances.
In the case of coin selection, soft locks are automatically taken upon gathering relevant unconsumed input refs.
class StateRef
.class StateRef
,
UUID,
FlowLogic.getRunId
,
UUID,
UUID,
interface CordaService
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 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
<T extends FungibleState<?>> java.util.List<net.corda.core.contracts.StateAndRef> tryLockFungibleStatesForSpending(java.util.UUID lockId, QueryCriteria eligibleStatesQuery, Amount<?> 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 FungibleState
and interface FungibleAsset
states.
lockId
- The FlowLogic.getRunId
'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 the
contractStateType. e.g. by selecting on account, issuer, etc. The query is internally augmented with the
StateStatus.UNCONSUMED, soft lock and contract type requirements.amount
- The required amount of the asset. It is assumed that compatible issuer states will be filtered out
by the eligibleStatesQuery. This method accepts both AmountcontractStateType
- class type of the result set.interface FungibleState
,
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: StateStatus.UNCONSUMED, StateStatus.CONSUMED, StateStatus.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 class DataFeed
object containing:
a snapshot as a class Vault.Page
(described previously in VaultService.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 VaultService.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
,
VaultService.queryBy
,
Observable,
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, PageSpecification paging)
<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, 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, 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)