MockNetwork
Keywords: net.corda.testing.node.MockNetwork class
Date: 2023-09-18

net.corda.testing.node

## Class MockNetwork

- net.corda.testing.node.MockNetwork

-     public class MockNetwork

  A mock node brings up a suite of in-memory services in a fast manner suitable for unit testing. Components that do IO are either swapped out for mocks, or pointed to a Jimfs in memory filesystem or an in memory H2 database instance.

  Java users can use the constructor that takes an (optional) `class MockNetworkParameters` builder, which may be more convenient than specifying all the defaults by hand. Please see `class MockNetworkParameters` for the documentation of each parameter.

  Mock network nodes require manual pumping by default: they will not run asynchronous. This means that for message exchanges to take place (and associated handlers to run), you must call the `runNetwork` method. If you want messages to flow automatically, use automatic pumping with a thread per node but watch out for code running parallel to your unit tests: you will need to use futures correctly to ensure race-free results.

  By default a single notary node is automatically started, which forms part of the network parameters for all the nodes. This node is available by calling `defaultNotaryNode`.

  See Also:
    Jimfs, `class MockNetworkParameters`, `class MockNetworkParameters`, `runNetwork`, `defaultNotaryNode`

- - ### Constructor Detail

    - #### MockNetwork

          public MockNetwork(@NotNull
                             java.util.List<java.lang.String> cordappPackages,
                             @NotNull
                             MockNetworkParameters defaultParameters,
                             boolean networkSendManuallyPumped,
                             boolean threadPerNode,
                             @NotNull
                             net.corda.testing.node.InMemoryMessagingNetwork.ServicePeerAllocationStrategy servicePeerAllocationStrategy,
                             @NotNull
                             java.util.List<net.corda.testing.node.MockNetworkNotarySpec> notarySpecs,
                             @NotNull
                             NetworkParameters networkParameters)

      A mock node brings up a suite of in-memory services in a fast manner suitable for unit testing. Components that do IO are either swapped out for mocks, or pointed to a Jimfs in memory filesystem or an in memory H2 database instance.

      Java users can use the constructor that takes an (optional) `class MockNetworkParameters` builder, which may be more convenient than specifying all the defaults by hand. Please see `class MockNetworkParameters` for the documentation of each parameter.

      Mock network nodes require manual pumping by default: they will not run asynchronous. This means that for message exchanges to take place (and associated handlers to run), you must call the `runNetwork` method. If you want messages to flow automatically, use automatic pumping with a thread per node but watch out for code running parallel to your unit tests: you will need to use futures correctly to ensure race-free results.

      By default a single notary node is automatically started, which forms part of the network parameters for all the nodes. This node is available by calling `defaultNotaryNode`.

      Parameters:
        `cordappPackages` - A List of cordapp packages to scan for any cordapp code, e.g. contract verification code, flows and services.
        `defaultParameters` - The default parameters for the network. If any of the remaining constructor parameters are specified thentheir values are taken instead of the corresponding value in defaultParameters.
        `networkSendManuallyPumped` - If false then messages will not be routed from sender to receiver until you usethe `MockNetwork.runNetwork` method. This is useful for writing single-threaded unit test code that can examine thestate of the mock network before and after a message is sent, without races and without the receiving node immediatelysending a response. The default is false, so you must call runNetwork.
        `threadPerNode` - If true then each node will be run in its own thread. This can result in race conditions inyour code if not carefully written, but is more realistic and may help if you have flows in your app that do longblocking operations. The default is false.
        `servicePeerAllocationStrategy` - How messages are load balanced in the case where a single compound identityis used by multiple nodes. You rarely if ever need to change that, it's primarily of interest to people testingnotary code.
        `notarySpecs` - The notaries to use in the mock network. By default you get one mock notary and that is usually sufficient.
        `networkParameters` - The network parameters to be used by all the nodes. NetworkParameters.notaries must beempty as notaries are defined by notarySpecs.
      See Also:
        Jimfs, `class MockNetworkParameters`, `class MockNetworkParameters`, `runNetwork`, `defaultNotaryNode`

    - #### MockNetwork

          @Deprecated
           @JvmOverloads
          public MockNetwork(@NotNull
                                                        java.util.List<java.lang.String> cordappPackages,
                                                        @NotNull
                                                        MockNetworkParameters parameters)

      Deprecated.

    - #### MockNetwork

          @Deprecated
           @JvmOverloads
          public MockNetwork(@NotNull
                                                        java.util.List<java.lang.String> cordappPackages)

      Deprecated.

    - #### MockNetwork

          public MockNetwork(@NotNull
                             MockNetworkParameters parameters)

  - ### Method Detail

    - #### getNextNodeId

          public int getNextNodeId()

      In a mock network, nodes have an incrementing integer ID. Real networks do not have this. Returns the next ID that will be used.

    - #### getDefaultNotaryNode

          @NotNull
          public StartedMockNode getDefaultNotaryNode()

      Returns the single notary node on the network. Throws an exception if there are none or more than one.

      See Also:
        `notaryNodes`

    - #### getDefaultNotaryIdentity

          @NotNull
          public Party getDefaultNotaryIdentity()

      Return the identity of the default notary node.

      See Also:
        `defaultNotaryNode`

    - #### getNotaryNodes

          @NotNull
          public java.util.List<net.corda.testing.node.StartedMockNode> getNotaryNodes()

      Returns the list of notary nodes started by the network.

    - #### createPartyNode

          @NotNull
          public StartedMockNode createPartyNode(@Nullable
                                                          CordaX500Name legalName)

      Create a started node with the given identity.

    - #### createNode

          @NotNull
          public StartedMockNode createNode(@NotNull
                                                     MockNodeParameters parameters)

      Create a started node with the given parameters.

    - #### createNode

          @JvmOverloads
           @NotNull
          public StartedMockNode createNode(@Nullable
                                                                    CordaX500Name legalName,
                                                                    @Nullable
                                                                    java.lang.Integer forcedID,
                                                                    @NotNull
                                                                    java.math.BigInteger entropyRoot,
                                                                    @Nullable
                                                                    MockNodeConfigOverrides configOverrides)

      Create a started node with the given parameters.

      Parameters:
        `legalName` - The node's legal name.
        `forcedID` - A unique identifier for the node.
        `entropyRoot` - The initial entropy value to use when generating keys. Defaults to an (insecure) random value,but can be overridden to cause nodes to have stable or colliding identity/service keys.
        `configOverrides` - Add/override the default configuration/behaviour of the node

    - #### createNode

          @JvmOverloads
           @NotNull
          public StartedMockNode createNode(@Nullable
                                                                    CordaX500Name legalName,
                                                                    @Nullable
                                                                    java.lang.Integer forcedID,
                                                                    @NotNull
                                                                    java.math.BigInteger entropyRoot)

      Create a started node with the given parameters.

      Parameters:
        `legalName` - The node's legal name.
        `forcedID` - A unique identifier for the node.
        `entropyRoot` - The initial entropy value to use when generating keys. Defaults to an (insecure) random value,but can be overridden to cause nodes to have stable or colliding identity/service keys.

    - #### createNode

          @JvmOverloads
           @NotNull
          public StartedMockNode createNode(@Nullable
                                                                    CordaX500Name legalName,
                                                                    @Nullable
                                                                    java.lang.Integer forcedID)

      Create a started node with the given parameters.

      Parameters:
        `legalName` - The node's legal name.
        `forcedID` - A unique identifier for the node.

    - #### createNode

          @JvmOverloads
           @NotNull
          public StartedMockNode createNode(@Nullable
                                                                    CordaX500Name legalName)

      Create a started node with the given parameters.

      Parameters:
        `legalName` - The node's legal name.

    - #### createNode

          @JvmOverloads
           @NotNull
          public StartedMockNode createNode()

      Create a started node with the given parameters.

    - #### createUnstartedNode

          @NotNull
          public UnstartedMockNode createUnstartedNode(@NotNull
                                                                MockNodeParameters parameters)

      Create an unstarted node with the given parameters.

    - #### createUnstartedNode

          @JvmOverloads
           @NotNull
          public UnstartedMockNode createUnstartedNode(@Nullable
                                                                               CordaX500Name legalName,
                                                                               @Nullable
                                                                               java.lang.Integer forcedID,
                                                                               @NotNull
                                                                               java.math.BigInteger entropyRoot,
                                                                               @Nullable
                                                                               MockNodeConfigOverrides configOverrides)

      Create an unstarted node with the given parameters.

      Parameters:
        `legalName` - The node's legal name.
        `forcedID` - A unique identifier for the node.
        `entropyRoot` - The initial entropy value to use when generating keys. Defaults to an (insecure) random value,but can be overridden to cause nodes to have stable or colliding identity/service keys.
        `configOverrides` - Add/override behaviour of the NodeConfiguration mock object.

    - #### createUnstartedNode

          @JvmOverloads
           @NotNull
          public UnstartedMockNode createUnstartedNode(@Nullable
                                                                               CordaX500Name legalName,
                                                                               @Nullable
                                                                               java.lang.Integer forcedID,
                                                                               @NotNull
                                                                               java.math.BigInteger entropyRoot)

      Create an unstarted node with the given parameters.

      Parameters:
        `legalName` - The node's legal name.
        `forcedID` - A unique identifier for the node.
        `entropyRoot` - The initial entropy value to use when generating keys. Defaults to an (insecure) random value,but can be overridden to cause nodes to have stable or colliding identity/service keys.

    - #### createUnstartedNode

          @JvmOverloads
           @NotNull
          public UnstartedMockNode createUnstartedNode(@Nullable
                                                                               CordaX500Name legalName,
                                                                               @Nullable
                                                                               java.lang.Integer forcedID)

      Create an unstarted node with the given parameters.

      Parameters:
        `legalName` - The node's legal name.
        `forcedID` - A unique identifier for the node.

    - #### createUnstartedNode

          @JvmOverloads
           @NotNull
          public UnstartedMockNode createUnstartedNode(@Nullable
                                                                               CordaX500Name legalName)

      Create an unstarted node with the given parameters.

      Parameters:
        `legalName` - The node's legal name.

    - #### createUnstartedNode

          @JvmOverloads
           @NotNull
          public UnstartedMockNode createUnstartedNode()

      Create an unstarted node with the given parameters.

    - #### startNodes

          public void startNodes()

      Start all nodes that aren't already started.

    - #### stopNodes

          public void stopNodes()

      Stop all nodes.

    - #### waitQuiescent

          public void waitQuiescent()

      Block until all scheduled activity, active flows and network activity has ceased.

    - #### runNetwork

          @JvmOverloads
          public void runNetwork(int rounds)

      Asks every node in order to process any queued up inbound messages. This may in turn result in nodes sending more messages to each other, thus, a typical usage is to call runNetwork with the `rounds` parameter set to -1 (the default) which simply runs as many rounds as necessary to result in network stability (no nodes sent any messages in the last round).

      See Also:
        `rounds`

    - #### runNetwork

          @JvmOverloads
          public void runNetwork()

      Asks every node in order to process any queued up inbound messages. This may in turn result in nodes sending more messages to each other, thus, a typical usage is to call runNetwork with the `rounds` parameter set to -1 (the default) which simply runs as many rounds as necessary to result in network stability (no nodes sent any messages in the last round).

      See Also:
        `rounds`

    - #### baseDirectory

          @NotNull
          public java.nio.file.Path baseDirectory(int nodeId)

      Get the base directory for the given node id.

    - #### getCordappPackages

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

      Deprecated.

      A

      List of cordapp packages to scan for any cordapp code, e.g. contract verification code, flows and services.

      See Also:
        List

    - #### getDefaultParameters

          @NotNull
          public MockNetworkParameters getDefaultParameters()

      The default parameters for the network.

      If any of the remaining constructor parameters are specified thentheir values are taken instead of the corresponding value in defaultParameters.

    - #### getNetworkSendManuallyPumped

          public boolean getNetworkSendManuallyPumped()

      If false then messages will not be routed from sender to receiver until you use

      the `MockNetwork.runNetwork` method. This is useful for writing single-threaded unit test code that can examine thestate of the mock network before and after a message is sent, without races and without the receiving node immediatelysending a response. The default is false, so you must call runNetwork.

      See Also:
        `MockNetwork.runNetwork`

    - #### getThreadPerNode

          public boolean getThreadPerNode()

      If true then each node will be run in its own thread.

      This can result in race conditions inyour code if not carefully written, but is more realistic and may help if you have flows in your app that do longblocking operations. The default is false.

    - #### getServicePeerAllocationStrategy

          @NotNull
          public net.corda.testing.node.InMemoryMessagingNetwork.ServicePeerAllocationStrategy getServicePeerAllocationStrategy()

      How messages are load balanced in the case where a single compound identity

      is used by multiple nodes. You rarely if ever need to change that, it's primarily of interest to people testingnotary code.

    - #### getNotarySpecs

          @NotNull
          public java.util.List<net.corda.testing.node.MockNetworkNotarySpec> getNotarySpecs()

      The notaries to use in the mock network.

      By default you get one mock notary and that is usually sufficient.

    - #### getNetworkParameters

          @NotNull
          public NetworkParameters getNetworkParameters()

      The network parameters to be used by all the nodes.

      NetworkParameters.notaries must beempty as notaries are defined by notarySpecs.