com.jstatcom.engine

Interface Engine

All Known Implementing Classes:

GaussEngine, GRTEngine, MatlabEngine, MLabEngine, OxEngine, StubEngine, StubMlabEngine

public interface Engine

This interface defines the general contract that all implemented concrete engines must satisfy. Engine clients can communicate to a specific computational engine exclusively via method calls defined in this interface.

Usage Note:
The methods defined in this interface should be sufficient to generalize the communication to every potential computational engine.

Implemented methods should throw the following unchecked exceptions:

• IllegalArgumentException if a given argument was not valid
• RuntimeException if execution failed for some reason
• IllegalStateException if the engine was in a wrong state for the given method call

Each engine implementation should be created in a new package whith implementations of:

• Engine for the communication with the external software
• AbstractConfigPanel for user input of engine specific settings on the user machine (DefaultConfigPanel can be used as well)
• LoadTypes to define extra module types that might be loaded by that engine
• EngineTypes mediator to set the name, check settings and bind the other classes together
• ConfigKeys to define configuration settings for the engine

The communication to an external engine always depends on certain resources, like libraries, other executables or configuration files. The specific implementations of ConfigKeys, EngineTypes and AbstractConfigPanel should make sure that these resources are found and that they are in a consistent state to run the Engine instance.

See Also:

AbstractConfigPanel, LoadTypes, EngineTypes, ConfigKeys

Method Summary

Modifier and Type	Method and Description
void	call(java.lang.String procName, JSCData[] args, JSCData[] retData) Calls a procedure with input and return parameters specified.
boolean	isValid(JSCTypes type) Gets whether type can be handled by this engine.
void	load(java.lang.String module, LoadTypes loadType, JSCData... args) Loads an engine specific type that is defined by a load type.
void	shutdown() Terminates this engine and does clean up tasks.
void	stop() Stops a running execution.

Method Detail

call

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

Calls a procedure with input and return parameters specified.

The return parameters define the data types that are returned. If the procedure returns types that are not compatible with the types in retData then a RuntimeException should be thrown.

Elements in retData must not be null. All elements in retData and args must be understood by this engine, which is defined by the isValid method.

Returned values should be set to the elements in retData, instead of creating new data objects and replacing the array elements.

Parameters:

procName - procedure to be executed by this engine

args - the data to be used as input

retData - the return types

isValid

boolean isValid(JSCTypes type)

Gets whether type can be handled by this engine.

Parameters:

type - the data type to be checked

Returns:

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

load

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

Loads an engine specific type that is defined by a load type. Implementations of this method can perform various specific actions according to loadType, for example library loading, setting of filenames for modules or object creation with args.

Parameters:

module - the name of the module to load

loadType - the type of module to load

args - (optional) module load arguments if needed

stop

void stop()
   throws java.lang.UnsupportedOperationException

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

Throws:

java.lang.UnsupportedOperationException

shutdown

void shutdown()

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