com.jstatcom.engine.grte
Class GRTEngine

java.lang.Object
  com.jstatcom.engine.grte.GRTEngine

All Implemented Interfaces:

Engine

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

Provides communication to the Gauss Runtime Engine and conforms to the Engine interface. This class serves as an adapter to the GaussWorkspace class of the GaussApi. Currently only realy numbers and arrays are recognized, the complex part of returns is ignored.

Usage Note:
The engine can be configured via the respective XML config file. On initialization the given GCG file is loaded and the procedure initJGRTE defined in jgrte.src is called. On shutdown the method shutdownGRTE is called. It is assumed that these method are compiled into the loaded GCG file before. Change the respective GAUSS code according to your needs. The default functionality depends on the system library jgrte.dll (Windows) to manage the display of graphics, which would otherwise not work properly.

By default this communication class assumes that the GRT type engine version 5.0 is loaded. This can be changed via setting the system library in the XML config file.

All resources must be placed in the subdirectory jgrte.

Author:

Markus Kraetzig

Constructor Summary

GRTEngine()
Creates an instance of GRTEngine.

Method Summary

void	call(java.lang.String procName, JSCData[] args, JSCData[] retData) Calls a procedure with input and return parameters specified.
com.aptech.gaussApi5_0.GaussWorkspace	getGaussWorkSpace() Gets the workspace that is encapsulated by this engine.
static GRTEngine	getInstance() Returns an initialized instance of the GRTEngine that is a Singleton.
com.aptech.gaussApi5_0.GaussWorkspace	getWk() Gets the gauss workspace that this engine uses.
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() Deletes graphics directory and shuts down all workspaces by calling Gauss.shutdown().
void	stop() Throws an Exception, because the task cannot be stopped.

Methods inherited from class java.lang.Object

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

Constructor Detail

GRTEngine

public GRTEngine()

Creates an instance of GRTEngine. This should only be invoked if more than one workspace is needed. Otherwise the static initializer should be preferred. This attaches System.out to the output and error writer of the created GaussWorkspace.

Throws:

java.lang.RuntimeException - if something went wrong during the init process

com.aptech.gaussApi5_0.GaussException - if the workspace initialization failed

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

Method Detail

call

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

Calls a procedure with input and return parameters specified. If this method is called after shutdown then the initialization is done again. If JSCConstants.DEBUG == true, then initialization is done for every call. This allows to take changes in the compiled GCG file into account without restarting.

IMPORTANT:
Any GaussMatrix that is returned from a GRTE call that contains only a single NaN element is treated as an empty matrix and is transformed to an empty JSCData object of the specified type. This convention is choosen, because otherwise not initialized objects could not be returned.

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 to be called

args - the data to be used as input, can be null or emtpy

retData - the data objects to store the return parameters, can be null or emtpy

Throws:

java.lang.IllegalArgumentException - if args or retData contain elements that are null or if (procName == null || procName.length() == 0) or if procName is not a loaded procedure

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

com.aptech.gaussApi5_0.GaussException - if there were any GAUSS errors during the execution of the procedure

getInstance

public static GRTEngine getInstance()

Returns an initialized instance of the GRTEngine that is a Singleton.

Returns:

initialized GRTE instance

Throws:

java.lang.RuntimeException - if something went wrong during the init process

com.aptech.gaussApi5_0.GaussException - if the workspace initialization failed

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 GRT engine. The args argument is ignored. If this command is called after shutdown then the initialization is done again.

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 - always ignored

Throws:

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

See Also:

Engine

stop

public void stop()

Throws an Exception, because the task cannot be stopped.

Specified by:

stop in interface Engine

Throws:

java.lang.UnsupportedOperationException

See Also:

Engine.stop()

shutdown

public void shutdown()

Deletes graphics directory and shuts down all workspaces by calling Gauss.shutdown().

Specified by:

shutdown in interface Engine

getGaussWorkSpace

public com.aptech.gaussApi5_0.GaussWorkspace getGaussWorkSpace()

Gets the workspace that is encapsulated by this engine.

Returns:

the current workspace used for this engine

getWk

public com.aptech.gaussApi5_0.GaussWorkspace getWk()

Gets the gauss workspace that this engine uses.

Returns:

gauss workspace