Class StubEngine

  extended by com.jstatcom.engine.stub.StubEngine
All Implemented Interfaces:

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

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

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


public static StubEngine getInstance()
Returns an instance of the StubEngine that is a Singleton.

an engine instance


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:

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.

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


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
type - the data type to be checked
true if ok, false if type cannot be handled by this engine
See Also:


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.

Specified by:
load in interface Engine
module - the name of the system library to load with/without the system specific extension (SYSLIB/USERLIB)
loadType - the load type
args - always ignored
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[])


public java.lang.String getCurrentSysLib()
Gets the system library that is currently used by this engine. It can be changed via the load method.

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


public void stop()
Throws an Exception, because the task cannot be stopped.

Specified by:
stop in interface Engine
See Also:


public void shutdown()
Does nothing.

Specified by:
shutdown in interface Engine
See Also: