MatlabProxy¶

public abstract class MatlabProxy implements MatlabInteractor¶

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 java.rmi.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 matlabcontrol.extensions.MatlabProxyLogger exists to record what is being returned from MATLAB. The matlabcontrol.extensions.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:

• An internal MATLAB exception occurs. This occurs primarily for two different reasons. The first is anything that would normally cause an error in MATLAB such as trying to use a function improperly or referencing a variable that does not exist. The second is due to the undocumented nature of the underlying Java MATLAB Interface API, such as trying to send a long[] to MATLAB.
• The proxy has been disconnected via disconnect().
• Communication between this Java Virtual Machine and the one that MATLAB is running in is disrupted (likely due to closing MATLAB).
• The class of an object to be sent or returned is not java.io.Serializable or java.rmi.Remote. ¹ Java primitives and arrays behave as if they were Serializable.
• The class of an object to be returned from MATLAB is not defined in your application and no SecurityManager has been installed.²
• The class of an object to sent to MATLAB is not defined in MATLAB and the class is not on your application’s classpath.³
• The method call is made from the Event Dispatch Thread (EDT) used by AWT and Swing components.⁴ (A matlabcontrol.extensions.CallbackMatlabProxy may be used to interact with MATLAB on the EDT.) This does not apply to exit() which may be called from the EDT.

¹This is a requirement of Remote Method Invocation, which matlabcontrol uses when running outside MATLAB. ² 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. ³ 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. ⁴ This is done to prevent MATLAB from hanging indefinitely. When interacting with MATLAB the calling thread (unless it is the main MATLAB thread) is paused until MATLAB completes the requested operation. When a thread is paused, no work can be done on the thread. MATLAB makes extensive use of the EDT when creating or manipulating figure windows, uicontrols, plots, and other graphical elements. For instance, calling plot from the EDT would never return because the plot function waits for the EDT to dispatch its event, which will never occur, because the thread has been paused. A related, but far less critical issue, is that pausing the EDT would make the user interface of MATLAB and any other Java GUI code running inside MATLAB non-responsive until MATLAB completed evaluating the command. 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().

Author:	Joshua Kaplan

See also: MatlabProxyFactory.getProxy(), MatlabProxyFactory.requestProxy(matlabcontrol.MatlabProxyFactory.RequestCallback)