com.uppaal.engine
Class Engine

java.lang.Object
  com.uppaal.engine.Engine

public class Engine
extends Object

State-less wrapper for a UPPAAL server connection.

If you want to communicate with the UPPAAL verification engine, this is the class to use. It is a thin wrapper around the EngineStub class and provides a state-less interface to the verification engine. In contrast to the EngineStub class, it can work with several model instances at the same time (although with reduced speed) and transparently connect and reconnect to the engine.

The various connection modes are documented in the EngineStub class.

Before connecting to the engine, a document should be created, please see Document for sample code.

The following code demonstrates how to connect to a local UPPAAL engine via standard input/output streams using server protocol:

 Engine engine = new Engine();
 engine.setServerPath(enginePath);
 engine.connect();
 

where enginePath is a path to server executable. On Windows the enginePath is "uppaal-version\\bin-Win32\\server.exe" and on Linux it is "uppaal-version/bin-Linux/server".

Alternatively one can use a Linux server by starting socketserver utility on a remote computer. The socketserver uses default port 2350 and can be reached as follows:

 Engine engine = new Engine(EngineStub.BOTH, 2350, "hostname", enginePath);
 engine.connect();
 

If the connection fails, then the local server execution will be used instead.

Then the model document can be uploaded, syntax-checked and compiled as follows:

 ArrayList<Problem> problems = new ArrayList<Problem>();
 UppaalSystem system = engine.getSystem(doc, problems);
 

The array problems contains errors and warnings if any. If the compilation was successful the system object contains a reference to a compiled system model.

The following code can be used to execute and print random transitions:

 SystemState state = engine.getInitialState(system);
 while (state != null) {
      ArrayList<Transition> trans = engine.getTransitions(system, state);
      Transition tr = trans.get((int)Math.floor(Math.random()*trans.size()));
      if (tr.getSize()==0) { // transition without edges, something special:
          System.out.println(tr.getEdgeDescription());
      } else { // one or more edges involved:
          System.out.print("(");
          for (SystemEdge e: tr.getEdges()) {
              System.out.print(e.getProcessName()+": "
                  + e.getEdge().getSource().getPropertyValue("name")
                  + " -> "
                  + e.getEdge().getTarget().getPropertyValue("name")+", ");
          }
          System.out.println(")");
      }
      state = tr.getTarget(); // deadlock "transitions" will give null
 }
 

The verifier functionality can be accessed by calling the query method.

The options string in the query method is a concatenation of one option per line: an option name and a choice name (or one or more values) separated by space.

For example at the time of this writing the default list of options was:

order 0
reduction 1
representation 0
trace 0
extrapolation 0
hashsize 27
reuse 1
smcparametric 1
modest 0
statistical 0.01 0.01 0.05 0.05 0.05 0.9 1.1 0.0 0.0 1280.0 0.01
 

The options may vary from version to version and depends on the actual server binary used. One can inspect the list of available options by requesting getOptionsInfo() which will bring an XML description of all options.

See Also:

Document, EngineStub

Field Summary

protected EngineStub

stub The stub for the server connection.

Constructor Summary

Engine()
Constructs an Engine object for local connections.

Engine(int mode, int port, String host, String path)
Constructs an Engine object for the given connection settings.

Method Summary

void	cancel() Forced disconnection from the server.
void	connect() Connects to the server, if not already connected.
protected void	connected() Called whenever a connection to the server is established.
void	disconnect() Disconnect from the server.
protected void	disconnected() Called when disconnecting from the server.
SystemState	getInitialState(UppaalSystem system) Initialized UPPAAL system with the initial state.
LscProcess	getLscProcess(Document document, ArrayList<Problem> problems)
String	getOptionsInfo() Returns information about available options.
UppaalSystem	getSystem(Document document, ArrayList<Problem> problems) Instantiates a UPPAAL document.
ArrayList<Transition>	getTransitions(UppaalSystem system, SystemState state) Returns the list of outgoing transitions for the state of the given system.
String	getVersion() Returns the version string of the server.
char	query(UppaalSystem system, String options, String query, QueryFeedback f) Verify a guery on an instantiated UPPAAL model.
char	query(UppaalSystem system, SystemState state, String options, String query, QueryFeedback f) Verify a guery on an instantiated UPPAAL model.
void	setConnectionMode(int mode) Sets the connection mode.
void	setServerHost(String host) Sets the server host.
void	setServerPath(String path) Sets the server path.
void	setServerPort(int port) Sets the server port.
void	submit(Job job)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

stub

protected EngineStub stub

The stub for the server connection.

Constructor Detail

Engine

public Engine()

Constructs an Engine object for local connections. Make sure the engine path is set before connecting.

Engine

public Engine(int mode,
              int port,
              String host,
              String path)

Constructs an Engine object for the given connection settings.

Parameters:

mode - specifies mode: EngineStub.LOCAL (executed locally), EngineStub.SERVER (connected to remote socket) or EngineStub.BOTH (try remote and fallback to local when socket connection fails).

port - the socket port number (default 2350)

host - the hostname of the remote computer where the socketserver is started

path - a path to server binary for local execution.

Method Detail

setServerPath

public void setServerPath(String path)

Sets the server path. The server path should include the path to, filename of and options for the server binary.

setServerPort

public void setServerPort(int port)

Sets the server port. The server port is used in REMOTE mode to determine which port on the server to connect to.

setServerHost

public void setServerHost(String host)

Sets the server host. In SERVER mode the engine will try to connect to this host.

setConnectionMode

public void setConnectionMode(int mode)

Sets the connection mode. Mode is either LOCAL, SERVER or BOTH. In BOTH the stub will first try to build a remote connection and if that fails attempt to create a local connection.

disconnect

public void disconnect()

Disconnect from the server.

cancel

public void cancel()

Forced disconnection from the server.

getVersion

public String getVersion()
                  throws EngineException,
                         IOException

Returns the version string of the server.

Throws:

EngineException

IOException

getOptionsInfo

public String getOptionsInfo()
                      throws EngineException,
                             IOException

Returns information about available options. The information is returned as an XML document.

Throws:

EngineException

IOException

getTransitions

public ArrayList<Transition> getTransitions(UppaalSystem system,
                                            SystemState state)
                                     throws EngineException,
                                            IOException

Returns the list of outgoing transitions for the state of the given system.

Throws:

EngineException

IOException

getSystem

public UppaalSystem getSystem(Document document,
                              ArrayList<Problem> problems)
                       throws EngineException,
                              IOException

Instantiates a UPPAAL document. If successful, the instantiated system is returned. Otherwise null is returned and a problem report is stored in the problems vector.

Throws:

EngineException

IOException

getInitialState

public SystemState getInitialState(UppaalSystem system)
                            throws EngineException,
                                   IOException

Initialized UPPAAL system with the initial state. If not successful an exception is thrown.

Throws:

EngineException

IOException

getLscProcess

public LscProcess getLscProcess(Document document,
                                ArrayList<Problem> problems)
                         throws EngineException,
                                IOException

Throws:

EngineException

IOException

query

public char query(UppaalSystem system,
                  String options,
                  String query,
                  QueryFeedback f)
           throws EngineException,
                  IOException

Verify a guery on an instantiated UPPAAL model.

The given options are applied to the verification.

Parameters:

system - a reference to compiled system.

options - verification options.

query - a query to be checked.

f - a callback for progress feedback, status and traces.

Returns:

'T' if property is satisfied, 'F' if it is not satisfied, 'M' if it is maybe satisfied, and 'E' if an error occurred.

Throws:

EngineException

IOException

query

public char query(UppaalSystem system,
                  SystemState state,
                  String options,
                  String query,
                  QueryFeedback f)
           throws EngineException,
                  IOException

Verify a guery on an instantiated UPPAAL model.

The given options are applied to the verification.

Parameters:

system - a reference to compiled system.

state - a custom initial state

options - verification options.

query - a query to be checked.

f - a callback for progress feedback, status and traces.

Returns:

'T' if property is satisfied, 'F' if it is not satisfied, 'M' if it is maybe satisfied, and 'E' if an error occurred.

Throws:

EngineException

IOException

connect

public void connect()
             throws EngineException,
                    IOException

Connects to the server, if not already connected.

Throws:

EngineException

IOException

connected

protected void connected()
                  throws IOException,
                         EngineException

Called whenever a connection to the server is established.

Throws:

IOException

EngineException

disconnected

protected void disconnected()

Called when disconnecting from the server.

submit

public void submit(Job job)