Class MatlabEngine

  extended by com.jstatcom.engine.matlab.MatlabEngine
All Implemented Interfaces:

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

Engine for calling Matlab Compiler generated dlls from .m source files. Allows full control over execution, especially stopping is supported.

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 MatlabEngine 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 setOutErrHandler(OutErrHandler outErrHandler)
          Sets a new output error handler.
 void shutdown()
          Empty method, no termination code.
 void stop()
          Stops a running execution.
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail


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

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


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.

Specified by:
call in interface Engine
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
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) or
  • 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


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

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


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()
Description copied from interface: Engine
Stops a running execution. If there is nothing to do for this engine, this method must throw an UnsupportedOperationException.

Specified by:
stop in interface Engine
See Also:


public void shutdown()
Empty method, no termination code.

Specified by:
shutdown in interface Engine
See Also:


public void setOutErrHandler(OutErrHandler outErrHandler)
Sets a new output error handler.

outErrHandler - new implementation for dealing with output and errors
java.lang.IllegalArgumentException - if null argument