com.jstatcom.engine.matlab
Class MatlabEngine

java.lang.Object
  extended by com.jstatcom.engine.matlab.MatlabEngine
All Implemented Interfaces:
Engine

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.

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

getInstance

public static MatlabEngine 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.

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

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.

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 - ignored
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()
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:
Engine

shutdown

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

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

setOutErrHandler

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

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