com.jstatcom.engine.mlab
Class MLabEngine

java.lang.Object
  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()