You can draw from an extensive collection of existing Java® classes or create your own class definitions to use with MATLAB®. This topic explains how to find the class definitions that you need or how to create classes of your own design. This topic also describes how to specify the native method libraries used by Java code.
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.
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 third-party and user-defined class definitions. When loading a Java class, MATLAB searches files and folders in the order they occur on the class path. The search ends when MATLAB finds a file that contains the class definition.
MATLAB segments the Java class path into a static path and a dynamic path. MATLAB provides the dynamic path as a convenience for when you develop your own Java classes. After you develop and debug a Java class, add the class to the static path.
To view the two path segments, use the javaclasspath function.
Use the static path if you want the class functionality to run the same way it does in Java. Also, the static path offers better class loading performance than the dynamic path.
To add files to the static path, create a javaclasspath.txt file:
Create an ASCII text file and name the file javaclasspath.txt.
Enter the name of a Java class folder or jar file, one per line. For example:
c:\work\javaclasses
To simplify folder specifications in cross-platform
environments, use these macros: $matlabroot, $arch,
and $jre_home.
Save the file in your preferences folder. To view the location of the preferences folder, type:
prefdir
Alternatively, save the 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.
Restart MATLAB.
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.
If you do not want MATLAB to use the entries in the javaclasspath.txt file,
start MATLAB with the -nouserjavapath option.
Note: Do not put Java classes on the static path if they have dependencies on classes on the dynamic path. |
You can change class definitions on the dynamic path without restarting MATLAB. Therefore, it is useful to put a user-defined Java class definition on the dynamic path while you develop and debug the class.
MATLAB always searches the static path before the dynamic path.
To add a class to the dynamic path, use the javaclasspath and javaaddpath functions. To remove an entry,
use the javarmpath function.
These functions clear all existing variables and global variables
in the workspace.
The dynamic path offers greater flexibility in changing the path. However, Java classes on the dynamic path might load more slowly than classes on the static path. Also, classes on the dynamic path might not behave identical to classes on the static path. If your class does not behave as expected, use the static path.
After developing a Java class, put the class on the static path.
To make third-party and user-defined Java classes available to MATLAB, place them on either the static or dynamic Java class path.
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.
To put this folder on the dynamic class path, use the following command:
javaaddpath d:\work\javaclasses
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
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 |
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
You can now call the public methods in the JAR file. For information about these methods, refer to the JAR file documentation.
Class.forName MethodUse 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')
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.
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'
import FunctionYour 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. To see what classes are on
that list, type import. 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 methodsTo remove the list of imported Java classes, type:
clear import
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 runs 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.
import | inmem | javaclasspath