Fusion Middleware Documentation
Advanced Search


Developing Mobile Applications with Oracle Mobile Application Framework
Close Window

Table of Contents

Show All | Collapse

18 Handling Errors in MAF Applications

This chapter describes how to use the AdfException class to handle errors and how to localize error messages.

This chapter includes the following sections:

18.1 About Error Handling for MAF

Errors arising from mobile applications might be unexpected, such as a failed connection to a remote server, or expected, such as a violation of an application business rule. Errors or exceptions might occur in the primary request thread or in a secondary thread that runs a background task. If the application supports multiple languages, then it must display the error message in the user's language.

To enable a mobile application to throw an exception, use oracle.adfmf.framework.exception.AdfException class. For more information, see Oracle Fusion Middleware Java API Reference for Oracle Mobile Application Framework.

The following code enables MAF to handle an exception gracefully. A popup message, similar to the one illustrated in Figure 18-1displays within the application and shows the message severity and explanatory text.

throw new AdfException("My error message",AdfException.ERROR);

Figure 18-1 An Error Message

This image is described in the surrounding text

Note:

Similar error messages display within application when the exception is thrown within a managed bean or a data control bean.

18.2 Displaying Error Messages and Stopping Background Threads

The MessageUtils class, illustrated in Example 18-1, enables an application to stop a thread and display an error by first making a JavaScript call (invokeContainerJavaScriptFunction) and then throwing an exception. The addMessage method enables the error to display. For more information, see Section 18.2.1, "How Applications Display Error Message for Background Thread Exceptions." See also Section B.2.14, "invokeContainerJavaScriptFunction."

The MessageUtils class uses the BundleFactory and Utility methods for retrieving the resource bundle and the error message and dynamically checks if a thread is running in the background. Using this class, you can move code from the main thread to the background thread.

Example 18-1 A MessageUtils Class

package oracle.errorhandling.demo.mobile;
 
import java.util.ResourceBundle;
 
import oracle.adfmf.framework.api.AdfmfContainerUtilities;
import oracle.adfmf.framework.api.AdfmfJavaUtilities;
import oracle.adfmf.framework.exception.AdfException;
import oracle.adfmf.util.BundleFactory;
import oracle.adfmf.util.Utility;
 
public class MessageUtils {

   public static void handleError(AdfException ex) {
      handleMessage(ex.getSeverity(), ex.getMessage());
   }

   public static void handleError(String message) {
      handleMessage(AdfException.ERROR, message);
   }
   public static void handleError(Exception ex) {
      handleMessage(AdfException.ERROR, ex.getLocalizedMessage());
   }

   public static void handleMessage(String severity, String message) {
      if (AdfmfJavaUtilities.isBackgroundThread()) {
         AdfmfContainerUtilities.invokeContainerJavaScriptFunction(AdfmfJavaUtilities.
                                                                   getFeatureName(),
                                                                   "adf.mf.api.amx.addMessage",
                                                                   new Object[] {severity,
                                                                                 null,
                                                                                 null});
         if (AdfException.ERROR.equals(severity)) {
            // we still need to throw execption to stop background thread processing
            throw new AdfException(message,severity);
         }
      }
      else {
         throw new AdfException(message,severity);
      }
   }

   public static void addJavaScriptMessage(String severity, String message) {
      AdfmfContainerUtilities.invokeContainerJavaScriptFunction(AdfmfJavaUtilities.
                                                                getFeatureName(),
                                                                "adf.mf.api.amx.addMessage",
                                                                new Object[] {severity,
                                                                              message,
                                                                              null,
                                                                              null });
   }

}

18.2.1 How Applications Display Error Message for Background Thread Exceptions

Applications do not display error messages when exceptions are thrown for background threads. To enable error messages to display under these circumstances, applications call the addMessage method. The addMessage method takes the following parameters:

  • The severity of the error

  • The summary message

  • The detail message

  • a clientComponentId.

Example 18-2 illustrates how you can enable the application to alert the user when an error occurs in the background by using the addMessage method.

Example 18-2 Allowing the Display of an Error Message for Background Threads

Runnable runnable = new Runnable()
{
  public void run() {
    AdfmfContainerUtilities.invokeContainerJavaScriptFunction(AdfmfJavaUtilities.getFeatureName(),
      "adf.mf.api.amx.addMessage", new Object[] {AdfException.ERROR, 
                                                 "My error message for background thread",
                                                 null,
                                                 null });
  }
};
Thread thread = new Thread(runnable);
thread.start();

Because the adf.mf.api.amx.addMessage JavaScript function is the same method that is used when the application throws AdfException in the primary request thread, users receive the same popup error message whether the error message is referring to exceptions in the main thread or from a background thread.

Note:

As illustrated in Example 18-2, the detail message and the clientComponentId can be a Null value. A detail message displays on a new line in the same font size as the summary message.

18.3 Localizing Error Messages

MAF uses standard Java resource bundles to display an exception error message in the language of the application user. As illustrated in Example 18-3, the resource bundle name (the .xlf file) and bundle message key is passed to the AdfException constructor method to enable the error message to be read from a resource bundle.

Example 18-3 Passing the Resource Bundle Name and Message Key to the AdfException Constructor Method

private static final String XLF_BUNDLE_NAME="oracle.errorhandling..mobile.ViewControllerBundle";
   throw new AdfException(AdfException.ERROR, XLF_BUNDLE_NAME,
                                             "MY_ERROR_MESSAGE",
                                              null);

To ensure that the application does not throw an MissingResourceException error, use the oracle.adfmf.util.BundleFactory method to retrieve the resource bundle and then use the oracle.adfmf.util.Utility method to retrieve the error message, as illustrated in Example 18-4.

Example 18-4 Using the BundleFactory and Utility Methods to Retrieve the Resource Bundle and Error Message

ResourceBundle bundle = BundleFactory.getBundle(XLF_BUNDLE_NAME);
String message = Utility.getResourceString(bundle, "MY_ERROR_MESSAGE",null);
throw new AdfException(message,AdfException.ERROR);

Example 18-5 illustrates using the adf.mf.api.amx.addMessage JavaScript function to display the localized error message when an exception is thrown from a background thread.

Example 18-5 Displaying an Localized Error Method for a Background Exception

ResourceBundle bundle = BundleFactory.getBundle(XLF_BUNDLE_NAME);
String message = Utility.getResourceString(bundle, "MY_ERROR_MESSAGE_BG",null);
AdfmfContainerUtilities.invokeContainerJavaScriptFunction(AdfmfJavaUtilities.
                                                          getFeatureName(),
                                                          "adf.mf.api.amx.addMessage",
                                                           new Object[] {AdfException.ERROR,
                                                                                      message,
                                                                                      null,
                                                                                      null });