com.jstatcom.engine.ox

Class OxEngine

java.lang.Object

com.jstatcom.engine.ox.OxEngine

All Implemented Interfaces:

Engine

public final class OxEngine
extends java.lang.Object
implements Engine

Engine implementation to handle calls to the Ox program. Ox can be downloaded from http://www.nuff.ox.ac.uk/Users/Doornik/doc/ox/. It must be installed to run this engine. The exact location of the Ox dll must be set in jox/engine_config.xml. A dialog will appear to ask for it, if it was not set before.

The engine can create objects from Ox classes and invoke methods defined by those classes. Modules (.ox or .oxo files) must reside in the jox subfolder. Static methods cannot be called directly, but only member functions of Ox classes.

This engine takes JSCData arrays as arguments and return types and automatically does the conversion to and from the corresponding Ox types. Input and return parameters of the respective Ox function have to be known and the correct JSCTypes have to be specified.

Usage Example:
It is assumed, that there is a module oxmodule.ox(o) in the jox subfolder:

#include <oxstd.h>
// more includes
class MyClass {
decl lags;
MyClass();
setLags(const p);
... // more declarations
}
MyClass::setLags(const p){
lags = p;
}
... // more member methods


The Java call to that module could look like this:

Engine ox = EngineTypes.OX.getEngine();
ox.load("oxmodule", OxLoadTypes.OXO, null);
ox.load("MyClass", OxLoadTypes.CLASS, new JSCData[]{new JSCInt("arg", 3)}); // new MyClass(3)
ox.call("setLags", new JSCData[]{new JSCInt("lags", 3), null) // myclass.setLags(3);


Method Summary

Modifier and Type	Method and Description
void	call(java.lang.String procName, JSCData[] args, JSCData[] retData) Makes a call to a memberfunction of an Ox object.
static OxEngine	getInstance() Returns an instance of the OxEngine that is a Singleton.
boolean	isValid(JSCTypes type) Gets whether type can be handled by this engine.
void	load(java.lang.String loadName, LoadTypes loadType, JSCData... args) Loads a module according to the load type.
void	shutdown() Shuts down Ox workspace.
void	stop() Always throws an exception, because Ox engine tasks cannot be stopped.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static OxEngine getInstance()

Returns an instance of the OxEngine that is a Singleton.

Returns:

an engine instance

Throws:

java.lang.RuntimeException - if the native support libraries cannot be found

call

public void call(java.lang.String procName,
                 JSCData[] args,
                 JSCData[] retData)

Makes a call to a memberfunction of an Ox object. The object has to be created before via the load method with the OxLoadTypes.CLASS argument.

Input objects must not be empty or null. They are never changed by the Ox call. The following parameter conversion rules apply:

• JSCInt - OX_INT
• JSCNumber - OX_DOUBLE
• JSCNArray - OX_MATRIX
• JSCString - OX_STRING
• JSCSArray
  1. if cols == 1;OX_ARRAY (rows x 1) filled with OX_STRING values
  2. else; OX_ARRAY (rows x 1) with OX_ARRAY (cols x 1) values, each of them filled with OX_STRING values

Return types may be empty but not null. They are overwritten by the return values from the Ox call. The following parameter conversion rules apply:

• return is JSCInt - takes OX_INT, OX_DOUBLE or 0:0 element of OX_MATRIX if dimension is 1:1, if OX_INT, OX_DOUBLE, OX_MATRIX is empty, then return type is cleared
• return is JSCNumber - takes OX_INT, OX_DOUBLE or 0:0 element of OX_MATRIX if dimension is 1:1, if OX_INT, OX_DOUBLE, OX_MATRIX is empty, then return type is cleared
• return is JSCNArray - takes OX_INT, OX_DOUBLE or OX_MATRIX, if OX_INT, OX_DOUBLE, OX_MATRIX is empty, then return type is cleared
• return is JSCString - takes OX_STRING or 0:0 element of OX_ARRAY if dimension is 1:1, if OX_STRING, OX_SARRAY is empty, then return type is cleared, OX_ARRAY can contain one value or another OX_ARRAY with just one value, higher array nesting is not allowed
• return is JSCSARRAY - takes OX_STRING or OX_ARRAY (as vector of values or other OX_ARRAYs) with elements that are either OX_STRING, OX_DOUBLE, OX_INT, if OX_STRING, OX_ARRAY is empty, then return type is cleared, only up to 2 dimensional arrays with scalar values are supported

If none of the rules apply for the given return type, a RuntimeException is issued.

Specified by:

call in interface Engine

Parameters:

procName - name of the member function of the loaded class

args - arguments for function, number must match exactly with method signature

retData - return types from function, number must not match exactly with number of actually returned parameters, can be null

Throws:

java.lang.IllegalArgumentException - if (procName == null || procName.length() == 0) or if args or retData contain null elements or unsupported types or if an element of args is empty but not BYREF

java.lang.RuntimeException - if the module to load could not be found or if the call to the Ox system library resulted in an error

isValid

public boolean isValid(JSCTypes type)

Gets whether type can be handled by this engine.

Specified by:

isValid in interface Engine

Parameters:

type - the type to check

Returns:

true if type is one of NARRAY, INT, NUMBER, SARRAY or STRING, false otherwise

load

public void load(java.lang.String loadName,
                 LoadTypes loadType,
                 JSCData... args)

Loads a module according to the load type.

Usage Note:

• OxLoadTypes.VIEWER - spawns the viewer with loadName as file argument, args is ignored. The file to view must be specified with the absolute path.
• OxLoadTypes.OXO - loads the ox file specified with loadName in the workspace. The filename must not contain the .ox or .oxo suffix. If JSCConstants.DEBUG == true, then the .ox file is searched first, otherwise the compiled object file .oxo. The argument args is ignored. All filenames must be specified relative to the resource directory for the Ox engine.
• OxLoadTypes.CLASS - creates an instance of the class with the name loadName and the constructor arguments args. The file containing the class must have been loaded before via OxLoadTypes.OXO. The created object is then set to be the current object and all calls via the call method assume, that this object is used.

Specified by:

load in interface Engine

Parameters:

loadName - the name of the module to load

loadType - the type of the load operation to invoke

args - ignored for OxLoadTypes.OXO and OxLoadTypes.VIEWER, but used for OxLoadTypes.CLASS as constructor arguments, can be null

Throws:

java.lang.IllegalArgumentException - if (loadName == null || loadType == null) or if (loadName.length() == 0) or if args contains null or empty elements or unsupported types when used with OxLoadTypes.CLASS

java.lang.RuntimeException - if the module to load could not be found or if the call to the Ox system library resulted in an error

See Also:

Engine

stop

public void stop()

Always throws an exception, because Ox engine tasks cannot be stopped.

Specified by:

stop in interface Engine

Throws:

java.lang.UnsupportedOperationException

See Also:

Engine.stop()

shutdown

public void shutdown()

Shuts down Ox workspace.

Specified by:

shutdown in interface Engine

See Also:

Engine.shutdown()