CordaRPCOps
Keywords: net.corda.core.messaging.CordaRPCOps interface
Date: 2023-09-18

net.corda.core.messaging

## Interface CordaRPCOps

- All Superinterfaces:
    RPCOps

      public CordaRPCOps
      extends RPCOps

  RPC operations that the node exposes to clients.

- - ### Constructor Detail

    - #### CordaRPCOps

          public CordaRPCOps()

  - ### Method Detail

    - #### stateMachinesSnapshot

          @NotNull
          java.util.List<net.corda.core.messaging.StateMachineInfo> stateMachinesSnapshot()

      Returns a list of currently in-progress state machine infos.

    - #### stateMachinesFeed

          @RPCReturnsObservables
           @NotNull
          DataFeed<java.util.List,net.corda.core.messaging.StateMachineUpdate> stateMachinesFeed()

      Returns a data feed of currently in-progress state machine infos and an observable of future state machine adds/removes.

    - #### vaultQueryBy

          @RPCReturnsObservables
           @NotNull
          <T extends ContractState> net.corda.core.node.services.Vault.Page<T> vaultQueryBy(@NotNull
                                                                                                                             QueryCriteria criteria,
                                                                                                                             @NotNull
                                                                                                                             PageSpecification paging,
                                                                                                                             @NotNull
                                                                                                                             Sort sorting,
                                                                                                                             @NotNull
                                                                                                                             java.lang.Class<? extends T> contractStateType)

      Returns a snapshot of vault states for a given query criteria (and optional order and paging specification)

      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: UNCONSUMED, CONSUMED, 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`

    - #### vaultQuery

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

    - #### vaultQueryByCriteria

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

    - #### vaultQueryByWithPagingSpec

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

    - #### vaultQueryByWithSorting

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

    - #### vaultTrackBy

          @RPCReturnsObservables
           @NotNull
          <T extends ContractState> DataFeed<net.corda.core.node.services.Vault.Page,net.corda.core.node.services.Vault.Update> vaultTrackBy(@NotNull
                                                                                                                                                                              QueryCriteria criteria,
                                                                                                                                                                              @NotNull
                                                                                                                                                                              PageSpecification paging,
                                                                                                                                                                              @NotNull
                                                                                                                                                                              Sort sorting,
                                                                                                                                                                              @NotNull
                                                                                                                                                                              java.lang.Class<? extends T> contractStateType)

      Returns a snapshot (as per queryBy) and an observable of future updates to the vault for the given query criteria.

      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 `CordaRPCOps.vaultQueryBy`)

      2. an Observable of `class Vault.Update`

      Notes: the snapshot part of the query adheres to the same behaviour as the `CordaRPCOps.vaultQueryBy` function. the `class QueryCriteria` applies to both snapshot and deltas (streaming updates).

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

    - #### vaultTrack

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

    - #### vaultTrackByCriteria

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

    - #### vaultTrackByWithPagingSpec

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

    - #### vaultTrackByWithSorting

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

    - #### stateMachineRecordedTransactionMappingSnapshot

          @NotNull
          java.util.List<net.corda.core.messaging.StateMachineTransactionMapping> stateMachineRecordedTransactionMappingSnapshot()

      Returns a snapshot list of existing state machine id - recorded transaction hash mappings.

    - #### stateMachineRecordedTransactionMappingFeed

          @RPCReturnsObservables
           @NotNull
          DataFeed<java.util.List,net.corda.core.messaging.StateMachineTransactionMapping> stateMachineRecordedTransactionMappingFeed()

      Returns a snapshot list of existing state machine id - recorded transaction hash mappings, and a stream of future such mappings as well.

    - #### networkMapSnapshot

          @NotNull
          java.util.List<net.corda.core.node.NodeInfo> networkMapSnapshot()

      Returns all parties currently visible on the network with their advertised services.

    - #### networkMapFeed

          @RPCReturnsObservables
           @NotNull
          DataFeed<java.util.List,net.corda.core.node.services.NetworkMapCache.MapChange> networkMapFeed()

      Returns all parties currently visible on the network with their advertised services and an observable of future updates to the network.

    - #### getNetworkParameters

          @NotNull
          NetworkParameters getNetworkParameters()

      Returns the network parameters the node is operating under.

    - #### networkParametersFeed

          @RPCReturnsObservables
           @NotNull
          DataFeed<net.corda.core.messaging.ParametersUpdateInfo,net.corda.core.messaging.ParametersUpdateInfo> networkParametersFeed()

      Returns `class DataFeed` object containing information on currently scheduled parameters update (null if none are currently scheduled) and observable with future update events. Any update that occurs before the deadline automatically cancels the current one. Only the latest update can be accepted. Note: This operation may be restricted only to node administrators.

      See Also:
        `class DataFeed`

    - #### acceptNewNetworkParameters

          void acceptNewNetworkParameters(@NotNull
                                          SecureHash parametersHash)

      Accept network parameters with given hash, hash is obtained through `networkParametersFeed` method. Information is sent back to the zone operator that the node accepted the parameters update - this process cannot be undone. Only parameters that are scheduled for update can be accepted, if different hash is provided this method will fail. Note: This operation may be restricted only to node administrators.

      Parameters:
        `parametersHash` - hash of network parameters to accept
      Throws:
        `IllegalArgumentException` - if network map advertises update with different parameters hash then the one accepted by node's operator.
        `IOException` - if failed to send the approval to network map
      See Also:
        `networkParametersFeed`

    - #### startFlowDynamic

          @RPCReturnsObservables
           @NotNull
          <T> FlowHandle<T> startFlowDynamic(@NotNull
                                                                              java.lang.Class<? extends net.corda.core.flows.FlowLogic<? extends T>> logicType,
                                                                              @NotNull
                                                                              java.lang.Object... args)

      Start the given flow with the given arguments. `logicType` must be annotated with `annotationclass StartableByRPC`.

      See Also:
        `logicType`, `annotationclass StartableByRPC`

    - #### startFlowDynamicWithClientId

          @RPCReturnsObservables
           @NotNull
          <T> FlowHandleWithClientId<T> startFlowDynamicWithClientId(@NotNull
                                                                                                      java.lang.String clientId,
                                                                                                      @NotNull
                                                                                                      java.lang.Class<? extends net.corda.core.flows.FlowLogic<? extends T>> logicType,
                                                                                                      @NotNull
                                                                                                      java.lang.Object... args)

      Start the given flow with the given arguments and a `clientId`.

      The flow's result/ exception will be available for the client to re-connect and retrieve even after the flow's lifetime, by re-calling `startFlowDynamicWithClientId` with the same `clientId`. The `logicType` and `args` will be ignored if the `clientId` matches an existing flow. If you don't have the original values, consider using `reattachFlowWithClientId`.

      Upon calling `removeClientId`, the node's resources holding the result/ exception will be freed and the result/ exception will no longer be available.

      `logicType` must be annotated with `annotationclass StartableByRPC`.

      Parameters:
        `clientId` - The client id to relate the flow to (or is already related to if the flow already exists)
        `logicType` - The `class FlowLogic` to start
        `args` - The arguments to pass to the flow
      See Also:
        `clientId`, `startFlowDynamicWithClientId`, `clientId`, `logicType`, `args`, `clientId`, `reattachFlowWithClientId`, `removeClientId`, `logicType`, `annotationclass StartableByRPC`

    - #### startTrackedFlowDynamic

          @RPCReturnsObservables
           @NotNull
          <T> FlowProgressHandle<T> startTrackedFlowDynamic(@NotNull
                                                                                             java.lang.Class<? extends net.corda.core.flows.FlowLogic<? extends T>> logicType,
                                                                                             @NotNull
                                                                                             java.lang.Object... args)

      Start the given flow with the given arguments, returning an Observable with a single observation of the result of running the flow. `logicType` must be annotated with `annotationclass StartableByRPC`.

      See Also:
        `logicType`, `annotationclass StartableByRPC`

    - #### killFlow

          boolean killFlow(@NotNull
                           StateMachineRunId id)

      Attempts to kill a flow. This is not a clean termination and should be reserved for exceptional cases such as stuck fibers.

      Returns:
        whether the flow existed and was killed.

    - #### reattachFlowWithClientId

          @RPCReturnsObservables
           @Nullable
          <T> FlowHandleWithClientId<T> reattachFlowWithClientId(@NotNull
                                                                                                   java.lang.String clientId)

      Reattach to an existing flow that was started with `startFlowDynamicWithClientId` and has a `clientId`.

      If there is a flow matching the `clientId` then its result or exception is returned.

      When there is no flow matching the `clientId` then null is returned directly (not a future/`interface FlowHandleWithClientId`).

      Calling `reattachFlowWithClientId` after `removeClientId` with the same `clientId` will cause the function to return null as the result/exception of the flow will no longer be available.

      Parameters:
        `clientId` - The client id relating to an existing flow
      See Also:
        `startFlowDynamicWithClientId`, `clientId`, `clientId`, `clientId`, null, `interface FlowHandleWithClientId`, `reattachFlowWithClientId`, `removeClientId`, `clientId`, null

    - #### removeClientId

          boolean removeClientId(@NotNull
                                 java.lang.String clientId)

      Removes a flow's `clientId` to result/ exception mapping. If the mapping is of a running flow, then the mapping will not get removed. This version will only remove flow's that were started by the same user currently calling `removeClientId`.

      See `startFlowDynamicWithClientId` for more information.

      Returns:
        whether the mapping was removed.
      See Also:
        `clientId`, `removeClientId`, `startFlowDynamicWithClientId`

    - #### removeClientIdAsAdmin

          boolean removeClientIdAsAdmin(@NotNull
                                        java.lang.String clientId)

      Removes a flow's `clientId` to result/ exception mapping. If the mapping is of a running flow, then the mapping will not get removed. This version can be called for all client ids, ignoring which user originally started a flow with `clientId`.

      See `startFlowDynamicWithClientId` for more information.

      Returns:
        whether the mapping was removed.
      See Also:
        `clientId`, `clientId`, `startFlowDynamicWithClientId`

    - #### finishedFlowsWithClientIds

          @NotNull
          java.util.Map<java.lang.String,java.lang.Boolean> finishedFlowsWithClientIds()

      Returns all finished flows that were started with a client ID for which the client ID mapping has not been removed. This version only returns the client ids for flows started by the same user currently calling `finishedFlowsWithClientIds`.

      Returns:
        A Map containing client ids for finished flows started by the user calling `finishedFlowsWithClientIds`, mapped to true if finished successfully, false if completed exceptionally.
      See Also:
        `finishedFlowsWithClientIds`

    - #### finishedFlowsWithClientIdsAsAdmin

          @NotNull
          java.util.Map<java.lang.String,java.lang.Boolean> finishedFlowsWithClientIdsAsAdmin()

      Returns all finished flows that were started with a client id by all RPC users for which the client ID mapping has not been removed.

      Returns:
        A Map containing all client ids for finished flows, mapped to true if finished successfully, false if completed exceptionally.

    - #### nodeInfo

          @NotNull
          NodeInfo nodeInfo()

      Returns Node's NodeInfo, assuming this will not change while the node is running.

    - #### nodeDiagnosticInfo

          @NotNull
          NodeDiagnosticInfo nodeDiagnosticInfo()

      Returns Node's NodeDiagnosticInfo, including the version details as well as the information about installed CorDapps.

    - #### notaryIdentities

          @NotNull
          java.util.List<net.corda.core.identity.Party> notaryIdentities()

      Returns network's notary identities, assuming this will not change while the node is running.

      Note that the identities are sorted based on legal name, and the ordering might change once new notaries are introduced.

    - #### addVaultTransactionNote

          void addVaultTransactionNote(@NotNull
                                       SecureHash txnId,
                                       @NotNull
                                       java.lang.String txnNote)

      Add note(s) to an existing Vault transaction.

    - #### getVaultTransactionNotes

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

      Retrieve existing note(s) for a given Vault transaction.

    - #### attachmentExists

          boolean attachmentExists(@NotNull
                                   SecureHash id)

      Checks whether an attachment with the given hash is stored on the node.

    - #### openAttachment

          @NotNull
          java.io.InputStream openAttachment(@NotNull
                                                      SecureHash id)

      Download an attachment JAR by ID.

      Parameters:
        `id` - the id of the attachment to open
      Returns:
        the stream of the JAR
      Throws:
        `RPCException` - if the attachment doesn't exist

    - #### uploadAttachment

          @NotNull
          SecureHash uploadAttachment(@NotNull
                                               java.io.InputStream jar)

      Uploads a jar to the node, returns it's hash.

    - #### uploadAttachmentWithMetadata

          @NotNull
          SecureHash uploadAttachmentWithMetadata(@NotNull
                                                           java.io.InputStream jar,
                                                           @NotNull
                                                           java.lang.String uploader,
                                                           @NotNull
                                                           java.lang.String filename)

      Uploads a jar including metadata to the node, returns it's hash.

    - #### queryAttachments

          @NotNull
          java.util.List<net.corda.core.crypto.SecureHash> queryAttachments(@NotNull
                                                                                     AttachmentQueryCriteria query,
                                                                                     @Nullable
                                                                                     AttachmentSort sorting)

      Queries attachments metadata

    - #### currentNodeTime

          @NotNull
          java.time.Instant currentNodeTime()

      Returns the node's current time.

      Is a quick RPC, meaning that it is handled outside the node's standard thread pool in order to provide a quick response even when the node is dealing with a high volume of RPC calls.

    - #### waitUntilNetworkReady

          @RPCReturnsObservables
           @NotNull
          CordaFuture<java.lang.Void> waitUntilNetworkReady()

      Returns a `interface CordaFuture` which completes when the node has registered wih the network map service. It can also complete with an exception if it is unable to.

      See Also:
        `interface CordaFuture`

    - #### wellKnownPartyFromAnonymous

          @Nullable
          Party wellKnownPartyFromAnonymous(@NotNull
                                                      AbstractParty party)

      Returns the well known identity from an abstract party. This is intended to resolve the well known identity from a confidential identity, however it transparently handles returning the well known identity back if a well known identity is passed in.

      Parameters:
        `party` - identity to determine well known identity for.
      Returns:
        well known identity, if found.

    - #### partyFromKey

          @Nullable
          Party partyFromKey(@NotNull
                                       java.security.PublicKey key)

      Returns the `class Party` corresponding to the given key, if found.

      See Also:
        `class Party`

    - #### wellKnownPartyFromX500Name

          @Nullable
          Party wellKnownPartyFromX500Name(@NotNull
                                                     CordaX500Name x500Name)

      Returns the `class Party` with the X.500 principal as it's Party.name.

      See Also:
        `class Party`

    - #### notaryPartyFromX500Name

          @Nullable
          Party notaryPartyFromX500Name(@NotNull
                                                  CordaX500Name x500Name)

      Get a notary identity by name.

      Returns:
        the notary identity, or null if there is no notary by that name. Note that this will return null if there is a peer with that name but they are not a recognised notary service.

    - #### partiesFromName

          @NotNull
          java.util.Set<net.corda.core.identity.Party> partiesFromName(@NotNull
                                                                                java.lang.String query,
                                                                                boolean exactMatch)

      Returns a list of candidate matches for a given string, with optional fuzzy(ish) matching. Fuzzy matching may get smarter with time e.g. to correct spelling errors, so you should not hard-code indexes into the results but rather show them via a user interface and let the user pick the one they wanted.

      Parameters:
        `query` - The string to check against the X.500 name components
        `exactMatch` - If true, a case sensitive match is done against each component of each X.500 name.

    - #### registeredFlows

          @NotNull
          java.util.List<java.lang.String> registeredFlows()

      Enumerates the class names of the flows that this node knows about.

    - #### nodeInfoFromParty

          @Nullable
          NodeInfo nodeInfoFromParty(@NotNull
                                               AbstractParty party)

      Returns a node's info from the network map cache, where known. Notice that when there are more than one node for a given name (in case of distributed services) first service node found will be returned.

      Returns:
        the node info if available.

    - #### clearNetworkMapCache

          void clearNetworkMapCache()

      Clear all network map data from local node cache. Notice that after invoking this method your node will lose network map data and effectively won't be able to start any flow with the peers until network map is downloaded again on next poll - from `additional-node-infos` directory or from network map server. It depends on the polling interval when it happens. You can also use `refreshNetworkMapCache` to force next fetch from network map server (not from directory - it will happen automatically). If you run local test deployment and want clear view of the network, you may want to clear also `additional-node-infos` directory, because cache can be repopulated from there.

      See Also:
        `refreshNetworkMapCache`

    - #### refreshNetworkMapCache

          void refreshNetworkMapCache()

      Poll network map server if available for the network map. Notice that you need to have `compatibilityZone` or `networkServices` configured. This is normally done automatically on the regular time interval, but you may wish to have the fresh view of network earlier.

    - #### setFlowsDrainingModeEnabled

          void setFlowsDrainingModeEnabled(boolean enabled)

      Sets the value of the node's flows draining mode. If this mode is `enabled`, the node will reject new flows through RPC, ignore scheduled flows, and do not process initial session messages, meaning that P2P counterparties will not be able to initiate new flows involving the node.

      Parameters:
        `enabled` - whether the flows draining mode will be enabled.
      See Also:
        `enabled`

    - #### isFlowsDrainingModeEnabled

          boolean isFlowsDrainingModeEnabled()

      Returns whether the flows draining mode is enabled.

      See Also:
        `setFlowsDrainingModeEnabled`

    - #### shutdown

          void shutdown()

      Shuts the node down. Returns immediately. This does not wait for flows to be completed.

    - #### terminate

          void terminate(boolean drainPendingFlows)

      Shuts the node down. Returns immediately.

      Parameters:
        `drainPendingFlows` - whether the node will wait for pending flows to be completed before exiting. While draining, new flows from RPC will be rejected.

    - #### isWaitingForShutdown

          boolean isWaitingForShutdown()

      Returns whether the node is waiting for pending flows to complete before shutting down. Disabling draining mode cancels this state.

      Returns:
        whether the node will shutdown when the pending flows count reaches zero.