Bringing Java Classes into MATLAB Workspace

Introduction

You can draw from an extensive collection of existing Java® classes or create your own class definitions to use with MATLAB®. This section explains how to go about finding the class definitions that you need or how to create classes of your own design. Once you have the classes you need, defined in either individual .class files, packages, or Java Archive (JAR) files, you can make them available in the MATLAB workspace. This section also describes how to specify the native method libraries used by Java code.

Sources of Java Classes

Following are Java class sources that you can use in the MATLAB workspace:

  • Java built-in classes — general-purpose class packages, such as java.util, included in the Java language. See your Java language documentation for descriptions of these packages.

  • Third-party classes — packages of special-purpose Java classes.

  • User-defined classes — Java classes or subclasses of existing classes that you define using a Java language development environment.

Defining New Java Classes

To define new Java classes and subclasses of existing classes, use a Java Development Kit external to MATLAB. For information on supported versions of JDK™ software, see the Supported and Compatible Compilers website.

After you create class definitions in .java files, use your Java compiler to produce .class files from them. The next step is to make the class definitions in those .class files available for you to use in MATLAB.

The Java Class Path

MATLAB loads Java class definitions from files that are on the Java class path. The class path is a series of file and folder specifications that MATLAB uses to locate class definitions. When loading a Java class, MATLAB searches files and directories in the order they occur on the class path. The search ends when MATLAB finds a file that contains the class definition.

The Java class path consists of two segments: the static path and the dynamic path. MATLAB loads the static path at startup. If you change the path, you must restart MATLAB. You can load and modify the dynamic path at any time using MATLAB functions. MATLAB always searches the static path before the dynamic path.

    Note:   Do not put Java classes on the static path that have dependencies on classes on the dynamic path.

You can view these two path segments using the javaclasspath function:

javaclasspath
       STATIC JAVA PATH

   D:\Sys0\Java\util.jar
   D:\Sys0\Java\widgets.jar
   D:\Sys0\Java\beans.jar
             .
             .

       DYNAMIC JAVA PATH

   C:\Work\Java\ClassFiles
   C:\Work\Java\mywidgets.jar
             .
             .

You probably want to use both the static and dynamic paths:

  • Put the Java class definitions that are more stable on the static class path. Classes defined on the static path load faster than classes on the dynamic path.

  • Put the Java class definitions that you are likely to modify on the dynamic class path. You can change class definitions on this path without restarting MATLAB.

The Static Path

MATLAB loads the static class path at the start of each session. The static path offers better class loading performance than the dynamic path. To add folders to the static path, create the file javaclasspath.txt, and then restart MATLAB.

Create an ASCII file in your preferences folder named javaclasspath.txt. To view the location of the preferences folder, type:

prefdir

Each line in the file is the path of a folder or jar file. For example:

d:\work\javaclasses

To simplify the specification of directories in cross-platform environments, use any of these macros: $matlabroot, $arch, and $jre_home.

You also can create a javaclasspath.txt file in your MATLAB startup folder. Classes specified in this file override classes specified in the javaclasspath.txt file in the preferences folder.

To disable using the javaclasspath.txt file, execute MATLAB with the -nouserjavapath option.

    Note:   MATLAB reads the static class path only at startup. If you edit javaclasspath.txt or change your .class files while MATLAB is running, restart MATLAB to put those changes into effect.

The Dynamic Path

The dynamic class path can be loaded any time during a MATLAB session using the javaclasspath function. You can define the dynamic path, modify the path, and refresh the Java class definitions for all classes on the dynamic path without restarting MATLAB.

The functions javaaddpath and javaclasspath(dpath) add entries to the dynamic class path. To avoid the possibility that the new path contains a class or package with the same name as an existing class or package, MATLAB clears all existing global variables and variables in the workspace.

Although the dynamic path offers more flexibility in changing the path, Java classes on the dynamic path might load more slowly than classes on the static path.

Making Java Classes Available in MATLAB Workspace

To make third-party and user-defined Java classes available to MATLAB, place them on either the static or dynamic Java class path.

  • For classes you want on the static path, edit the javaclasspath.txt file.

  • For classes you want on the dynamic path, use either the javaclasspath or the javaaddpath functions.

Making Individual (Unpackaged) Classes Available

You can use individual classes (classes that are not part of a package) in MATLAB. To make them available, specify the full path to the folder you want to use for the .class files.

For example, to make available your compiled Java classes in the file d:\work\javaclasses\test.class, add the following entry to the static or dynamic class path:

d:\work\javaclasses

To put this folder on the static class path, edit the javaclasspath.txt file, described in The Static Path.

To put this folder on the dynamic class path, use the following command:

javaaddpath d:\work\javaclasses

Making Entire Packages Available

You can access classes in a package. To make a package available to MATLAB, specify the full path to the parent folder of the highest level folder of the package path. This folder is the first component in the package name.

For example, if your Java class package com.mw.tbx.ini has its classes in folder d:\work\com\mw\tbx\ini, add the following folder to your static or dynamic class path:

d:\work

Making Classes in a JAR File Available

You can use the jar (Java Archive) tool to create a JAR file, containing multiple Java classes and packages in a compressed ZIP format. For information on jar and JAR files, consult your Java development documentation.

To make the contents of a JAR file available for use in MATLAB, specify the full path, including full file name, for the JAR file. You also can put the JAR file on the MATLAB path.

    Note:   The path requirement for JAR files is different from the requirement for .class files and packages, for which you do not specify any file name.

For example, to make available the JAR file e:\java\classes\utilpkg.jar, add the following file specification to your static or dynamic class path:

e:\java\classes\utilpkg.jar

Loading a Class Using Java Class.forName Method

Use the javaObjectEDT function instead of the Java Class.forName method. For example, replace the following statement:

java.lang.Class.forName('xyz.myapp.MyClass')

with:

javaObjectEDT('xyz.myapp.MyClass')

Loading Java Class Definitions

Normally, MATLAB loads a Java class automatically when your code first uses it, for example, when you call its constructor. However, be aware of the following exception. When you use the which function on methods defined by Java classes, the function only acts on the classes currently loaded into the MATLAB workspace. In contrast, which always operates on MATLAB classes, whether they are loaded.

Determining Which Classes Are Loaded

At any time during a MATLAB session, you can obtain a listing of all the Java classes that are currently loaded. To do so, use the inmem function as follows:

[M,X,J] = inmem

This function returns the list of Java classes in the output argument J. (It also returns the names of all currently loaded MATLAB functions in M, and the names of all currently loaded MEX-files in X.)

Here is a sample of output from the inmem function:

[m,x,j] = inmem;
j

MATLAB displays:

j = 
	'java.util.Date'
	'com.mathworks.ide.desktop.MLDesktop'

Simplifying Java Class Names

Your MATLAB commands can refer to any Java class by its fully qualified name, which includes its package name. For example, the following are fully qualified names:

  • java.lang.String

  • java.util.Enumeration

A fully qualified name can be long, making commands and functions, such as constructors, cumbersome to edit and to read. To refer to classes by the class name alone (without a package name), first import the fully qualified name into MATLAB.

MATLAB adds all classes that you import to a list called the import list. You can see what classes are on that list by typing import, without any arguments. Your code can refer to any class on the list by class name alone.

When called from a function, import adds the specified classes to the import list in effect for that function. When invoked at the command prompt, import uses the base import list for your MATLAB platform.

For example, suppose that a function contains the following statements:

import java.lang.String
import java.util.* java.awt.*
import java.util.Enumeration

Any code that follows these import statements can refer to the String, Frame, and Enumeration classes without using the package names. For example:

str = String('hello');     % Create java.lang.String object
frm = Frame;               % Create java.awt.Frame object
methods Enumeration        % List java.util.Enumeration methods

To remove the list of imported Java classes, type:

clear import

Locating Native Method Libraries

Java classes can dynamically load native methods using the Java method java.lang.System.loadLibrary("LibFile"). In order for the JVM™ software to locate the specified library file, the folder containing it must be on the Java Library Path. This path is established when the MATLAB launches the JVM software at startup.

You can augment the search path for native method libraries by creating an ASCII text file named javalibrarypath.txt in your preferences folder. Follow these guidelines when editing this file:

  • Specify each new folder on a line by itself.

  • Specify only the folder names, not the names of the DLL files. The loadLibrary call reads the file names.

  • To simplify the specification of directories in cross-platform environments, use any of these macros: $matlabroot, $arch, and $jre_home.

You also can create a javalibrarypath.txt file in your MATLAB startup folder. Libraries specified in this file override libraries specified in the javalibrarypath.txt file in the preferences folder.

To disable using the javalibrarypath.txt file, execute MATLAB with the -nouserjavapath option.

Java Classes Contained in a JAR File

You can access Java classes that are contained in a JAR file once you have added the JAR file to either the static or dynamic class path. See The Java Class Path for more information on how MATLAB uses the Java class path.

For example, suppose that you have a file, myArchive.jar, in a folder called work in your MATLAB root folder. You can construct the path to this file using the matlabroot command:

[matlabroot '/work/myArchive.jar']

Add the JAR file to your dynamic class path using the javaaddpath function (fullfile adds the platform-correct folder separators):

javaaddpath(fullfile(matlabroot,'work','myArchive.jar'))

You can now call the public methods in the JAR file. For information about these methods, refer to the JAR file documentation.

Was this topic helpful?