Invoking Methods on Java Objects :: Using Sun Java Classes in MATLAB Software (MATLAB®)

Learn more about MATLAB

Invoking Methods on Java Objects

On this page…
Using Java and MATLAB Calling Syntax Invoking Static Methods on Java Classes Obtaining Information About Methods Java Methods That Affect MATLAB Commands How MATLAB Software Handles Undefined Methods How MATLAB Software Handles Java Exceptions Method Execution in MATLAB Software

On this page…

Using Java and MATLAB Calling Syntax

Invoking Static Methods on Java Classes

Obtaining Information About Methods

Java Methods That Affect MATLAB Commands

How MATLAB Software Handles Undefined Methods

How MATLAB Software Handles Java Exceptions

Method Execution in MATLAB Software

Using Java and MATLAB Calling Syntax

To call methods on Sun Java objects, you can use the Java syntax:

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

In the following example, myDate is a java.util.Date object, and getHours and setHours are methods of that object.

myDate = java.util.Date;
myDate.setHours(3)
myDate.getHours

The MATLAB software displays:

ans =
     3

Alternatively, you can call Java object (nonstatic) methods with the MATLAB syntax:

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

Using MATLAB syntax:

getHours(myDate)

MATLAB displays:

ans =
     3

All of the programming examples in this chapter contain invocations of Java object methods. For example, the code for Example — Reading a URL contains a call, using MATLAB syntax, to the openStream method on a java.net.URL object, url.

is = openStream(url)

In another example, the code for Example — Creating and Using a Phone Book contains a call, using Java syntax, to the load method on a java.utils.Properties object, pb_htable.

pb_htable.load(FIS);

Using the javaMethod Function on Nonstatic Methods

Under certain circumstances, you may need to use the javaMethod function to call a Java method. The following syntax invokes the method, method_name, on Java object J with the argument list that matches x1,...,xn. This returns the value X.

X = javaMethod('method_name',J,x1,...,xn);

For example, to call the startsWith method on a java.lang.String object passing one argument, use:

gAddress = java.lang.String('Four score and seven years ago');
str = java.lang.String('Four score');
javaMethod('startsWith', gAddress, str)
ans =
     1

Using the javaMethod function enables you to:

Use methods that have names that exceed the maximum length of a MATLAB identifier. (Call the namelengthmax function to obtain the maximum identifier length.)
Specify the method you want to invoke at run-time, for example, as input from an application user.

The only way to invoke a method whose name is longer than namelengthmax characters is to use javaMethod. The Java and MATLAB calling syntax does not accept method names of this length.

With javaMethod, you can also specify the method to be invoked at run time. In this situation, your code calls javaMethod with a string variable in place of the method_name argument. When you use javaMethod to invoke a static method, you can also use a string variable in place of the class name argument.

Note Typically, you do not need to use javaMethod. The default MATLAB syntax for invoking a Java method is somewhat simpler and is preferable for most applications. Use javaMethod primarily for the two cases described above.

Invoking Static Methods on Java Classes

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

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

For example, to call the isNaN static method on the java.lang.Double class, type:

java.lang.Double.isNaN(2.2)

Alternatively, you can apply static method names to instances of a class. In this example, the isNaN static method is referenced in relation to the dblObject instance of the java.lang.Double class.

dblObject = java.lang.Double(2.2);
dblObject.isNaN
ans =
     0

Using the javaMethod Function on Static Methods

You can use the javaMethod function to call static methods.

The following syntax invokes the static method, method_name, in class, class_name, with the argument list that matches x1,...,xn. This returns the value X.

X = javaMethod('method_name','class_name',x1,...,xn);

For example, to call the static isNaN method of the java.lang.Double class on a double value of 2.2, type:

javaMethod('isNaN','java.lang.Double',2.2);

Using the javaMethod function to call static methods enables you to:

Use methods that have names that exceed the maximum length of a MATLAB identifier. (Call the namelengthmax function to obtain the maximum identifier length.)
Specify method and class names at run-time, for example, as input from an application user.

Obtaining Information About Methods

MATLAB software offers several functions to help obtain information related to the Java methods you are working with. You can request a list of all of the methods that are implemented by any class. The list may be accompanied by other method information such as argument types and exceptions. You can also request a listing of every Java class that you loaded into MATLAB that implements a specified method.

Methodsview: Displaying a Listing of Java Methods

If you want to know what methods are 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.

The methodsview window is displayed.

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 the Methodsview Window

Field Name	Description	Examples
Qualifiers	Method type qualifiers	abstract, synchronized
Return Type	Type returned by the method	`void`, `java.lang.String`
Name	Method name	`addActionListener`, `dispatchEvent`
Arguments	Types of arguments passed to method	`boolean`, `java.lang.Object`
Other	Other relevant information	throws `java.io.IOException`
Inherited From	Parent of the specified class	`java.awt.MenuComponent`

Using the Methods Function on Java Classes

The methods function returns information on methods of MATLAB and Java classes. You can use any of the following forms of this command.

methods class_name
methods class_name -full
n = methods('class_name')
n = methods('class_name','-full')

Use methods without the '-full' qualifier to return the names of all the methods (including inherited methods) of the class. 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)

Determining What Classes Define a Method

You can use the which function to display the fully qualified name (package and class name) of a method implemented by a loaded Java class. With the -all qualifier, the which function finds all classes with a method of the name specified.

Suppose, for example, that you want to find the package and class name for the concat method, with the String class currently loaded. Use the command:

which concat
java.lang.String.concat  % String method

If the java.lang.String class has not been loaded, the same which command would give the output:

which concat
concat not found.

If you use which -all for the method equals, with the String and java.awt.Frame classes loaded, you see the following display.

which -all equals
java.lang.String.equals                     % String method
java.awt.Frame.equals                       % Frame method
com.mathworks.ide.desktop.MLDesktop.equals  % MLDesktop method

The which function operates differently on Java classes than it does on MATLAB classes. MATLAB classes are always displayed by which, whether or not they are loaded. This is not true for Java classes. 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 make use of the methods that are implemented within, or inherited by, these objects' classes. There are some MATLAB commands that you can alter somewhat in behavior by changing the Java methods that they rely on.

Changing the Effect of disp and display

You can use the disp function to display the value of a variable or an expression in MATLAB. Terminating a command line without a semicolon also calls the disp function. You can also use disp to display a Java object in MATLAB.

When disp operates on a Java object, MATLAB formats the output using the toString method of the class to which the object belongs. If the class does not implement this method, then an inherited toString method is used. If no intermediate ancestor classes define this method, it uses the toString method defined by the java.lang.Object class. You can override inherited toString methods in classes that you create by implementing such a method within your class definition. In this way, you can change the way MATLAB displays information regarding the objects of the class.

Changing the Effect of isequal

The MATLAB isequal function compares two or more arrays for equality in type, size, and contents. This function can also be used 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 it is not implemented in this class, then an inherited equals method is used. This is the equals method defined by the java.lang.Object class if no intermediate ancestor classes define this method.

You can override inherited equals methods in classes that you create by implementing such a method within your class definition. In this way, you can change the way MATLAB performs comparison of the members of this class.

Changing the Effect of double and char

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

How MATLAB Software 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.

string = java.lang.String('hello'); 
size(string)
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.

How MATLAB Software Handles Java Exceptions

If invoking a Java method or constructor throws an exception, MATLAB catches the exception and transforms it into a MATLAB error message. MATLAB puts the text of the Java error message into its own error message. Receiving an error from a Java method or constructor has the same appearance as receiving an error from an M-file.

Method Execution in MATLAB Software

When calling a main method from MATLAB, the method returns as soon as 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, need to be cautious when calling main methods from MATLAB, particularly main methods that launch GUIs. main methods are usually 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 GUI code might be already running can lead to problems.

Creating and Using Java Objects

Working with Java Arrays

Recommended Products

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit