MatlabJavaInterface

Details on the MATLAB-Java Interface

This page describes interesting tidbits when working across the MATLAB-java interface, including the steps needed to debug Java code from a running MATLAB session.

Setting Up A Debugging Session With Eclipse

(Borrowed from: http://www.mathworks.com/matlabcentral/newsreader/view_thread/155261 )

These notes apply to MATLAB R2008a, R2009b and Eclipse 3.4.0 (Ganymede).

1. Create a Eclipse project for JAT. Its should include the source code of your java classes. The .class files should be created next to the source files.

2. Build JAT .class files and make sure those locations are in the MATLAB path. Be sure that when you build your .class files that all the debugging information is included in your build options. (ex: javac -g ...)

Note: The compiler compliance level settings in Eclipse should match the version of the JRE supplied with the target versions of MATLAB or an earlier version JRE that is common to all platforms. The version of the JRE used by Matlab can be determined by using the following Matlab command:
>> version - java
For example, not all MATLAB R2008a pltforms come with same JVM version. Vista can have 1.6 but Macs currently have only 1.5. Set the Eclipse compiler compliance level to 1.5 so that all platforms are supported and debuggable.

3. Create the java.opts file in your "startup" directory. Alternatively you could place java.opts in the "%MATLAB_ROOT%\bin\arch" directory but this has been seen not to work in all cases. This java.opts file is a standard text file. Choose a port number, e.g. 5678, that won't collide with any other application on your machine. You may have to open or allow this port to be used with your machine's firewall.

java.opts:

-agentlib:jdwp=transport=dt_socket,address=5678,server=y,suspend=n
-Djava.compiler=NONE

Note, the "-Djava.compiler=NONE" is optional. It turns off the Just-In-Time (JIT) compiler which translates the Java bytecode into native machine code. Generally the JIT offers significant speed improvement but it may reduce the amount of debugging information. Try it without first but if you see "strangeness" with your debugger place it back into the java.opts file and restart MATLAB to see if it fixes debugger quirks. Also remember to remove this line if you aren't debugging since it affects performance.

4. In your eclipse project, define a new debug configuration. Create a new Remote Java Application. Give it a good name, like MATLAB or something useful. Make sure the appropriate Project is set. The Connection Type should be Standard (Socket Attach). The Host should be localhost and the port should match the java.opts file above, e.g. 5678.

5. Launch MATLAB. Check, and set if required, the java classpath for the code in the Eclipse project to be debugged. MATLAB's java static or dynamic path can be used.

6. Then debug the "Remote Java Application" on the Eclipse side. Put a break point in your java code and instantiate or execute your java code from within MATLAB. You should see the breakpoint popping up when MATLAB calls java. If you see connection refused then there are a couple of problems:

1. MATLAB didn't find the java.opts file on startup,
2. The JVM couldn't read or parse the java.opts file,
3. Your machine's firewall is preventing the socket from being created,
4. Your machine's firewall is preventing the socket from being accessed.

You can even place breakpoints in Eclipse and MATLAB at the same time. To stop the java debugging just detach the Eclipse debugger from the MATLAB JVM. In Eclipse, highlight the [Remove Java Application] in the Debug processes/threads view and either use Terminate or the Disconnect from the Run menu or debug controls.

Parallel Processing Toolbox Limitation:
This can intefere with the matlabpool and other parallel processing toolbox functions. When the multiple labs are spawned each could use the same java.otps file and subsequent labs attempt to open the same port. Setting the address=0 will get around this problem by allowing each MATLAB instance (lab) to open its own port. The downside is that you will have to externally determine ('netcat'?) what ports these MATLAB instances are listening on in order to connect via Eclipse and adjust the Eclipse debug parameters accordingly.

Saving and Loading Java Objects from MATLAB

When running JAT, if you attempt to save your MATLAB workspace you will likely get an error such as:

>> whos
  Name           Size            Bytes  Class                                    Attributes

  o              1x1              5462  struct                                             
  y              1x1                    jat.matlabInterface.ODToolboxJATModel              
  ytostirng      1x45               90  char

>> save wstest.mat
Warning: jat.matlabInterface.ODToolboxJATModel@12c6ed8 is not serializable
Warning: Variable 'y' of class 'jat.matlabInterface.ODToolboxJATModel'
cannot be saved to a MAT-file or contains nonsaveable members.
Skipping...

This is because MATLAB is attempting to serialize and save the Java objects themselves. This may work with JAT (JAT /branches/ODTBX rev 114, Jan 2010) because some JAT classes have been made Serializable. However, not every single JAT class has been modified to implement java.io.Serializable. Mantis issue 169 is the first issue where JAT classes were made serializable to support the use of JAT and ODTBX in a parallel computing environment.

Note that serialization is a deep topic that will bring its own set of issues that should be addressed (such as properly coputing and handling the static final long serialVersionUID in each class). Here are a couple of handy links for reference:

• http://java.sun.com/javase/6/docs/technotes/guides/serialization/index.html
• http://java.sun.com/javase/6/docs/api/java/io/Serializable.html
• http://java.sys-con.com/node/36635
• http://frequal.com/java/PracticalSerialVersionIdGuidelines.html
• http://java.sun.com/developer/technicalArticles/Programming/serialization/
• http://www.devx.com/Java/Article/9931/1954

Problems with the Matlab Java Class Path

Note: This section is outdated. Most of this classpath setup is now handled in the startup.m provided with ODTBX.

1. The Java classpath can be set in the $matlab/toolboxes/local/classpath.txt file or in any .m file. We are setting it in startup.m, which assumes that JAT is located at: ../Jat. The ../Jat directory should contain the following directories: external_jar, external_dll, and jat. You must also add the individual external jar files to the classpath, just as you would do in eclipse. In classpath.txt add the location to the jar file as well as the jar file name and the .jar extension.

2. Matching versions of the JRE. The version of the JRE used by Matlab must match the one used to compile Jat. The version of the JRE used by Matlab can be determined by using the following Matlab command:
>> version - java
The version of the JRE used by Matlab can be set by setting the MATLAB_JAVA environment variable.

3. You also need to import the java package or class you will be accessing. This is best done in the piece of code which actually calls the method in Jat you are trying to use. To import a jat package simply put this at the top of your script:
>> import jat.subdirect.*
This will actually include all of the classes that are contained within a subdirectory under jat. If you want to access only one class type:
>> import classname

4. You also need to add Jat and all of the subfolders to the Matlab path by going into:
>> File-setPath-Add Folder with Subfolders- select Jat top directory which should include jat, external_jar & external_dll

5. To determine if the classpath has been set correctly, use the following Matlab command:
>> methodsview className
If you get an error message, the classpath is not set up correctly. className is the name of the class you import or in the case of a package one of the classes in the package.

6. In order to see changes that are made in Jat while Matlab is still open you need to add the /Jat directory described in step 1 to the dynamic path, along with the static path (what is done in step 1). To add /Jat to the dynamic path just use the command:
>> javaaddpath('location to /Jat')
When changes are made to Jat simply type:
>> clear java
at the command prompt in Matlab to see the changes in Matlab. If you make changes to Jat and have only set the static path you will need to close matlab and reopen it to see the changes. However you still want the Jat directory to be on the static path because the dynamic path is not set permanently using the javaaddpath command and therefore you will need to add the /Jat directory to the dynamic path each time you reopen Matlab if you will be making changes to Jat.

Navigation

OD Toolbox Home

WikiStart - Go back to OD Toolbox Home