Using Native Java with Cell Arrays and Struct Arrays

On this page…
Why Use Native Type Cell Arrays and Struct Arrays? Native Type Data Marshaling Prerequisites The Native Java Cell and Struct Example

Middle-Tier Developer

Middle-tier developer

Little to no MATLAB experience Moderate IT Experience Expert at business logic and services tier Java expert Minimal access to IT systems Expert at J2EE Expert at Web services

Integrates deployed component with the rest of the J2EE system by converting MATLAB data types (MWArrays) to the Java Business logic objects

Why Use Native Type Cell Arrays and Struct Arrays?

In Java, there is no direct representation available for MATLAB-specific struct and cell arrays.

As a result, when an instance of MWStructArray or MWCellArray is converted to a Java native type using the toArray() method, the output is a multi-dimensional Object array which can be difficult to process.

When you use MATLAB® Builder™ JA components with RMI, however, you have control over how the server sends the results of MATLAB function calls back to the client. The server can be set to marshal the output to the client as an MWArray (com.mathworks.toolbox.javabuilder package) sub-type or as a Java™ native data type. The Java native data type representation of MWArray subtypes is obtained by invoking the toArray() method by the server.

Using Java native representations of MATLAB struct and cell arrays is recommended if both of these are true:

• You have MATLAB functions on a server with MATLAB struct or cell data types as inputs or outputs

• You do not want or need to install an MCR on your client machines

Using Native Types Does Not Require a Client-Side MCR

The classes in the com.mathworks.extern.java package (in javabuilder.jar) do not need an MCR. The names of the classes in this package are the same as those in com.mathworks.toolbox.javabuilder — allowing the end-user to easily create instances of com.mathworks.extern.java.MWStructArray or com.mathworks.extern.java.MWCellArray that work the same as the like-named classes in com.mathworks.toolbox.javabuilder — on a machine that does not have an MCR.

The availability of an MCR on the client machine dictates how the server should be set for marshaling MATLAB functions, since the MWArray class hierarchy can be used only with an MCR. If the client machine does not have an MCR available, the server returns the output of toArray() for cell or struct arrays as instances of com.mathworks.extern.java.MWStructArray or com.mathworks.extern.java.MWCellArray.

Back to Top

Native Type Data Marshaling Prerequisites

Even though client machines don't need to have an MCR, they do need to have javabuilder.jar since it contains the com.mathworks.extern.java package.

Please refer to the Javadoc for more information about classes in all MATLAB Builder JA packages.

Back to Top

The Native Java Cell and Struct Example

Before You Run the Example

Before you run this example, note the following:

• This example demonstrates how to implement RMI when the client and the server are running on the same machine. See Running the Client and Server on Separate Machines if you would like to do otherwise.

• On UNIX, use : as the path separator in calls to java and javac. Use ; as a path separator on Windows.

• Only update the server system path with the location of the MCR. The client does not need access to the MCR.

• This example is shipped in the matlab\toolbox\javabuilder\Examples\RMIExamples\NativeCellStruct directory.

• Ensure that:

  • On Windows systems, matlabroot/runtime/arch is on the system path.

  • On UNIX systems, LD_LIBRARY_PATH and DYLD_LIBRARY_PATH are set properly. See Modifying the Path in the MATLAB Compiler User's Guide for further information on setting the path.

Running the Example

Note   Be sure to enter the following as single, unbroken commands.

1. Use the following mcc command to build the component:

    mcc -W 'java:dataTypesComp,dataTypesClass' createEmptyStruct.m 
                                               updateField.m -v

2. Compile the server's Java code:

   javac -classpath matlabroot\toolbox\javabuilder\jar\javabuilder.jar;
   directory_containing_component\dataTypesComp.jar NativeCellStructServer.java 

3. Compile the client's Java code:

   javac -classpath matlabroot\toolbox\javabuilder\jar\javabuilder.jar;
   directory containing component\dataTypesComp.jar 
   NativeCellStructClient.java 
   

4. Prepare to run the server and client applications by opening two DOS or UNIX command windows—one for client and one for server.

5. Run the server:

   java -classpath .;directory_containing_component\dataTypesComp.jar;
        matlabroot\toolbox\javabuilder\jar\javabuilder.jar 
   -Djava.rmi.server.codebase="file:///matlabroot/toolbox/javabuilder/
   jar/javabuilder.jar file:///
   directory_containing_component/dataTypesComp.jar" 
   NativeCellStructServer

6. Run the client:

   java -classpath .;directory_containing_component\dataTypesComp.jar;
   matlabroot\toolbox\javabuilder\jar\javabuilder.jar NativeCellStructClient

7. If your application has run successfully, the output will display as follows:

   • Server output:

      Please wait for the server registration notification.
                 Server registered and running successfully!!
     
                 EVENT 1: Initializing the structure on server and 
                          sending it to client:
                          Initialized empty structure:
     
                          Name: ' '
                          Address: []
     
     
                 ##################################
     
                 EVENT 3: Partially initialized structure as received 
                                                          by server:
     
                          Name: ' '
                          Address: [1x1 struct]
     
                    Address field as initialized from the client:
     
                          Street: '3, Apple Hill Drive'
                          City: 'Natick'
                          State: 'MA'
                          Zip: '01760'
     
                 ##################################
     
                 EVENT 4: Updating 'Name' field before sending the 
                          structure back to the client
     
                          Name: 'The MathWorks'
                          Address: [1x1 struct]
     
     
                 ##################################
     
     
     
        

   • Client output:

     Running the client application!!
     
                 EVENT 2: Initialized structure as received in client 
                                                         applications:
     
                          1x1 struct array with fields:
                             Name
                             Address
     
                     Updating the 'Address' field to :
     
                          1x1 struct array with fields:
                             Street
                             City
                             State
                             Zip
     
                 #################################
     
                 EVENT 5: Final structure as received by client:
     
                          1x1 struct array with fields:
                             Name
                             Address
     
                     Address field:
     
                          1x1 struct array with fields:
                             Street
                             City
                             State
                             Zip
     
                 #################################
     
     

Back to Top

Running the Client and Server on Separate Machines

Additional RMI Examples

© 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS