VaultService
Keywords: net.corda.core.node.services.VaultService interface
Date: 2023-09-18

net.corda.core.node.services

## Interface VaultService

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

  See Also:
    `interface VaultService`

- - ### Constructor Detail

    - #### VaultService

          public VaultService()

  - ### Method Detail

    - #### getRawUpdates

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

      See Also:
        `updates`, `class Vault`, Thread, `class Vault`

    - #### getUpdates

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

      See Also:
        `class Vault`

    - #### whenConsumed

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

      See Also:
        `interface CordaFuture`, `class StateRef`

    - #### addNoteToTransaction

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

      See Also:
        `class LedgerTransaction`, `class SecureHash`, `class LedgerTransaction`

    - #### getTransactionNotes

          @NotNull
          java.lang.Iterable<java.lang.String> getTransactionNotes(@NotNull
                                                                            SecureHash txnId)

    - #### softLockReserve

          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.

      Throws:
        `StatesNotAvailableException` - when not possible to soft-lock all of requested `class StateRef`.
      See Also:
        `class StateRef`, UUID, `FlowLogic.runId`, UUID, UUID, `annotationclass CordaService`

    - #### softLockRelease

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

      See Also:
        `class StateRef`, UUID, `class Vault`

    - #### tryLockFungibleStatesForSpending

          @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 `net.corda.finance.workflows.asset.selection.AbstractCashSelection.unconsumedCashStatesForSpending`. However, this is fully generic and can operate with custom `interface FungibleState` and `interface FungibleAsset` states.

      Parameters:
        `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 the`contractStateType`. 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 Amount>> and Amount<>. Amount>> isautomatically unwrapped to Amount<>.
        `contractStateType` - class type of the result set.
      Returns:
        Returns a locked subset of the `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.
      See Also:
        `net.corda.finance.workflows.asset.selection.AbstractCashSelection.unconsumedCashStatesForSpending`, `interface FungibleState`, `interface FungibleAsset`

    - #### _queryBy

          @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:

      1. states as a List of (page number and size defined by `class PageSpecification`)

      2. states metadata as a List of `class Vault.StateMetadata` held in the Vault States table.

      3. total number of results available if `class PageSpecification` supplied (otherwise returns -1).

      4. status types used in this query: StateStatus.UNCONSUMED, StateStatus.CONSUMED, StateStatus.ALL.

      5. other results (aggregate functions with/without using value groups).

      Throws:
        `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`.

      See Also:
        `class QueryCriteria`, `class PageSpecification`, `class Sort`, `class Vault.Page`, `class PageSpecification`, `class Vault.StateMetadata`, `class PageSpecification`

    - #### _trackBy

          @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:

      1. a snapshot as a `class Vault.Page` (described previously in `queryBy`).

      2. an Observable of `class Vault.Update`.

      Throws:
        `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.

      See Also:
        `class QueryCriteria`, `class PageSpecification`, `class Sort`, `class DataFeed`, `class Vault.Page`, `queryBy`, `class Vault.Update`

    - #### queryBy

          @NotNull
          <T extends ContractState> net.corda.core.node.services.Vault.Page<T> queryBy(@NotNull
                                                                                                java.lang.Class<? extends T> contractStateType)

    - #### queryBy

          @NotNull
          <T extends ContractState> net.corda.core.node.services.Vault.Page<T> queryBy(@NotNull
                                                                                                java.lang.Class<? extends T> contractStateType,
                                                                                                @NotNull
                                                                                                QueryCriteria criteria)

    - #### queryBy

          @NotNull
          <T extends ContractState> net.corda.core.node.services.Vault.Page<T> queryBy(@NotNull
                                                                                                java.lang.Class<? extends T> contractStateType,
                                                                                                @NotNull
                                                                                                PageSpecification paging)

    - #### queryBy

          @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)

    - #### queryBy

          @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)

    - #### queryBy

          @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)

    - #### trackBy

          @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)

    - #### trackBy

          @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)

    - #### trackBy

          @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)

    - #### trackBy

          @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)

    - #### trackBy

          @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)

    - #### trackBy

          @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)