Main Content

Java Client Coding Best Practices

Static Proxy Interface Guidelines

When you write Java® interfaces to invoke MATLAB® code, remember these considerations:

  • The method name exposed by the interface must match the name of the MATLAB function being deployed.

  • The method must have the same number of inputs and outputs as the MATLAB function.

  • The method input and output types must be convertible to and from MATLAB.

  • If you are working with MATLAB structures, remember that the field names are case sensitive and must match in both the MATLAB function and corresponding user-defined Java type.

  • The name of the interface can be any valid Java name.

Java Client Prerequisites

Complete the following steps to prepare your MATLAB Production Server™ Java development environment.

  1. Install a Java IDE of your choice. Follow instructions on the Oracle Web site for downloading Java , if needed.

  2. Add mps_client.jar (located in $MPS_INSTALL\client\java) to your Java CLASSPATH and Build Path. This JAR file is sometimes defined in separate GUIs, depending on your IDE.

    Generate one deployable archive into your server’s auto_deploy folder for each MATLAB application you plan to deploy. For information about creating a deployable archive with the Production Server Compiler app, see Create a Deployable Archive for MATLAB Production Server.

    Your server’s main_config file should point to where your MATLAB Runtime instance is installed.

  3. The server hosting your deployable archive must be running.

Manage Client Lifecycle

A single Java client connects to one or more servers available at various URLs. Even though you create multiple instances of MWHttpClient, one instance is capable of establishing connections with multiple servers.

Proxy objects communicate with the server until the close method of that instance is invoked.

For a locally scoped instance of MWHttpClient, the Java client code looks like the following:

 Locally Scoped Instance

When using a locally scoped instance of MWHttpClient, tie it to a servlet.

When using a servlet, initialize the MWHttpClient inside the HttpServlet.init() method, and close it inside the HttpServlet.destroy() method, as in the following code:

 Servlet Implementation

Handling Java Client Exceptions

The Java interface must declare checked exceptions for the following errors:

Java Client Exceptions

ExceptionReason for ExceptionAdditional Information
com.mathworks.mps.client.MATLABExceptionA MATLAB error occurred when a proxy object method was executed.

The exception provides the following:

  • MATLAB Stack trace

  • Error ID

  • Error message

java.io.IOException
  • A network-related failure has occurred.

  • The server returns an HTTP error of either 4xx or 5xx.

Use java.io.IOException to handle an HTTP error of 4xx or 5xx in a particular manner.

Managing System Resources

A single Java client connects to one or more servers available at different URLs. Instances of MWHttpClient can communicate with multiple servers.

All proxy objects, created by an instance of MWHttpClient, communicate with the server until the close method of MWHttpClient is invoked.

Call close only if you no longer need to communicate with the server and you are ready to release the system resources. Closing the client terminates connections to all created proxies.

Where to Find the Javadoc

The API doc for the Java client is installed in $MPS_INSTALL/client.