Chapter 3. Simulation

3.1. Defining a Trace
3.2. Performing a Simulation

Simulation is performed by defining a trace file, containing a sequence of actions (e.g. message transfers), and one or more simulation definitions identifying how each role should be simulated.

3.1. Defining a Trace

The trace model can be serialized as a JSON representation, e.g.

{
	"name":"RequestResponse-1",
	"steps":[{
		"type":"MessageTransfer",
		"message":{
			"operator":"buy",
			"types":["{http://scribble.org/example}OrderRequest"],
			"values":[""]
		},
		"fromRole":"Buyer",
		"toRoles":["Seller"]
	},{
		"type":"MessageTransfer",
		"message":{
			"operator":"buy",
			"types":["{http://scribble.org/example}OrderResponse"],
			"values":[""]
		},
		"fromRole":"Seller",
		"toRoles":["Buyer"]
	}],
	"simulations":[{
		"roleSimulators":{
			"Buyer":{
				"type":"MonitorRoleSimulator",
				"module":"scribble.examples.RequestResponse",
				"role":"Buyer",
				"protocol":"First"
			},
			"Seller":{
				"type":"MonitorRoleSimulator",
				"module":"scribble.examples.RequestResponse",
				"role":"Seller",
				"protocol":"First"
			}
		}
	}]
}

In this example trace file, two steps (or actions) are defined. The first is representing the order request being sent from the Buyer role to the Seller role. The second is representing an order response being returned from the Seller role to the Buyer role. The message component defined the operator, list of parameter types, and list of parameter values. The values are currently optional - however once assertions are supported, the value will need to be provided.

The simulations section defines a list of simulations. Each simulation defined an optional name, and a map of role names to role simulators.

In this example, the only role simulator type used is MonitorRoleSimulator which uses the Scribble monitor to verify that the message transfers defined in the trace conform to the Scribble protocol identified by the module, role and protocol.

Note

If a trace contains steps associated with roles that are not defined within the role simulator map, then those roles will be ignored when performing the simulation.

3.2. Performing a Simulation

To perform a simulation from within your own application, you need to perform the following steps:

// Create a locator that can be used to load the scribble modules and any associated resources
org.scribble.resources.ResourceLocator locator=new org.scribble.resources.DirectoryResourceLocator(...);

// Build or load the trace (e.g. deserialize the JSON representation)
org.scribble.trace.model.Trace trace=...;

// Create a context using the locator
org.scribble.trace.simulation.SimulatorContext context=new org.scribble.trace.simulation.DefaultSimulatorContext(locator);

// Create the simulator
org.scribble.trace.simulation.Simulator simulator=new org.scribble.trace.simulation.Simulator();

// Instantiate an implementation of the listener interface, to be informed when steps are simulated
// successfully or unsuccessfully
org.scribble.trace.simulation.SimulationListener l=...;

// Add the listener to the simulator
simulator.addSimulationListener(l);

try {
	// Simulate the trace
	simulator.simulate(context, trace);
} catch (Exception e) {
	...
}

// Unregister the listener
simulator.removeSimulationListener(l);