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.