VaultService - corda

corda / net.corda.core.node.services / VaultService

# VaultService

`@DoNotImplement interface VaultService`

A 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.

### Properties

#### rawUpdates | Prefer the use of updates unless you know why you want to use this instead. `abstract val rawUpdates: Observable<Update<ContractState>>`
#### updates | 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. `abstract val updates: Observable<Update<ContractState>>`

### Functions

#### _queryBy | Generic vault query function which takes a QueryCriteria object to define filters, optional PageSpecification and optional Sort modification criteria (default unsorted), and returns a Vault.Page object containing the following: `abstract fun <T : ContractState> _queryBy(criteria: QueryCriteria, paging: PageSpecification, sorting: Sort, contractStateType: Class<out T>): Page<T>`
#### _trackBy | Generic vault query function which takes a QueryCriteria object to define filters, optional PageSpecification and optional Sort modification criteria (default unsorted), and returns a DataFeed object containing: `abstract fun <T : ContractState> _trackBy(criteria: QueryCriteria, paging: PageSpecification, sorting: Sort, contractStateType: Class<out T>): DataFeed<Page<T>, Update<T>>`
#### addNoteToTransaction | Add a note to an existing LedgerTransaction given by its unique 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. `abstract fun addNoteToTransaction(txnId: SecureHash, noteText: String): Unit`
#### getTransactionNotes | `abstract fun getTransactionNotes(txnId: SecureHash): Iterable<String>`
#### queryBy | `open fun <T : ContractState> queryBy(contractStateType: Class<out T>): Page<T>` `open fun <T : ContractState> queryBy(contractStateType: Class<out T>, criteria: QueryCriteria): Page<T>` `open fun <T : ContractState> queryBy(contractStateType: Class<out T>, paging: PageSpecification): Page<T>` `open fun <T : ContractState> queryBy(contractStateType: Class<out T>, criteria: QueryCriteria, paging: PageSpecification): Page<T>` `open fun <T : ContractState> queryBy(contractStateType: Class<out T>, criteria: QueryCriteria, sorting: Sort): Page<T>` `open fun <T : ContractState> queryBy(contractStateType: Class<out T>, criteria: QueryCriteria, paging: PageSpecification, sorting: Sort): Page<T>`
#### softLockRelease | Release all or an explicitly specified set of StateRef for a given UUID unique identifier. A 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. `abstract fun softLockRelease(lockId: UUID, stateRefs: NonEmptySet<StateRef>? = null): Unit`
#### softLockReserve | Reserve a set of 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. CordaService instances. In the case of coin selection, soft locks are automatically taken upon gathering relevant unconsumed input refs. `abstract fun softLockReserve(lockId: UUID, stateRefs: NonEmptySet<StateRef>): Unit`
#### trackBy | `open fun <T : ContractState> trackBy(contractStateType: Class<out T>): DataFeed<Page<T>, Update<T>>` `open fun <T : ContractState> trackBy(contractStateType: Class<out T>, criteria: QueryCriteria): DataFeed<Page<T>, Update<T>>` `open fun <T : ContractState> trackBy(contractStateType: Class<out T>, paging: PageSpecification): DataFeed<Page<T>, Update<T>>` `open fun <T : ContractState> trackBy(contractStateType: Class<out T>, criteria: QueryCriteria, paging: PageSpecification): DataFeed<Page<T>, Update<T>>` `open fun <T : ContractState> trackBy(contractStateType: Class<out T>, criteria: QueryCriteria, sorting: Sort): DataFeed<Page<T>, Update<T>>` `open fun <T : ContractState> trackBy(contractStateType: Class<out T>, criteria: QueryCriteria, paging: PageSpecification, sorting: Sort): DataFeed<Page<T>, Update<T>>`
#### tryLockFungibleStatesForSpending | Helper function to determine spendable states and soft locking them. Currently performance will be worse than for the hand optimised version in net.corda.finance.workflows.asset.selection.AbstractCashSelection.unconsumedCashStatesForSpending. However, this is fully generic and can operate with custom FungibleState and FungibleAsset states. `abstract fun <T : FungibleState<*>> tryLockFungibleStatesForSpending(lockId: UUID, eligibleStatesQuery: QueryCriteria, amount: Amount<*>, contractStateType: Class<out T>): List<StateAndRef<T>>`
#### whenConsumed | Provide a CordaFuture for when a StateRef is consumed, which can be very useful in building tests. `open fun whenConsumed(ref: StateRef): CordaFuture<Update<ContractState>>`

### Extension Functions

#### queryBy | `fun <T : ContractState> VaultService.queryBy(): Page<T>` `fun <T : ContractState> VaultService.queryBy(criteria: QueryCriteria): Page<T>` `fun <T : ContractState> VaultService.queryBy(paging: PageSpecification): Page<T>` `fun <T : ContractState> VaultService.queryBy(criteria: QueryCriteria, paging: PageSpecification): Page<T>` `fun <T : ContractState> VaultService.queryBy(criteria: QueryCriteria, sorting: Sort): Page<T>` `fun <T : ContractState> VaultService.queryBy(criteria: QueryCriteria, paging: PageSpecification, sorting: Sort): Page<T>`
#### trackBy | `fun <T : ContractState> VaultService.trackBy(): DataFeed<Page<T>, Update<T>>` `fun <T : ContractState> VaultService.trackBy(paging: PageSpecification): DataFeed<Page<T>, Update<T>>` `fun <T : ContractState> VaultService.trackBy(criteria: QueryCriteria): DataFeed<Page<T>, Update<T>>` `fun <T : ContractState> VaultService.trackBy(criteria: QueryCriteria, paging: PageSpecification): DataFeed<Page<T>, Update<T>>` `fun <T : ContractState> VaultService.trackBy(criteria: QueryCriteria, sorting: Sort): DataFeed<Page<T>, Update<T>>` `fun <T : ContractState> VaultService.trackBy(criteria: QueryCriteria, paging: PageSpecification, sorting: Sort): DataFeed<Page<T>, Update<T>>`