com.jstatcom.engine.gauss
Class GaussEngine

java.lang.Object
  com.jstatcom.engine.gauss.GaussEngine

All Implemented Interfaces:

Engine

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

Links to an instance of the software package Gauss (www.aptech.com). This object performs the whole communication with Gauss and has control over it, i.e. it starts, commands, and ends Gauss.

This class enforces the Singleton property by a static initializer. Currently it runs only on the Windows OS.

Author:

Markus Kraetzig

Method Summary

void	call(java.lang.String procName, JSCData[] args, JSCData[] retData) Executes a procedure with input and return parameters specified.
java.lang.String	compileGCG() Compiles the source files defined in the XML file for compilation.
java.lang.String	createLibs() Creates the GAUSS libraries defined in the respective XML file
void	execute(java.lang.String command) Executes a GAUSS command.
static GaussEngine	getInstance() Returns an instance of the GaussEngine 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	read(JSCData[] rtArray) Reads all variables defined in varNames from GAUSS.
void	shutdown() Terminates this engine and does clean up tasks.
void	start(boolean compileIfNecessary) Starts an instance of GAUSS.
void	stop() Stops a running execution.
void	write(JSCData[] engineData) Write a data array to GAUSS.

Methods inherited from class java.lang.Object

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

Method Detail

compileGCG

public java.lang.String compileGCG()

Compiles the source files defined in the XML file for compilation.

Returns:

null if ok, error string otherwise

createLibs

public java.lang.String createLibs()

Creates the GAUSS libraries defined in the respective XML file

Returns:

null if ok, error string otherwise

execute

public void execute(java.lang.String command)

Executes a GAUSS command. If this engine is in debug mode, the command is also printed to System.out.

Parameters:

command - string with GAUSS code, for example "y=rndn(100,1)"

Throws:

java.lang.IllegalArgumentException - if (command == null)

java.lang.RuntimeException - if execution of command failed, use getMessage to retrieve the error string

call

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

Executes a procedure with input and return parameters specified. The results are set to the data objects specified in retData. Listeners registered to these data objects receive notifications if something changed.

Please note:
If a data object of type JSCTypes.INT is specified as return, then any double scalar will silently be cast to an int. It may happen that information is lost during that operation.

Specified by:

call in interface Engine

Parameters:

procName - procedure name to be executed by this engine

args - the data to be used as input, can be null or emtpy if no arguments needed

retData - the data array to store results can be null or emtpy if no returns needed

Throws:

java.lang.IllegalArgumentException - if args or retData contain elements that are null

java.lang.RuntimeException - if return types are not compatible with returns

getInstance

public static GaussEngine getInstance()

Returns an instance of the GaussEngine that is a Singleton. Whenever this method is called, the respective system library is loaded.

Returns:

initialized GAUSS instance, not yet started

Throws:

java.lang.RuntimeException - if operating system is not supported or if something went wrong during the init process

java.lang.UnsatisfiedLinkError - if system libraries cannot be found

isValid

public boolean isValid(JSCTypes type)

Description copied from interface: Engine

Gets whether type can be handled by this engine.

Specified by:

isValid in interface Engine

Parameters:

type - the data type to be checked

Returns:

true if ok, false if type cannot be handled by this engine

See Also:

Engine

load

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

Loads a module according to the load type. All filenames must be specified relative to the resource directory for the GAUSS engine. The args argument is ignored.

Specified by:

load in interface Engine

Parameters:

loadName - the name of the module to load

loadType - the type of module to load

args - (optional) module load arguments if needed

Throws:

java.lang.IllegalArgumentException - if (loadName == null || loadType == null) or if (loadName.length() == 0) or if loadName is not valid

See Also:

Engine

read

public void read(JSCData[] rtArray)

Reads all variables defined in varNames from GAUSS. The varTypes are necessary to enforce type savety.

Parameters:

rtArray - the data to be read

Throws:

java.lang.IllegalArgumentException - if (rtArray == nul) or if rtArray contains null elements

java.lang.RuntimeException - if the variable could not be read or if an invalid type was specified or if the read variable does not match with the respective type

start

public void start(boolean compileIfNecessary)

Starts an instance of GAUSS. If in DEBUG mode, then it uses the library system, otherwise the specified .gcg file is loaded. If the load of the .gcg file fails then a compilation of the source files is carried out.

Nothing happens if GAUSS is already running.

Parameters:

compileIfNecessary - compiles gcg file if it cannot be loaded

Throws:

java.lang.RuntimeException - if start fails

stop

public void stop()

Description copied from interface: Engine

Stops a running execution. If there is nothing to do for this engine, this method must throw an UnsupportedOperationException.

Specified by:

stop in interface Engine

See Also:

Engine

shutdown

public void shutdown()

Description copied from interface: Engine

Terminates this engine and does clean up tasks. Whenever a load or execute is called afterwards this engine should be reinitialized.

Specified by:

shutdown in interface Engine

See Also:

Engine

write

public void write(JSCData[] engineData)

Write a data array to GAUSS. If GAUSS is not yet running, the start method is called.

Parameters:

engineData - the data array to be written to GAUSS

Throws:

java.lang.IllegalArgumentException - if one of the data types cannot be handled by the GAUSS engine or if (engineData == null) or if one element of engineData is null

java.lang.RuntimeException - if write failed of if GAUSS could not be started if it was not running before

See Also:

Engine