Using Flash Remoting MX
Using Flash Remoting Components in ActionScript

Handling errors

Flash Remoting MX returns a Status event instead of a result if either of the following happens:

• The Flash Remoting gateway encounters an error.
• A service function encounters an error (throws an exception).

You write status event handlers to respond to the errors, typically by displaying an error message or logging the error information. In some cases, you might be able to include recovery code, such as code to retry a call to a busy server, in the error handler.

The error object

When Flash Remoting MX receives a Status event, Flash passes an error object that contains information about the error to the status event handler. The error object has the following format:

Key name	Contents
code	Currently, always "SERVER.PROCESSING".
level	Currently, always "Error".
description	A string that describes the error.
details	A stack trace that indicates the processing state at the time of the exception.
type	The error class name.
rootcause	A nested error object that contains additional information on the cause of the error. Provided only if a Java servletException is thrown.

Error-handling hierarchy

Flash Remoting MX supports the following hierarchy of error handling:

1. The initial error responder depends on whether you have specified the responder in the service function or the getService call:
   • If you specify the responder in the getService call, the following happens:

     a. If the responder has a function with a name of the form functionName_Status, where functionName is the name of the service function that you called, Flash Remoting MX returns the status information for the function to that method.

     b. If the default responder object specified in the getService call has a function named onStatus, Flash Remoting MX returns the status to that function.

   • If you specify a responder object in the service function call, Flash Remoting MX returns the status to that object's onStatus method. When you use this technique, the responder object must also have an onResult method to handle the error.
2. If there is a function called _root.onStatus, Flash Remoting MX returns the status to that function.
3. If there is a function called _global.System.onStatus, Flash Remoting MX returns the status to that function.
4. During development, Flash displays the status information in a message window.

This hierarchy adds two levels, items 2 and 3, to the result-handling scheme described in "Result-handling hierarchy". As a result, you can define handlers for all otherwise-unhandled status events on a level or in the entire application.

Error-handling strategies

Flash applications use error-handling code less often than server applications, because Flash does not report errors to the user when viewing movies. However, Flash Remoting MX does make error information available to the movie ActionScript, and your application can use this information. The error handling hierarchy lets you handle errors with any degree of granularity. For example:

• You can use a global error handler to log error information if the status event cannot be otherwise handled.
• You can display a message to the user in response to specific functions or specific errors returned by specific functions.

Error handling can be particularly useful for remote services, because the user's experience depends on remote data that might not always be retrieved, and it might not be obvious that data is not retrieved. Also, in some cases, the error-handling code can even recover from a transient error. For example, if a service function fails due to a time-out, it might be appropriate for the Flash application to try the request a second time. If the request fails a second time, the movie could then display a message to the user and post a message to the server to log the error.

The following section, "Example: error handling using unique result objects" shows how you can apply error handling to a Flash Remoting MX application. For more information about selecting from the status event-handling hierarchy, see "Result-handling strategies", which discusses strategies for selecting from the similar result-handling hierarchy.

Example: error handling using unique result objects

The following example adds error handling to the example in the "Example: specifying unique result objects in service function calls". The error handlers for the temperature and forecast display custom messages to the user. The general error handler displays a generalized message. All handlers call a function to report the error to a log on the server.

#include "NetServices.as"

#include "NetDebug.as" 

// Initialization code, run once for each movie instance.
if (inited == null)
{
  inited = true;
  NetServices.setDefaultGatewayURL("http://apps.myco.com/flashservices/gateway")
  gatewayConnection = NetServices.createGatewayConnection();
  // Do not specify a default responder object when creating the service object.
  weatherService = gatewayConnection.getService("flashExamples.weatherStation"); 
}

// Temperature result handler object
function tempResult()
{ 
  this.onResult = function(temperature)
  { 
    temperatureIndicator.text = temperature;
  }

  this.onStatus = function (status)
  { 
    temperatureIndicator.text = "No Temperature Available"; 
    _global.logStatus(Status);
  }
}

//Forecast result handler object
function forecastResult()
{
  this.onResult = function (forecast)
  { forecastIndicator.text = forecast; }

  this.onStatus = function (status)
  { 
    forecastIndicator.text = "No Forecast Available"; 
    _global.logStatus(Status);
  }
}

// General result handler object
function generalResult ()
{
  this.onResult = function (result) 
  { generalMessageBox.text = result; }

  this.onStatus = function (status)
  { 
    generalMessageBox.text = "An error occurred. Please try later"; 
    _global.logStatus(Status);
  }
}

// Call the service functions and specify the result handler as the first argument.
// In a real application, these calls would be initiated by user actions in the 
// Flash application.
weatherService.getTemperature(new tempResult(), "New York" );
weatherService.getForecast(new forecastResult(), "Chicago" );
weatherService.getServiceStatus( new generalResult(), "San Francisco" );
weatherService.getUsageStats(new generalResult());

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/flashremoting/mx/Using_Flash_Remoting_MX/UseActionScript8.htm

Add Comment