Error Handling

Error Overview

Errors that occur during execution of a MATLAB® function or during data conversion are signaled by a standard Java® exception. This includes MATLAB run-time errors as well as errors in your MATLAB code.

Handle Checked Exceptions

Checked exceptions must be declared as thrown by a method using the throws clause. MATLAB Compiler SDK™ Java packages support the com.mathworks.toolbox.javabuilder exception.MWException. This exception class inherits from java.lang.Exception and is thrown by every MATLAB Compiler SDK generated Java method to signal that an error has occurred during the call. All normal MATLAB run-time errors, as well as user-created errors (e.g., a calling error in your MATLAB code) are manifested as MWExceptions.

The Java interface to each MATLAB function declares itself as throwing an MWException using the throws clause. For example, the myprimes MATLAB function shown previously has the following interface:

/* mlx interface - List version */
public void myprimes(List lhs, List rhs) throws MWException
{
    (implementation omitted)
}
/* mlx interface - Array version */
public void myprimes(Object[] lhs, Object[] rhs) 
                               throws MWException
{
    (implementation omitted)
 }
/* Standard interface - no inputs*/
public Object[] myprimes(int nargout) throws MWException
   {
      (implementation omitted)
   }
/* Standard interface - one input*/
public Object[] myprimes(int nargout, Object n) 
                                     throws MWException
   {
      (implementation omitted)
   }

Any method that calls myprimes must do one of two things:

  • Catch and handle the MWException.

  • Allow the calling program to catch it.

The following two sections provide examples of each.

Handle Exception in Called Function

The getprimes example shown here uses the first of these methods. This method handles the exception itself and does not need to include a throws clause at the start.

public double[] getprimes(int n)
{
   myclass cls = null;
   Object[] y = null;

   try
   {
      cls = new myclass();
      y = cls.myprimes(1, Double.valueOf((double)n));
      return (double[])((MWArray)y[0]).getData();
   }

   /* Catches the exception thrown by myprimes */
   catch (MWException e)
   {
      System.out.println("Exception: " + e.toString());
      return new double[0];
   }

   finally
   {
      MWArray.disposeArray(y);
      if (cls != null)
         cls.dispose();
   }
}

Note that in this case, it is the programmer's responsibility to return something reasonable from the method in case of an error.

The finally clause in the example contains code that executes after all other processing in the try block is executed. This code executes whether or not an exception occurs or a control flow statement like return or break is executed. It is common practice to include any cleanup code that must execute before leaving the function in a finally block. The documentation examples use finally blocks in all the code samples to free native resources that were allocated in the method.

For more information on freeing resources, see Manage MATLAB Resources in JVM.

Handle Exception in Calling Function

In this next example, the method that calls myprimes declares that it throws an MWException:

public double[] getprimes(int n) throws MWException
{
   myclass cls = null;
   Object[] y = null;

   try
   {
      cls = new myclass();
      y = cls.myprimes(1, Double.valueOf((double)n));
      return (double[])((MWArray)y[0]).getData();
   }

   finally
   {
      MWArray.disposeArray(y);
      if (cls != null)
      cls.dispose();
   }
}

Handle Unchecked Exceptions

Several types of unchecked exceptions can also occur during the course of execution. Unchecked exceptions are Java exceptions that do not need to be explicitly declared with a throws clause. The MWArray API classes all throw unchecked exceptions.

All unchecked exceptions thrown by MWArray and its subclasses are subclasses of java.lang.RuntimeException. The following exceptions can be thrown by MWArray:

  • java.lang.RuntimeException

  • java.lang.ArrayStoreException

  • java.lang.NullPointerException

  • java.lang.IndexOutOfBoundsException

  • java.lang.NegativeArraySizeException

This list represents the most likely exceptions. Others might be added in the future.

Catching General Exceptions

You can easily rewrite the getprimes example to catch any exception that can occur during the method call and data conversion. Just change the catch clause to catch a general java.lang.Exception.

public double[] getprimes(int n)
{
   myclass cls = null;
   Object[] y = null;

   try
   {
      cls = new myclass();
      y = cls.myprimes(1, Double.valueOf((double)n));
      return (double[])((MWArray)y[0]).getData();
   }

   /* Catches the exception thrown by anyone */
   catch (Exception e)
   {
      System.out.println("Exception: " + e.toString());
      return new double[0];
   }

   finally
   {
      MWArray.disposeArray(y);
      if (cls != null)
         cls.dispose();
   }
}

Catching Multiple Exception Types

This second, and more general, variant of this example differentiates between an exception generated in a compiled method call and all other exception types by introducing two catch clauses as follows:

public double[] getprimes(int n)
{
   myclass cls = null;
   Object[] y = null;

   try
   {
      cls = new myclass();
      y = cls.myprimes(1, Double.valueOf((double)n));
      return (double[])((MWArray)y[0]).getData();
   }

   /* Catches the exception thrown by myprimes */
   catch (MWException e)
   {
      System.out.println("Exception in MATLAB call: " +
         e.toString());
      return new double[0];
   }

   /* Catches all other exceptions */
   catch (Exception e)
   {
      System.out.println("Exception: " + e.toString());
      return new double[0];
   }

   finally
   {
      MWArray.disposeArray(y);
      if (cls != null)
         cls.dispose();
   }
}

The order of the catch clauses here is important. Because MWException is a subclass of Exception, the catch clause for MWException must occur before the catch clause for Exception. If the order is reversed, the MWException catch clause never executes.

Alternatives to Using System.exit

Any Java application that uses a class generated using MATLAB Compiler SDK should avoid any direct or indirect calls to System.exit.

Any direct or indirect call to System.exit will result in the JVM shutting down in an abnormal fashion. This may result in system deadlocks.

Using System.exit also causes the java process to exit unpredictably.

Java programs using Swing components are most likely to invoke System.exit. Here are a few ways to avoid it:

  • Use public interface WindowConstants.DISPOSE_ON_CLOSE method as an alternative to WindowConstants.EXIT_ON_CLOSE as input to the JFrame class setDefaultCloseOperation method.

  • If you want to provide an Exit button in your GUI that terminates your application, instead of calling System.exit in the ActionListener for the button, call the dispose method on JFrame.