MATLAB®

Bringing Java™ Classes and Methods into MATLAB^® Workspace

Introduction

You can draw from an extensive collection of existing Sun™ Java™ classes or create your own class definitions to use with MATLAB^® software. 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.

Back to Top

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. You need to use a Java language development environment to do this, as explained in the following section.

Back to Top

Defining New Java™ Classes

To define new Java classes and subclasses of existing classes, you must use a Java language development environment external to MATLAB software. See Technical Note 1601 http://www.mathworks.com/support/tech-notes/1600/1601.html for information on supported versions of the Java Development Kit (JDK™) software. You can download the JDK from the Sun Microsystems™ Web site, (http://java.sun.com/j2se/). The Sun site also provides documentation for the Java language and classes that you need for development.

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.

Back to Top

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 directory specifications that MATLAB software uses to locate class definitions. When loading a particular Java class, MATLAB searches files and directories in the order they occur on the class path until a file is found that contains that class definition. The search ends when the first definition is found.

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   Java classes on the static path should not 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 somewhat faster than those on the dynamic path.

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

The Static Path

MATLAB loads the static class path from the classpath.txt file at the start of each session. The static path offers better class loading performance than the dynamic path. However, to modify the static path, you need to edit classpath.txt, and then restart MATLAB.

Finding and Editing classpath.txt.   The default classpath.txt file resides in the toolbox\local subdirectory of your MATLAB root directory matlabroot:

[matlabroot '\toolbox\local\classpath.txt']
ans =
   \\sys07\matlab\toolbox\local\classpath.txt

To make changes in the static path that affect all users who share this same MATLAB root directory, edit this file in toolbox\local. If you want to make changes that do not affect anyone else, copy classpath.txt to your own startup directory and edit the file there. When MATLAB starts up, it looks for classpath.txt first in your startup directory, and then in the default location. It uses the first file it finds.

To see which classpath.txt file is currently being used by your MATLAB environment, use the which function:

which classpath.txt

To edit either the default file or the copy in your own directory, type:

edit classpath.txt

Note    MATLAB reads classpath.txt only at startup. If you edit classpath.txt or change your .class files while MATLAB is running, you must restart MATLAB to put those changes into effect.

Special Symbols in classpath.txt.   You can designate special tokens or macros in the classpath.txt file using a leading dollar sign, (e.g., $matlabroot or $jre_home). However, this can cause problems if you use this sign in any of your class directory paths. For example, the following path string does not correctly represent the path to a directory named hello$world:

d:\applications\hello$world

You must use two consecutive dollar signs in classpath.txt to represent a single $ character. So, to correctly specify the directory path shown above, you need to use the following text:

d:\applications\hello$$world

The Dynamic Path

The dynamic class path can be loaded any time during a MATLAB software session using the javaclasspath function. You can define the dynamic path (using javaclasspath), modify the path (using javaaddpath and javarmpath), and refresh the Java class definitions for all classes on the dynamic path (using clear with the keyword java) without restarting MATLAB. See the Java function reference pages for more information on how to use these functions.

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

Back to Top

Making Java™ Classes Available in MATLAB^® Workspace

To make your third-party and user-defined Java classes available in the MATLAB workspace, place them on either the static or dynamic Java class path, as described in the previous section, The Java™ Class Path.

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

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

Making Individual (Unpackaged) Classes Available

To make individual classes (classes that are not part of a package) available in MATLAB, specify the full path to the directory you want to use for the .class file(s).

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 directory on the static class path, add the above line to the default copy (in toolbox\local) or your own local copy of classpath.txt. See Finding and Editing classpath.txt.

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

javaaddpath d:\work\javaclasses

Making Entire Packages Available

To access one or more classes belonging to a package, you need to make the entire package available to MATLAB. To do this, specify the full path to the parent directory of the highest level directory of the package path. This directory is the first component in the package name.

For example, if your Java class package com.mw.tbx.ini has its classes in directory d:\work\com\mw\tbx\ini, add the following directory 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 or the JavaSoft Web site http://www.javasoft.com. See also To Learn More About Java™ Programming Language.

To make the contents of a JAR file available for use in MATLAB, specify the full path, including full filename, for the JAR file.

Note   The classpath.txt requirement for JAR files is different than that for .class files and packages, for which you do not specify any filename.

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

Back to Top

Loading Java™ Class Definitions

Normally, MATLAB software loads a Java class automatically when your code first uses it, (for example, when you call its constructor). However, there is one exception you should be aware of.

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 or not they are loaded.

Determining Which Classes Are Loaded

At any time during a MATLAB software 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 M-files in M, and the names of all currently loaded MEX-files in X.)

Here's a sample of output from the inmem function:

[m,x,j] = inmem;

MATLAB displays:

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

Back to Top

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 rather long, making commands and functions, such as constructors, cumbersome to edit and to read. You can refer to classes by the class name alone (without a package name) if you first import the fully qualified name into MATLAB.

The import command has the following forms:

import pkg_name.*               % Import all classes in package
import pkg_name1.* pkg_name2.*  % Import multiple packages
import class_name               % Import one class
import                          % Display current import list
L = import                      % Return current import list

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 software environment.

For example, suppose 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 clear the list of imported Java classes, type:

clear import

Back to Top

Locating Native Method Libraries

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

matlabroot/toolbox/local/librarypath.txt

You can augment the search path for native method libraries by editing the librarypath.txt file. Follow these guidelines when editing this file:

• Specify each new directory on a line by itself.

• Specify only the directory names, not the names of the DLL files. The loadLibrary call does this for you.

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

Back to Top

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 software uses the Java class path.

For example, suppose you have a file, myArchive.jar, in a directory called work in your MATLAB root directory. 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 directory separators):

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

You can now call the public methods in the JAR file.

Back to Top

Product Overview

Creating and Using Java™ Objects