com.jstatcom.engine.matlab
Class MatlabEngine

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