com.jstatcom.engine.mlab
Class MLabEngine

java.lang.Object
  extended by com.jstatcom.engine.mlab.MLabEngine
All Implemented Interfaces:
Engine

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

A MLabEngine manages calls to methods defined in native libraries created with the MatLab compiler from .m files. It works on Win32 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.

Every argument and return type is translated to a pointer to an mxArray object and the call is made via the mlx interface method. The argument and return types of the function must be compatible with the JSCData objects defined in the call method. The name of the procedure to be called is the same as specified in the MatLab .m file.

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 MLabEngine getInstance()
          Returns an instance of the MLabEngine 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 or loads an executable.
 void shutdown()
          Calls termination code.
 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 MLabEngine getInstance()
Returns an instance of the MLabEngine that is a Singleton.

Returns:
an engine instance
Throws:
java.lang.RuntimeException - if the native support library cannot be found

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. It is assumed that the library was created with the MatLab compiler from an .m file. This call uses the mlx interface function. It also takes care of initialization and termination tasks.

Usage Note
The name of the procedure and the input/return parameters must conform to the specification in the MatLab .m file. All input and return parameters will first be transformed to a mxArray. Afterwards the return values are read back and set to the specified data objects. The datatypes must be correctly specified.

Important
Because of a special initialization/termination behaviour of matlab compiled libraries with graphics, it is currently not possible to use graphics functions in shared libraries. For this purpose, the load function together with the EXE load type must be used. Graphics must therefore be compiled as stand-alone applications. The data to display can be stored in a file, which can be handed over as a commandline argument. The file(s) with the data can be created in a previous call to a non graphic library.

Specified by:
call in interface Engine
Parameters:
procName - name of the procedure to call, must be defined in the currently loaded library, must correspond to the name in the .m file (lowercase)
args - arguments for the procedure
retData - return types
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
  • 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.UnsatisfiedLinkError - if native support routines cannot be found
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 or loads an executable. The library is then used in the next call to a function.

if (loadType == MLabLoadTypes.USERLIB) then the library is searched in the jmlab subdirectory.

if (loadType == MLabLoadTypes.SYSLIB) then the library is searched in the library search path.

if (loadType == MLabLoadTypes.EXE) then the executable is searched in the jmlab subdirectory and executed with args as commandline arguments.

Specified by:
load in interface Engine
Parameters:
module - the name of the system library to load without the system specific extension
loadType - the load type
args - only used for EXE load type, must contain only JSCString objects, empty objects are treated as "", can be null for no arguments
Throws:
java.lang.IllegalArgumentException -
  • if (loadName == null || loadType == null) or
  • if (module.length() == 0) or
  • if no user library/exectuable with that name exists in the jmlab subdir or
  • if EXE is specified and args contains other types than JSCTypes.STRING or
  • if args contains null elements
java.lang.RuntimeException - if operating system is not supported or if the system library/exectuable with the given name cannot be found or if execution returned other value than 0
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()
Calls termination code.

Specified by:
shutdown in interface Engine
See Also:
Engine.shutdown()