Using Flash Remoting MX
Using Flash Remoting Components in ActionScript

Handling service results

When the service function results return from the application server, event handlers use the returned data or handle the returned error information. For example, a result handler could display the results in the Flash application, and an error handler could set trace functions to report the error descriptions. This section describes how to handle result data. The section "Handling errors" describes how to handle error information.

Result-handling hierarchy

Flash Remoting MX supports the following hierarchy of event handling:

1. If you specify a responder object in the NetConnection object getService method, Flash Remoting MX does the following:
   1. If the responder has a function with a name of the form functionName_Result, where functionName is the name of the service function that you called, Flash Remoting MX returns the result for the function to that method.
   2. If the responder has a function named onResult, Flash Remoting MX returns the result for the function to that function.
2. If you specify a responder object in the service function call, Flash Remoting MX returns the result to that object's onResult method.

   Note:   Do not specify a responder object in the gatewayConnection.getService method and in the service function call. If you specify the responder in both places, Flash Remoting MX passes the responder you specify in the service function method to the service function as an argument. This behavior causes errors in your application.

3. When you test an application in Flash MX during development, if there is no appropriate responder object method, Flash displays the results in a message window.

Result-handling strategies

The different types of result handlers provide you with a variety of result-handling strategies you can use to match your application's needs. The following sections describe some of the techniques you can use:

• "Using the getService method to specify a responder"
• "Using the service function call to specify a responder"

Using the getService method to specify a responder

If you use the gatewayConnection.getService method to specify the responder object, you can use the following techniques:

• Specify an object, typically the main movie this object, as the responder in the gatewayConnection.getService method and create a separate _Result handler on the main movie timeline for each service function. Use this technique if all of the following conditions are true:
  • The results of calls to one function name must be handled differently from the results of calls to another function.
  • All functions in all services that require different handling have unique names. (For example, you do not use two services with identically named functions, such as myFirstService.myFunction and myOtherService.myFunction, that require different processing.)
  • The results of all calls to a particular function in a service can be handled by a single responder.
• Specify the main movie this object as the responder in the gatewayConnection.getService method and create an onResult method on the main movie timeline to handle some or all of the service function results. Use this technique if the results of all requests for all service functions can be handled in the same manner.
• Use a combination of the previous two techniques. Specify the main movie this object as the responder in the gatewayConnection.getService method, and create a separate _Result handler for some service functions. Create a single onResult result handler for the remaining service functions. Use this technique if the following are true:
  • The results of some service functions must be handled differently from the results of other service functions.
  • All functions in all services that require different handling have unique names.
  • The results of several service functions with different names can be handled in the same manner.
  • The results of all calls to a particular function can be handled by a single responder.

    For an example of this technique, see "Example: using a hierarchy of handlers" .

Example: using a hierarchy of handlers

The following example shows how you can use the main movie as the responder and have a common onResult result handler for some service functions, and function-specific functionName_Result handlers for other functions. In this example, there are two function-specific result handlers, getTemperature_Result and getForecast_Result, which display the returned temperature and forecast in specific text boxes. The default onResult response handler displays the result in a general-purpose message box.

// Initialization code, run once for each movie instance.

if (inited == null)
{
  inited = true;
  NetServices.setDefaultGatewayURL("http://localhost/flashservices/gateway")
  gatewayConnection = NetServices.createGatewayConnection();
  // Specify the main movie (this) as the default responder object.
  weatherService = gatewayConnection.getService("flashExamples.weatherStation",
    this); 
}

// Function-specific result handlers
function getTemperature_Result(temperature)
  { temperatureIndicator.text = temperature; }
function getForecast_Result(forecast)
{ forecastIndicator.text = forecast; }
// Default response handler
function onResult(result) 
  { generalMessageBox.text = result; }

// Call the service functions
weatherService.getTemperature("New York");
weatherService.getForecast("Chicago");
weatherService.getServiceStatus("San Francisco");
weatherService.getUsageStats();

Using the service function call to specify a responder

If you specify the responder when you call the service function methods, you can use the following techniques:

• Define a responder object. Populate the responder object with result handler functions, as described in any of the bullets in "Using the getService method to specify a responder". Pass a new instance of the responder object to the gatewayConnection.getService method.

  This technique is more object-oriented than using the this object as a responder, and lets you program using more encapsulated code than the techniques in "Using the getService method to specify a responder".

• Define several unique responder objects. Populate the responder objects with result-handler functions, as described in any of the bullets in "Using the getService method to specify a responder". Pass a new instance of one of these responder objects to each serviceName.functionName call you make.

  This technique lets you create function-specific responders where several services have the same function names but return different data. It also lets you create several different handlers that you can use, under different circumstances, with a single service function.

  For an example of this technique, see "Example: specifying unique result objects in service function calls" , next.

• Use a combination of the previous two methods: use some responder objects for multiple service functions and use unique responder objects for other service functions.

Example: specifying unique result objects in service function calls

The following example rewrites the example in the "Example: using a hierarchy of handlers" to have the service function calls specify result handlers. There are three response-handler objects: tempResult for the temperature, forecastResult for the forecast, and generalResult for other service functions. Each result handler has one function, onResult, to handle the result returned by the service.

// Initialization code, run once for each movie instance.

if (inited == null)
{
  inited = true;
  NetServices.setDefaultGatewayURL("http://localhost/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; }
}

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

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

// Call the service functions and specify the result handler as the first argument.
weatherService.getTemperature(new tempResult(), "New York");
weatherService.getForecast(new forecastResult(), "Chicago");
weatherService.getServiceStatus(new generalResult(), "San Francisco");
weatherService.getUsageStats(new generalResult());