Represent Native Java Cell and Struct Arrays

Java^® has no direct representation available for MATLAB^® struct arrays 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 multidimensional Object array, which can be difficult to process.

When you use MATLAB Compiler SDK™ packages with RMI, 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) subtype, 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.

You can use Java native representations of MATLAB struct and cell arrays if both of these conditions are true:

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

• You do not want to install MATLAB Runtime on your client machines

The classes in the com.mathworks.extern.java package (in javabuilder.jar) do not need MATLAB Runtime. The names of the classes in this package are the same as those in com.mathworks.toolbox.javabuilder — allowing you 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 MATLAB Runtime.

Since the MWArray class hierarchy can be used only with MATLAB Runtime, if the client machine does not have MATLAB Runtime available, the server returns the output of toArray() for struct or cell arrays as instances of com.mathworks.extern.java.MWStructArray or com.mathworks.extern.java.MWCellArray, respectively.

Prerequisites

To run this example, your environment must meet the following prerequisites:

• Install MATLAB Compiler SDK on the development machine.

• Install a supported version of the Java Development Kit (JDK™) on the development machine. For more information, see Configure Your Environment for Generating Java Packages.

• Install MATLAB Runtime on the web server. For details, see Download and Install MATLAB Runtime.

• Ensure that your web server is capable of running accepted Java frameworks like J2EE.

• Install the javabuilder.jar library (matlabroot/toolbox/javabuilder/jar/javabuilder.jar) into your web server’s common library folder.

  If your implementation has separate client machines, they also need javabuilder.jar, since it contains the com.mathworks.extern.java package.

Note

You do not need MATLAB Runtime installed on the client side. Return values from the MATLAB Runtime can be automatically converted using the boolean marshalOutputs in the RemoteProxy class. For details, see the Java API documentation in matlabroot/help/toolbox/javabuilder/MWArrayAPI.

Procedure

Copy the NativeCellStruct folder from MATLAB to your work folder:

copyfile(fullfile(matlabroot,'toolbox','javabuilder','Examples','RMIExamples','NativeCellStruct'))

At the MATLAB command prompt, navigate to the new NativeCellStruct\NativeCellStructDemoComp subfolder in your work folder.

Examine the MATLAB functions createEmptyStruct.m and updateField.m.

 createEmptyStruct.m

function PartialStruct = createEmptyStruct(field_names)

fprintf('EVENT 1: Initializing the structure on server and sending it to client:\n');

PartialStruct = struct(field_names{1},' ',field_names{2},[]);

fprintf('         Initialized empty structure:\n\n');
disp(PartialStruct);
fprintf('\n##################################\n');

 updateField.m

function FinalStruct = updateField(st,field_name)

fprintf('\nEVENT 3: Partially initialized structure as received by server:\n\n');
disp(st);
fprintf('Address field as initialized from the client:\n\n');
disp(st.Address);
fprintf('##################################\n');

fprintf(['\nEVENT 4: Updating ''', field_name, ''' field before sending the structure back to the client:\n\n']);
st.(field_name) = 'MathWorks';
FinalStruct = st;
disp(FinalStruct);
fprintf('\n##################################\n');

Generate the Java package using compiler.build.javaPackage by issuing the following command at the MATLAB command prompt:

compiler.build.javaPackage({'createEmptyStruct.m','updateField.m'}, ...
    'PackageName','nativeCellStructComp', ...
    'ClassName','nativeCellStructClass', ...
    'Verbose','on');

For more details, see the instructions in Generate Java Package and Build Java Application.

At your system command prompt, navigate to the NativeCellStruct\NativeCellStructDemoJavaApp folder.

Compile the server Java code by issuing one of the following javac commands at your system command prompt.

• On Windows^®, type:

  javac -classpath
   "matlabroot\toolbox\javabuilder\jar\javabuilder.jar;path\to\nativeCellStructComp.jar"
   NativeCellStructServer.java

• On UNIX^®, type:

  javac -classpath
   "matlabroot/toolbox/javabuilder/jar/javabuilder.jar:path/to/nativeCellStructComp.jar"
   NativeCellStructServer.java

Note

Replace matlabroot with the path to your MATLAB or MATLAB Runtime installation folder.

Compile the client Java code by issuing one of the following javac commands at your system command prompt.

• On Windows, type:

  javac -classpath
   "matlabroot\toolbox\javabuilder\jar\javabuilder.jar;path\to\dataTypesComp.jar
   NativeCellStructClient.java

• On UNIX, type:

  javac -classpath
   "matlabroot/toolbox/javabuilder/jar/javabuilder.jar:path/to/dataTypesComp.jar"
   NativeCellStructClient.java

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

Run the server by issuing one of the following java commands in a single line at the system command prompt.

• On Windows, type:

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

• On UNIX, type:

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

In the second command window, run the client by issuing one of the following java commands in a single line.

• On Windows, type:

  java -classpath
   .;"path/to/\dataTypesComp.jar;matlabroot\toolbox\javabuilder\jar\javabuilder.jar"
   NativeCellStructClient

• On UNIX, type:

  java -classpath
   .:"path/to/dataTypesComp.jar;matlabroot/toolbox/javabuilder/jar/javabuilder.jar"
   -Djava.rmi.server.codebase="file:///matlabroot/toolbox/javabuilder/jar/javabuilder.jar
   file:///path/to/dataTypesComp.jar"
   NativeCellStructClient

If the commands are successful, the following output appears in the command window running the server:

 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]


            ##################################



   

The following output appears in the command window running the client:

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

            #################################