The Web Service Classes | Foundation XML for Flash

The Web Service classes offer another alternative for consuming SOAP web services within Flash. These classes are only available in Flash Professional. One reason for using them is that theyll create smaller file sizes than if you use data components . Table 9-5 shows the classes included in the services package.

Table 9-5: The classes included in the services package
Class name	Purpose
WebService	Creates a WebService object to manage web service requests and responses. This is different from the WebServiceConnector class.
PendingCall	Returned when you make a web service call. The object manages the response and any faults reported .
Log	Tracks the consumption of a web service.
SOAPCall	Controls the way the web service operates.

Before you can use the Web Service classes, you need to add the WebServiceClasses component to your library. You can find this in Window Other Panels Common Libraries Classes . Drag the WebServiceClasses component to the Stage. Delete it and youll have added the WebServiceClasses component to your library.

Creating a WebService object

You can create a new WebService object with the following code. Replace URL to WSDL with the full URL to the WSDL document for the web service.

 var myWS:WebService = new WebService("URL to WSDL");

We can then specify the operation using a PendingCall object. You dont need to create it with a constructor method, as you would for other objects. Constructor methods use the keyword new . You create a PendingCall object by specifying the name of the operation and the parameters for the call.

 var pc:PendingCall = myWS.operationName(param1, param2, param3);

The pending call has two event handlers to deal with the results or faults from the web service: onResult and onFault . You can create a results handler function with the following code:

 pc.onResult = function(result:Object):Void {   //do something with the result; }

The result object is the response from the web service, converted into ActionScript. If you are returning a single value, you can refer to it with

 pc.result

If the returned value is an object containing other values, you can access them by using

 pc.result.propertyName;

You can use the Web Services panel to find out about the operations, parameters, and return values that youll get from the web service. Add the web service to the panel and youll be able to see the full details, including the operations and schemas for the parameters and results. We discussed this panel earlier in the chapter.

The following code shows how to set up an onFault event handler to track faults returned by the web service:

 pc.onFault = function(fault:Object):Void {   //do something with the fault }

You can use the faultString , faultCode , and details properties to find out more information about the fault.

Viewing the raw XML content

If you want to see the request or response XML information, you can use the request and response properties of the pending call:

 pc.request; pc.response;

You can display the values contained within the response using the onResult handler function:

 pc.onResult = function(result:Object):Void {   trace (this.response); };

Logging the details

The Log class allows you to see whats happening during the call to the web service. You can display each message from the web service.

You need to create a Log object using the following code:

 var WSLog:Log = new Log();

You can optionally include the level of logging required Log.BRIEF, Log.VERBOSE , or Log.DEBUG as well as a name for a log object, if youre using more than one WebService object. In most cases, using the Log constructor without parameters works well.

The Log object has an onLog event handler that you can use to display messages. In the following example, we use it to display messages in an Output window:

 WSLog.onLog = function(logInfo:String):Void {   trace (logInfo); }

You also need to add a reference to the Log object when you create your WebService object:

 var myWS:WebService = new WebService("URL to WSDL", WSLog);

Figure 9-35 shows the type of messages that you could expect to see.

Figure 9-35: Log messages shown in an Output window

Well use the code discussed in this section to create a simple application for converting temperatures between Celsius and Fahrenheit values.

Exercise 7: Using the Web Service classes to create a temperature converter

In the final exercise for this chapter, well use the Web Service classes to create a temperature conversion application. The conversion will use a web service and well provide two options: convert Fahrenheit to Celsius and convert Celsius to Fahrenheit.

Open Flash if necessary and open the starter file tempConvert.fla . Figure 9-36 shows the interface of the movie.

Figure 9-36: The Temperature converter interface

The interface contains two TextInput components and two Buttons . There are also three dynamic text fields for displaying messages.
Add the WebServiceClasses component to your library by selecting Window Other Panels Common Libraries Classes and dragging the WebServiceClasses component onto the Stage. Delete the component from the Stage.

Create a new layer called actions and add the following line on frame 1 to import the services classes. This will save you from having to use full class names each time you refer to a WebService class in your code.
```
 import mx.services.* 
```
Add the following code on the actions layer:
```
 var WSDL_URL:String = "http://developerdays.com/cgi-bin/ tempconverter.exe/wsdl/ITempConverter"; var WSLog:Log = new Log(); WSLog.onLog = function(logInfo:String):Void {   trace (logInfo); } 
```
The code creates a variable for the URL to the WSDL document for the web service. It also creates a new Log object and traces each log message in an Output window.

Configure the buttons by adding the following onRelease handler functions to the actions layer:

 celsius_btn.onRelease = function():Void {   clearText();   if (temp_txt.text.length > 0) {     if (!isNaN(temp_txt.text)) {         fromUnit_txt.text = "Fahrenheit";       toUnit_txt.text = "Celsius";       convertTemp("toC",temp_txt.text);     }     else {       error_txt.text="Enter a valid temperature";     }   }   else {    error_txt.text="Enter a temperature first";   } } fahrenheit_btn.onRelease = function():Void {   clearText();   if (temp_txt.text.length > 0) {     if (! isNaN(temp_txt.text)) {       convertTemp("toF",temp_txt.text);         fromUnit_txt.text = "Celsius";       toUnit_txt.text = "Fahrenheit";     }     else {     error_txt.text="Enter a valid temperature";     }   }   else {     error_txt.text="Enter a temperature first";   } }

The functions call the clearText function first and then validate the data entry. They set the text properties of the fromUnit_txt and toUnit_txt dynamic text fields. The functions either display appropriate error messages or call the convertTemp function. Note that Ive used isNaN to check for non-numeric entries.

Add the clearText function to the actions layer. This function clears the text showing in the TextInput components and the dynamic text fields.
```
 function clearText():Void {   endTemp_txt.text="";   error_txt.text="";   fromUnit_txt.text = "";   toUnit_txt.text = ""; } 
```
Create the call to the web service with the following code:
```
 function convertTemp(convDir:String, temp:Number):Void {   var myWS:WebService = new WebService(WSDL_URL, WSLog);   if (convDir == "toC") {     var pc:PendingCall = myWS.FtoC(temp);   }   else if (convDir == "toF") {     var pc:PendingCall = myWS.CtoF(temp);   }   pc.onResult = function(result:Object):Void {     endTemp_txt.text = result;   };   pc.onFault = function(fault:Object):Void {     error_txt.text = fault.faultstring;   }; } 
```
The function takes two parameters: the direction of the conversion and the temperature to convert. It creates a new WebService object that uses the WSDL_URL variable for the location of the WSDL document. The WebService will log messages to the WSLog object.

The code creates a PendingCall object that calls either the FtoC or CtoF operation. If the conversion is successful, the converted value displays in the endTemp_txt component; otherwise , the faultstring displays in the error_txt dynamic text field.
Test the movie by entering a temperature and clicking one of the conversion buttons. You should see messages displayed in an Output window, as shown in Figure 9-37. You should also see the converted temperature value displayed in the second TextInput component. Ive saved the completed resource file under the name tempConvert_completed.fla .

Figure 9-37: Log messages from the temperature conversion web service

In the previous example, we used the Web Service classes to connect to a temperature conversion web service. I showed you how to work with the WebService, PendingCall, and Log classes so that we didnt need to use any data components.

The exercise introduced you to the most common Web Service classes rather than providing a complete reference to all classes. We didnt cover the SOAPCall class or explore the details of all of the methods of each class. You can explore these topics in more detail on your own if youre interested.