External Interfaces/API

Passing Java Objects

When calling a method that has an argument belonging to a particular Java class, you must pass an object that is an instance of that class. In the example below, the add method belonging to the java.awt.Menu class requires, as an argument, an object of the java.awt.MenuItem class. The method declaration for this is

• public MenuItem add(MenuItem mi)
  

The example operates on the frame created in the previous example in Passing Built-In Data Types. The second, third, and fourth lines of code shown here add items to a menu to be attached to the existing window frame. In each of these calls to menu1.add, an object that is an instance of the java.awt.MenuItem Java class is passed.

• menu1 = java.awt.Menu('File Options');
  menu1.add(java.awt.MenuItem('New'));
  menu1.add(java.awt.MenuItem('Open'));
  menu1.add(java.awt.MenuItem('Save'));
  
  menuBar=java.awt.MenuBar;
  menuBar.add(menu1);
  frame.setMenuBar(menuBar);
  

Handling Objects of Class java.lang.Object

A special case exists when the method being called takes an argument of the java.lang.Object class. Since this class is the root of the Java class hierarchy, you can pass objects of any class in the argument. The hash table example shown that follows, passes objects belonging to different classes to a common method, put, which expects an argument of java.lang.Object. The method declaration for put is

• public synchronized Object put(Object key, Object value)
  

The following MATLAB code passes objects of different types (boolean, float, and string) to the put method.

• hTable = java.util.Hashtable;
  hTable.put(0, java.lang.Boolean('TRUE'));
  hTable.put(1, java.lang.Float(41.287));
  hTable.put(2, java.lang.String('test string'));
  
  hTable                  % Verify hash table contents
  hTable =
  {1.0=41.287, 2.0=test string, 0.0=true}
  

When passing arguments to a method that takes java.lang.Object, it is not necessary to specify the class name for objects of a built-in data type. Line three, in the example above, specifies that 41.287 is an instance of class java.lang.Float. You can omit this and simply say, 41.287, as shown in the following example. Thus, MATLAB will create each object for you, choosing the closest matching Java object representation for each argument.

The three calls to put from the preceding example can be rewritten as

• hTable.put(0, 1);
  hTable.put(1, 41.287);
  hTable.put(2, 'test string');
  

Passing Objects in an Array

The only types of Java object arrays that you can pass to Java methods are Java arrays and MATLAB cell arrays.

If the objects have already been placed into an array, either an array returned from a Java constructor or constructed in MATLAB by the javaArray function, then you simply pass it as is in the argument to the method being called. No conversion is done by MATLAB, as this is already a Java array.

If you have objects that are not already in a Java array, then MATLAB allows you to simply pass them in a MATLAB cell array. In this case, MATLAB converts the cell array to a Java array prior to passing the argument.

The following example shows the mapPoints method of a user-written class accepting an array of class java.awt.Point. The method declaration for this is

• public Object mapPoints(java.awt.Point p[])
  

The MATLAB code shown below creates a 2-by-2 cell array containing four Java Point objects. When the cell array is passed to the mapPoints method, MATLAB converts it to a Java array of type java.awt.Point.

• pointObj1 = java.awt.Point(25,143);
  pointObj2 = java.awt.Point(31,147);
  pointObj3 = java.awt.Point(49,151);
  pointObj4 = java.awt.Point(52,176);
  
  cellArray={pointObj1, pointObj2; pointObj3, pointObj4}
  cellArray = 
      [1x1 java.awt.Point]    [1x1 java.awt.Point]
      [1x1 java.awt.Point]    [1x1 java.awt.Point]
  
  testData.mapPoints(cellArray);
  

Handling a Cell Array of Java Objects

You create a cell array of Java objects by using the MATLAB syntax {a1,a2,...}. You index into a cell array of Java objects in the usual way, with the syntax a{m,n,...}.

The following example creates a cell array of two Frame objects, frame1 and frame2, and assigns it to variable frames.

• frame1 = java.awt.Frame('Frame A');
  frame2 = java.awt.Frame('Frame B');
  
  frameArray = {frame1, frame2}
  frameArray = 
  [1x1 java.awt.Frame]    [1x1 java.awt.Frame]
  

The next statement assigns element {1,2} of the cell array frameArray to variable f.

• f = frameArray {1,2}
  f =
  java.awt.Frame[frame2,0,0,0x0,invalid,hidden,layout = 
  java.awt.BorderLayout,resizable,title=Frame B]
  

Passing String Arguments

Other Data Conversion Topics