Using XML in Flex - Tutorial Part 4 - WebService

Flex provides an ActionScript 3.0 class named WebService and a MXML component named WebService. My references for this tutorial are the Adobe Flex 2 Language Reference, Programming ActionScript 3.0, and the Flex 2 Developer's Guide.

The WebService class and component can be used to access SOAP-based web services. For more information on SOAP-based web services see: http://www.w3schools.com/soap/default.asp.

WebService Class

Let's examine the ActionScript 3.0 WebService class first and provide an example of how to use it. The WebService class exposes several properties and methods. One of the more important properties is wsdl, which is the location of the Web Service Description Language (WSDL) document for the web service. The WSDL document details the services provided by the web service, what inputs are required to use the service, and what outputs the service returns. A detailed description of WSDL is here: http://www.w3.org/TR/wsdl.

My example for this tutorial uses the USZip WebService provided by www.webservicex.net

To use the WebService class you will need this information:

1. WSDL - for example http://www.webservicex.net/uszip.asmx?wsdl
2. Method Name - for example GetInfoByCity
3. Method Parameters - for example USCity
4. NameSpace (if you want results formatted in e4x XML) - for example http://www.webserviceX.NET (see page 1150 in Flex 2.0 Developer's Guide)

If you examine the WSDL and the SOAP envelope returned you can find the information needed above. The USZip webservice has four methods we can use. In my example I use the GetInfoByCity method. You provide this method the name of a US city and it returns an XML document with the city, state, zip, area code, and time zone. If you examine the complete results returned, you will see that the response specifies an XML namespace of http://www.webserviceX.NET. To properly use the results formatted in e4x XML, you will need to create a namespace object and use it in your Flex app (see page 1150 in the Flex 2.0 Developer's Guide).

After you've created the WebService object, you specify the values for its properties, such as WSDL and resultFormat (e4x). You also specify which functions will handle the result and fault events by using your object name.the webservice method name.addEventListener(...). For example:

WS.GetInfoByCity.addEventListener("result", resultHandler);

The above code specifies that a function named resultHandler will handle the result event for method GetInfoByCity.

One of the event handlers you specify is for the load event. The load event is triggered when the WebService has completed loading the WSDL. Inside the function you specified as handling the load event is where you can call the WebService method. You pass any arguments to the WebService's methods inside the parenthesis:

//call the WebService method GetInfoByCity
WS.GetInfoByCity(city.selectedLabel);

In the above, I'm sending to the WebService method the user's selection in the city combo box.

In the resultHandler function I refer to the XML returned by the webservice method using the dot notation I discussed in tutorial 1.

WS.GetInfoByCity.lastResult is the XML document returned

WS.GetInfoByCity.lastResult.GetInfoByCityResult.NewDataSet.Table[0].ZIP gets the value for the ZIP node that is a child of the first Table element that is a child of the NewDataSet element, that is a child of the GetInfoByCityResult element.

To view the example click here. You can right click on the example to view the source code.

mx:WebService MXML Tag

Instead of the ActionScript 3.0 WebService class you can use the WebService MXML tag. When you use the mx:WebService tag you specify the WSDL and the id value (used to refer to the component later). Inside the mx:WebService tag you use an mx:operation tag to identify the webservice method you want to use and the resultFormat for the data returned by the method. Inside the mx:operation tag you use an mx:request tag to specify the values for the method's parameters. The elements inside the mx:request tag should be named to match the parameter names specified by the webservice method.

To make the call to the webservice method, you use the id value.the method name.send(). For example:

WS.GetInfoByCity.send() (where WS is the id value for the mx:WebService component)

Once the results are returned by the webservice you can bind them to various MXML components. Again you can use the dot notation to get the value of a specific element. You can also use the XML returned to populate a DataGrid.

See the mx:WebService example and right click on it to view the source.

Please post any suggestions for improving this tutorial or questions about areas that I've not properly covered.