matlabcontrol
Class MatlabProxy

java.lang.Object
  extended by matlabcontrol.MatlabProxy
All Implemented Interfaces:
MatlabOperations
Direct Known Subclasses:
LoggingMatlabProxy

public abstract class MatlabProxy
extends java.lang.Object
implements MatlabOperations

Communicates with a running MATLAB session. This class cannot be instantiated, it may be created with a MatlabProxyFactory. Interaction with MATLAB occurs as if calling eval and feval in the MATLAB Command Window.

Communicating with MATLAB

Methods which interact with MATLAB provide Java objects to the MATLAB environment and retrieve data from the MATLAB environment as Java objects. The following description of how the conversion between MATLAB and Java types occurs is based on tests conducted on versions of MATLAB R2007b through R2010b. Unless otherwise noted the behavior was identical on all tested versions. However, this behavior is not officially documented by The MathWorks and may change for future versions of MATLAB. (matlabcontrol is not compatible with versions prior to MATLAB R2007b.)

MATLAB to Java

Numeric Classes and Logical Class
All MATLAB numeric types whether they are a singular value or an array/matrix (of any dimension) are always converted into a one-dimensional Java double[]. For complex numbers, only the real component is converted. MATLAB logicals whether a singular value or an array/matrix (of any dimension) are always converted into a one-dimensional Java boolean[]. MATLAB arrays are stored in a linear manner, which has been documented by The MathWorks. It is in this linear manner that MATLAB arrays are returned to Java. (Sparse matrices are stored differently and are not sent to Java in an easy to use manner.)

Character Class
MATLAB char singular values are returned as a Java String. One-dimensional MATLAB char arrays are returned as a Java String. Two-dimensional MATLAB char arrays are returned as a Java String[] with each row of the MATLAB array becoming a Java String. MATLAB char arrays of more than two dimensions have an inconsistent conversion to a Java type, although all observed conversions are either a Java String or an array of Strings.

Cell and Struct Arrays
MATLAB cell arrays and struct arrays are converted to a Java Object[], often with arrays inside of them.

Function Handles and Non-Built-In Classes
MATLAB function_handles and all non-built-in classes (such as the Map class or user defined classes) are converted to an instance of com.mathworks.jmi.types.MLArrayRef that is not Serializable which prevents it from being transferred to a Java application running outside MATLAB (more information on this can be found in the exception section below).

Java to MATLAB

Primitives
It is not possible to directly send a Java primitive to the MATLAB environment because all methods which interact with MATLAB take in either Object or Object[] which results in the Java primitives becoming their auto-boxed class equivalent. (For example int becomes Integer.) Java primitive arrays, such as int[] are Objects and can therefore be sent to the MATLAB environment. They are converted as follows:

Java Type MATLAB Type
boolean[] logical array
char[] not supported*
byte[] int8 array
short[] int16 array
int[] int32 array
long[] not supported*
float[] single array
double[] double array

*In MATLAB R2009b and higher, MATLAB will throw an exception. In MATLAB R2008b and earlier, MATLAB will segfault. The behavior in MATLAB R2009a is not known.

Numbers
Subclasses of Number, which includes all of the auto-boxed versions of Java primitive numeric types, become MATLAB doubles.

Booleans
Booleans are converted to MATLAB logicals.

Characters
Characters are converted to MATLAB chars.

Strings
Strings are converted to MATLAB char arrays.

Object Arrays
Arrays of non-primitive types are converted to MATLAB cell arrays. The contents of the array are converted according to these same rules. Note that Java's multidimensional arrays are not an exception to this rule. For instance a double[][] is an array of double[]s and so MATLAB will create a cell array of MATLAB double arrays.

Other Classes
Classes not otherwise mentioned remain as their original Java type. Objects contained within that class or instances of that class are not automatically converted by MATLAB, although when fields or methods are accessed in the MATLAB environment they may be converted into MATLAB types as documented by The MathWorks.

Behavior of transferred data
How Java objects sent to MATLAB or retrieved from MATLAB behave depends on several factors:

Running outside MATLAB
References to Java objects are copies. (There is one exception to this rule. Objects that are Remote will act as if they are not copies. This is because matlabcontrol communicates with MATLAB's Java Virtual Machine using Remote Method Invocation.)

Running inside MATLAB
References to Java objects in MATLAB that are returned to Java, reference the same object. When passing a reference to a Java object to MATLAB, if the Java object is not converted to a MATLAB type then it will reference the same object in the MATLAB environment.

Help transferring data
The MatlabProxyLogger exists to record what is being returned from MATLAB. The MatlabTypeConverter can convert between complicated Java and MATLAB types. Currently only MATLAB numeric arrays are supported.

Exceptions

Proxy methods that are relayed to MATLAB can throw MatlabInvocationExceptions. They will be thrown if: 1This is a requirement of Remote Method Invocation, which matlabcontrol uses when running outside MATLAB.

2 This is due to Remote Method Invocation prohibiting loading classes defined in remote Java Virtual Machines unless a SecurityManager has been set. PermissiveSecurityManager exists to provide an easy way to set a security manager without further restricting permissions. Please consult PermissiveSecurityManager's documentation for more information.

3 MATLAB sessions started by a MatlabProxyFactory are able to load all classes defined in your application's class path as specified by the java.class.path property. Some frameworks load classes without placing them on the class path, in that case matlabcontrol will not know about them and cannot tell MATLAB how to load them.

Thread Safety

This proxy is unconditionally thread-safe. Methods which interact with MATLAB may be called concurrently; however they will be completed sequentially on MATLAB's main thread. Calls to MATLAB from a given thread will be executed in the order they were invoked. No guarantees are made about the relative ordering of calls made from different threads. This proxy may not be the only thing interacting with MATLAB's main thread. One proxy running outside MATLAB and any number of proxies running inside MATLAB may be simultaneously connected. If MATLAB is not hidden from user interaction then a user may also be making use of MATLAB's main thread. This means that two sequential calls to the proxy from the same thread that interact with MATLAB will execute in that order, but interactions with MATLAB may occur between the two calls. In typical use it is unlikely this behavior will pose a problem. However, for some uses cases it may be necessary to guarantee that several interactions with MATLAB occur without interruption. Uninterrupted access to MATLAB's main thread may be obtained by use of invokeAndWait(...).

Threads

When running outside MATLAB, the proxy makes use of multiple internally managed threads. When the proxy becomes disconnected from MATLAB it notifies its disconnection listeners and then terminates all threads it was using internally. A proxy may disconnect from MATLAB without exiting MATLAB by calling disconnect().

Since:
4.0.0
See Also:
MatlabProxyFactory.getProxy(), MatlabProxyFactory.requestProxy(matlabcontrol.MatlabProxyFactory.RequestCallback)

Nested Class Summary
static interface MatlabProxy.DisconnectionListener
          Listens for a proxy's disconnection from MATLAB.
static interface MatlabProxy.Identifier
          Uniquely identifies a proxy.
static interface MatlabProxy.MatlabThreadCallable<T>
          Uninterrupted block of computation performed in MATLAB.
static interface MatlabProxy.MatlabThreadProxy
          Operates on MATLAB's main thread without interruption.
 
Method Summary
 void addDisconnectionListener(MatlabProxy.DisconnectionListener listener)
          Adds a disconnection listener that will be notified when this proxy becomes disconnected from MATLAB.
abstract  boolean disconnect()
          Disconnects the proxy from MATLAB.
abstract  void exit()
          Exits MATLAB.
 MatlabProxy.Identifier getIdentifier()
          Returns the unique identifier for this proxy.
abstract
<T> T
invokeAndWait(MatlabProxy.MatlabThreadCallable<T> callable)
          Runs the callable on MATLAB's main thread and waits for it to return its result.
abstract  boolean isConnected()
          Whether this proxy is connected to MATLAB.
 boolean isExistingSession()
          Whether this proxy is connected to a session of MATLAB that was running previous to the request to create this proxy.
abstract  boolean isRunningInsideMatlab()
          Whether this proxy is running inside of MATLAB.
 void removeDisconnectionListener(MatlabProxy.DisconnectionListener listener)
          Removes a disconnection listener.
 java.lang.String toString()
          Returns a brief description of this proxy.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface matlabcontrol.MatlabOperations
eval, feval, getVariable, returningEval, returningFeval, setVariable
 

Method Detail

getIdentifier

public MatlabProxy.Identifier getIdentifier()
Returns the unique identifier for this proxy.

Returns:
identifier

isExistingSession

public boolean isExistingSession()
Whether this proxy is connected to a session of MATLAB that was running previous to the request to create this proxy.

Returns:
if existing session

toString

public java.lang.String toString()
Returns a brief description of this proxy. The exact details of this representation are unspecified and are subject to change.

Overrides:
toString in class java.lang.Object
Returns:

addDisconnectionListener

public void addDisconnectionListener(MatlabProxy.DisconnectionListener listener)
Adds a disconnection listener that will be notified when this proxy becomes disconnected from MATLAB.

Parameters:
listener -

removeDisconnectionListener

public void removeDisconnectionListener(MatlabProxy.DisconnectionListener listener)
Removes a disconnection listener. It will no longer be notified.

Parameters:
listener -

isRunningInsideMatlab

public abstract boolean isRunningInsideMatlab()
Whether this proxy is running inside of MATLAB.

Returns:

isConnected

public abstract boolean isConnected()
Whether this proxy is connected to MATLAB.

The most likely reasons for this method to return false are if the proxy has been disconnected via disconnect() or MATLAB has been closed (when running outside MATLAB).

Returns:
if connected
See Also:
disconnect(), exit()

disconnect

public abstract boolean disconnect()
Disconnects the proxy from MATLAB. MATLAB will not exit. After disconnecting, any method sent to MATLAB will throw an exception. A proxy cannot be reconnected. Returns true if the proxy is now disconnected, false otherwise.

Returns:
if disconnected
See Also:
exit(), isConnected()

exit

public abstract void exit()
                   throws MatlabInvocationException
Exits MATLAB. Attempting to exit MATLAB with either a eval or feval command will cause MATLAB to hang indefinitely.

Throws:
MatlabInvocationException
See Also:
disconnect(), isConnected()

invokeAndWait

public abstract <T> T invokeAndWait(MatlabProxy.MatlabThreadCallable<T> callable)
                         throws MatlabInvocationException
Runs the callable on MATLAB's main thread and waits for it to return its result. This method allows for uninterrupted access to MATLAB's main thread between two or more interactions with MATLAB.

If running outside MATLAB the callable must be Serializable; it may not be Remote.

Type Parameters:
T -
Parameters:
callable -
Returns:
result of the callable
Throws:
MatlabInvocationException