Synchronous RESTful Requests Using Protocol Buffers in the Java Client

This example shows how to make synchronous RESTful requests using the Java^® client API, MATLAB^® Production Server™ RESTful API for MATLAB Function Execution, and protocol buffers (protobuf). The example provides and explains a sample Java client, SyncExample.java, for evaluating a MATLAB function deployed on the server.

To use protobuf when making a request to the server, set the HTTP Content-Type header to application/x-google-protobuf in the client code. The Java client library provides helper classes to internally create protobuf messages based on a proto format and returns the corresponding byte array. Use this byte array in the HTTP request body. The Java client library provides methods and classes to deserialize the protobuf responses.

To use the Java client library, you must include mps_client.jar in the CLASSPATH.

The following table shows where to find the mps_client.jar file, Javadoc, and sample code for the example.

Location of `mps_client.jar`	`MPS_INSTALL/client/java` `MATLABProductionServer_<release>_Clients/java`
Location of Javadoc	`MPS_INSTALL/client/java/doc` `MATLABProductionServer_<release>_Clients/java/doc`
Location of code for the example files	`MPS_INSTALL/client/java/examples` `MATLABProductionServer_<release>_Clients/java/examples/MagicSquare`
`MPS_INSTALL` is the location in which MATLAB Production Server is installed. `MATLABProductionServer_<release>_Clients` is the folder containing MATLAB Production Server client libraries that you can download from https://www.mathworks.com/products/matlab-production-server/client-libraries.html.

The example uses the java.net package for making HTTP requests to evaluate a MATLAB function deployed on a MATLAB Production Server instance running on http://localhost:9910.

Deploy Your MATLAB Function on the Server

Write a MATLAB function mymagic that uses the magic (MATLAB) function to create a magic square, then deploy it on the server.

For information on how to deploy, see Create Deployable Archive for MATLAB Production Server.

function m = mymagic(in)

  m = magic(in);
end

The function mymagic takes a single int32 input and returns a magic square as a 2-D double array.

Make a Synchronous Request to the Server

Construct the request URL.
In the Java client, use the POST Synchronous Request to make the initial request to the server. The request URL comprises of the address of the server instance, the name of the deployed archive and the name of the MATLAB function to evaluate.
```
    String mpsBaseUrl = "http://localhost:9910";
    URL url;
    url = new URL(mpsBaseUrl + "/mymagic/mymagic");
```

Set the request headers.

Set the HTTP Content-Type header to application/x-google-protobuf, as the API returns a byte array of protocol buffer messages.

    final static protected String CONTENT_TYPE = "application/x-google-protobuf";
    HttpURLConnection urlConnection = (HttpURLConnection) url.openConnection();
    urlConnection.setDoOutput(true);
    urlConnection.setRequestProperty("Content-Type", CONTENT_TYPE);

Create an HTTP request body containing the protocol buffer message.
The function mymagic takes a single int32 input and returns a magic square as a 2-D double array.
Use the newInstance(arg1, arg2, arg3) method defined in the MATLABParams class to build the message. Since the mymagic function returns a single 2-D array, set arg1 to 1 and arg2 to double[][].class. Specify an integer value for arg3, which is the input to the mymagic function.
```
    MATLABParams mlMakeBody = MATLABParams.newInstance(1, double[][].class, 2);
```
Send the request to the server.
Write the MATLABParams mlMakeBody object to the output stream of the HTTP request.
```
    OutputStream output = urlConnection.getOutputStream();
    output.write(mlMakeBody.getRequestBody());
    output.flush();
```

Receive and Interpret the Server Response

On successful execution of the HTTP request, the server responds with a protocol buffer message. Parse the protocol buffer message using methods from the MATLABResult class to get the result of the request. To create a MATLABResult object, pass the MATLABParams mlMakeBody object and the response body of the HTTP request to the newInstance method.

If an error occurs when the deployed MATLAB function executes, then the call to the getResult method throws a MATLABException that contains the error message from MATLAB.

    MATLABResult<double[][]> mlFinalResult1 = 
        MATLABResult.newInstance(mlMakeBody, urlConnection.getInputStream());
    try{
        double[][] magicSq1 = mlFinalResult1.getResult();
        printResult(magicSq1);
    }catch(MATLABException e){
        e.printStackTrace();
    }

Write a helper method printResult which takes as input the result that is parsed from the response body and prints the corresponding 2-D array.

    private static void printResult(double[][] result) {
        for (double[] row : result) {
            for (double element : row) {
                System.out.print(element + " ");
            }
            System.out.println();
        }
    }

Sample code for the SyncExample.java Java client follows.

Code:

SyncExample.java

import com.mathworks.mps.client.MATLABException;
import com.mathworks.mps.client.rest.MATLABParams;
import com.mathworks.mps.client.rest.MATLABResult;

import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;


public class SyncExample{

	final static protected String CONTENT_TYPE = "application/x-google-protobuf";

    public static void main(String[] args){

        try{
	     // URL of the MATLAB Production Server.
	     String mpsBaseUrl = "http://localhost:9910";

            // Use the java.net package's URLConnection as HTTP Client in this example.		
            URL url;
            url = new URL(mpsBaseUrl + "/mymagic/mymagic");
            HttpURLConnection urlConnection = (HttpURLConnection) url.openConnection();
            urlConnection.setDoOutput(true);
            //Set Content-Type to protobuf.
            urlConnection.setRequestProperty("Content-Type", CONTENT_TYPE);

            // Make the initial POST request body with MATLABParams class.
            MATLABParams mlMakeBody = MATLABParams.newInstance(1, double[][].class, 2);

            // Write the MATLABParams object into the output stream of the HTTP request.
            OutputStream output = urlConnection.getOutputStream();
            output.write(mlMakeBody.getRequestBody());
            output.flush();

            // Parse the response body of the above HTTP request with methods from the MATLABResult class. 
	      // The MATLABParams object created earlier is an input argument to the newInstance method.
            // If there is any error in MATLAB, call to getResult() throws a MATLABException which
            // contains the error message displayed in MATLAB.
            MATLABResult mlFinalResult1 = MATLABResult.newInstance(mlMakeBody, urlConnection.getInputStream());
            try{
                double[][] magicSq1 = (double[][]) mlFinalResult1.getResult();
                printResult(magicSq1);
            }catch(MATLABException e){
                e.printStackTrace();
            }
        }catch(Exception e){
            e.printStackTrace();
        }
    }

    // Helper method to print out the magic square generated by MATLAB based on the input.
    private static void printResult(double[][] result) {
        for (double[] row : result) {
            for (double element : row) {
                System.out.print(element + " ");
            }
            System.out.println();
        }
    }
}