com.jstatcom.engine.stub
Class StubEngine

java.lang.Object
  com.jstatcom.engine.stub.StubEngine

All Implemented Interfaces:

Engine

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

A StubEngine manages calls to methods defined in arbitrary system libraries. It works on Win32, Linux (i386), and Solaris. It uses the "Shared Stubs" example by Sheng Liang to dispatch method calls without the need to create a distinguished JNI wrapper for every library to be used.

The methods defined in the system library can take certain types as arguments and returns, which are

• int, &int
• double, &double
• float, &float
• int*
• double*
• float*
• int**
• double**
• float**
• char*
• char**
• char***

The argument and return types must be compatible with the JSCData objects defined in the call method.

Author:

Markus Kraetzig

Method Summary

void	call(java.lang.String procName, JSCData[] args, JSCData[] retData) Makes a call to procName in the native library that was loaded before.
java.lang.String	getCurrentSysLib() Gets the system library that is currently used by this engine.
static StubEngine	getInstance() Returns an instance of the StubEngine that is a Singleton.
boolean	isValid(JSCTypes type) Gets whether type can be handled by this engine.
void	load(java.lang.String module, LoadTypes loadType, JSCData... args) Sets the name of the native library to be used.
void	shutdown() Does nothing.
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

Method Detail

getInstance

public static StubEngine getInstance()

Returns an instance of the StubEngine that is a Singleton.

Returns:

an engine instance

call

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

Makes a call to procName in the native library that was loaded before. The method signature is created from the specified input and return parameters. The CSignTypes can be used to set certain properties (FLOAT, VECTOR, BYREF) on the corresponding data objects. This can be used to conform to a wide range of different method signatures. The following C-types correspond to JSCTypes:

• double - JSCNumber
• float - JSCNumber with FLOAT == true
• int - JSCInt
• &double - JSCNumber with BYREF == true
• &float - JSCNumber with FLOAT == true && BYREF == true
• &int - JSCInt with BYREF == true
• char* - JSCString
• char** - JSCSArray with VECTOR == true
• char*** - JSCSArray with VECTOR == false
• double* - JSCNArray with VECTOR == true
• double** - JSCSNrray with VECTOR == false
• float* - JSCNArray with VECTOR == true && FLOAT == true
• float** - JSCSNrray with VECTOR == false && FLOAT == true

Input specification
If a type corresponds to a C-pointer type (instead of a value), then the memory is allocated according to the rows and columns of the respective JSCData object. All input arguments are filled with the values of the corresponding pointers after the procedure call, which means that it is possible to use an argument that holds the results. Value arguments must not be empty.

Return specification
If retData == null or has zero length, then the procedure is assumed to return void. If the return type (retData[0].tpye()) is a pointer type, then it is assumed, that the returned pointer from the procedure call has the same dimensions as retData[0], because is not possible to retrieve the size from the returned pointer.

Vectors
Often C-functions have input arguments that correspond to a one dimensional array. To call functions with these types, the vector property of JSCSArray and JSCNArray must be set to true. The data object is then vectorized (similar to UMatrix.vec). After the function call the pointer is indirected to the data object again, the array elements are filled with the values from the pointer columnwise, keeping the original array dimension.

Specified by:

call in interface Engine

Parameters:

procName - name of the procedure to call, must be defined in the currently loaded library

args - arguments for the procedure, the method signature is derived from it

retData - return type, can contain at most 1 element, void if empty or null, if type is an array, it has to be set to the rows and cols of the returned pointer

Throws:

java.lang.IllegalArgumentException -

• if args or retData contain null elements or unsupported types
• if retData contains more than 1 element
• if (procName == null || procName.length() == 0)
• if an element of args represents INT, NUMBER or STRING but is empty and BYREF == false
• if an element of args represents SARRAY and contains null strings

java.lang.RuntimeException - if procName adress could not be found in the loaded library

java.lang.IllegalStateException - if no system library was loaded before

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.isValid(com.jstatcom.model.JSCTypes)

load

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

Sets the name of the native library to be used. The library is then used in the next call to a function.

Usage Note:
if (loadType == StubLoadTypes.USERLIB) then the library is searched in the jstub subdirectory. No system specific extension (.dll/.so) is required but will be appended automatically according to the running OS.

if (loadType == StubLoadTypes.SYSLIB) then the library is searched in the library search path. The library name must be fully qualified with extension, because not all system libraries have a default suffix (e.g. libc.so.6).

Specified by:

load in interface Engine

Parameters:

module - the name of the system library to load with/without the system specific extension (SYSLIB/USERLIB)

loadType - the load type

args - always ignored

Throws:

java.lang.IllegalArgumentException - if (loadName == null || loadType == null) or if (module.length() == 0) or if no user library with that name exists in the jstub subdir

java.lang.RuntimeException - if operating system is not supported or if the system library with the given name cannot be found

See Also:

Engine.load(String, com.jstatcom.engine.LoadTypes, com.jstatcom.model.JSCData[])

getCurrentSysLib

public java.lang.String getCurrentSysLib()

Gets the system library that is currently used by this engine. It can be changed via the load method.

Returns:

the absolute path of the current system library or null if none has been loaded so far

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()

Does nothing.

Specified by:

shutdown in interface Engine

See Also:

Engine.shutdown()