Documentation

Calling Syntax

To call methods on Java^® objects, you can use either Java calling syntax or MATLAB^® calling syntax. Under certain circumstances, use the MATLAB javaMethod function.

• Java Calling Syntax

• MATLAB Calling Syntax

• Using the javaMethod Function

• Calling Syntax for Static Methods of Java Classes

Java Calling Syntax

To call methods on Java objects, use the Java syntax:

object.method(arg1,...,argn)

MATLAB Calling Syntax

To call methods on Java objects, use the MATLAB syntax:

method(object,arg1,...,argn)

For example, to call the getHours and setHours methods using MATLAB syntax:

mlDate = java.util.Date;
setHours(mlDate,3)
getHours(mlDate)

ans =
     3

Using the javaMethod Function

Note:   The MATLAB syntax is the preferred syntax for invoking a Java method. Use javaMethod for these special cases only.

Use the MATLAB javaMethod function to:

• Use Java methods with names that exceed the maximum length of a MATLAB identifier. (Call the namelengthmax function to obtain the maximum identifier length.)

• Specify a Java method to invoke at run time.

  For example, your code calls javaMethod with a character vector variable in place of the method argument. When you use javaMethod to invoke a static method, you also can use a character vector variable in place of the class name argument.

• Call the constructor of or a static method in an inner class. In the javaMethod and javaObject functions, specify the class name, using the $ character, as OuterClass$InnerClass.

  For example, suppose class com.ams.MyClass contains class MyInnerClass with static method methodname. In Java, the calling syntax is:

  out = com.ams.MyClass.MyInnerClass.methodname(arg);

  In MATLAB, type:

  out = javaMethod('methodname','com.ams.MyClass$MyInnerClass',arg)

Calling Syntax for Static Methods of Java Classes

To invoke a static method on a Java class, use the Java syntax:

class.method(arg1,...,argn)

For example, call the static method, isNaN:

java.lang.Double.isNaN(2.2)

ans =
     0

Obtaining Method Information

MATLAB provides the methods and methodsview functions to obtain information about the Java methods you are using. You also can request a listing of every Java class that you loaded into MATLAB that implements a specified method.

• Using methods to Display Method Names and Arguments

• Using methodsview to Display Argument Types and Exceptions

• Using which to Determine What Classes Define a Method

Using methods to Display Method Names and Arguments

The methods function returns information on methods of MATLAB and Java classes.

To return the names of all the methods (including inherited methods) of the class, use methods without the '-full' qualifier. Names of overloaded methods are listed only once.

With the '-full' qualifier, methods returns a listing of the method names (including inherited methods) along with attributes, argument lists, and inheritance information on each. Each overloaded method is listed separately.

For example, display a full description of all methods of the java.awt.Dimension object.

methods java.awt.Dimension -full

Methods for class java.awt.Dimension:
Dimension() 
Dimension(java.awt.Dimension) 
Dimension(int,int) 
java.lang.Class getClass()  % Inherited from java.lang.Object 
int hashCode()  % Inherited from java.lang.Object 
boolean equals(java.lang.Object) 
java.lang.String toString() 
void notify()  % Inherited from java.lang.Object 
void notifyAll()  % Inherited from java.lang.Object 
void wait(long) throws java.lang.InterruptedException 
   % Inherited from java.lang.Object
void wait(long,int) throws java.lang.InterruptedException 
   % Inherited from java.lang.Object 
void wait() throws java.lang.InterruptedException 
   % Inherited from java.lang.Object 
java.awt.Dimension getSize() 
void setSize(java.awt.Dimension) 
void setSize(int,int)

Using methodsview to Display Argument Types and Exceptions

To see methods implemented by a particular Java (or MATLAB) class, use the methodsview function. Specify the class name (along with its package name, for Java classes) in the command line. If you have imported the package that defines this class, then the class name alone suffices.

The following command lists information on all methods in the java.awt.MenuItem class. Type:

methodsview java.awt.MenuItem

A new window appears, listing one row of information for each method in the class.

Each row in the window displays up to six fields of information describing the method. The following table lists the fields displayed in the methodsview window along with a description and examples of each field type.

Fields Displayed in methodsview Window

Using which to Determine What Classes Define a Method

Use the which function to display the fully qualified name (package and class name) of a method implemented by a loaded Java class. To find all classes that define the specified method, use the which function with the -all qualifier.

For example, suppose you want to find the package and class name for the concat method. Type:

which concat

If the java.lang.String class is loaded, MATLAB displays:

concat is a Java method  % java.lang.String method

If the String class has not been loaded, MATLAB displays:

concat not found.

Suppose that you loaded the Java String and java.awt.Frame classes. Both of these classes have an equals method. Type:

which -all equals

The MATLAB display includes entries like the following:

equals is a Java method      % java.lang.String method
equals is a Java method      % java.awt.Frame.equals
equals is a Java method      % com.mathworks.jmi.MatlabPath method

The which function operates differently on Java classes than it does on MATLAB classes. which always displays MATLAB classes, whether they are loaded. which only displays Java classes that are loaded. You can find out which Java classes are currently loaded by using the command [m,x,j]=inmem, described in Determining Which Classes Are Loaded.

For a description of how Java classes are loaded, see Making Java Classes Available in MATLAB Workspace.

Java Methods That Affect MATLAB Commands

MATLAB commands that operate on Java objects and arrays use the methods that are implemented within, or inherited by, these objects' classes. There are some MATLAB commands that you can alter in behavior by changing the Java methods that they use.

Changing the Effect of disp and display

You are calling the disp function when you:

• Display the value of a variable or an expression in MATLAB.

• Terminate a command line without a semicolon.

• Display a Java object in MATLAB.

When calling disp on a Java object, MATLAB formats the output using the object toString method. If the class does not implement this method, then MATLAB uses an inherited toString method. If no intermediate ancestor classes define this method, MATLAB uses the toString method defined by the java.lang.Object class.

To change the way MATLAB displays an object, implement your own toString method in your class definition.

Changing the Effect of isequal

The MATLAB isequal function compares two or more arrays for equality in type, size, and contents. Also, you can use this function to test Java objects for equality.

When you compare two Java objects using isequal, MATLAB performs the comparison using the Java method, equals. MATLAB first determines the class of the objects specified in the command, and then uses the equals method implemented by that class. If equals is not implemented in this class, then MATLAB uses an inherited equals method. If no intermediate ancestor classes define this method, MATLAB uses the equals method defined by the java.lang.Object class.

To change the way MATLAB compares members of a class, implement your own equals method in your class definition.

Changing the Effect of double and char

You can change the output of the MATLAB double and char functions by defining your own Java methods, toDouble and toChar. For more information, see Converting to the MATLAB double Type and Converting to the MATLAB char Type.

How MATLAB Handles Undefined Methods

If your MATLAB command invokes a nonexistent method on a Java object, MATLAB looks for a function with the same name. If MATLAB finds a function of that name, it attempts to invoke it. If MATLAB does not find a function with that name, it displays a message stating that it cannot find a method by that name for the class.

For example, MATLAB has a function named size, and the Java API java.awt.Frame class also has a size method. If you call size on a Frame object, the size method defined by java.awt.Frame is executed. However, if you call size on an object of java.lang.String, MATLAB does not find a size method for this class. It executes the MATLAB size function instead.

text = java.lang.String('hello'); 
size(text)

ans =
     1     1

Note:   When you define a Java class for use in MATLAB, avoid giving any of its methods the same name as a MATLAB function.

Handling Java Exceptions

Use the matlab.exception.JavaException class to handle Java exceptions.

Method Execution in MATLAB

When calling a main method from MATLAB, the method returns when it executes its last statement, even if the method creates a thread that is still executing. In other environments, the main method does not return until the thread completes execution.

You, therefore, be cautious when calling main methods from MATLAB, particularly main methods that start a user interface. main methods are written assuming they are the entry point to application code. When called from MATLAB this is not the case, and the fact that other Java UI code might be already running can lead to problems.