Adding Web Services

Flex Builder makes it easy to add named and unnamed web services to an application by exposing the Flex whitelist.

1. Open the Data panel by selecting Window > Data (Ctrl + Shift + F7).
2. To add a service, click the Plus (+) button in the Data panel and choose Web Service.

3. In the pop-up menu, see all of the named and unnamed web services that have been configured in the Flex whitelist (Figure 1).

   

   Figure 1. The Data panel.

   The named service, SampleEmployeeWS, is one of the services displayed in the list. Named web services allow you to reference web services with simple names instead of using web service WSDL URLs. Entries in the flex-config.xml file map named web services to the web service details, such as the WSDL URL and the type of authentication. This means that web service references in your applications aren’t hard coded. You can also set up named services for HTTP services and Remote Objects.

4. Select the named service SampleEmployeeWS from the Add WebService pop-up menu (Figure 2).

Figure 2. The Add WebService dialog box.

Note: In the pop-up menu, you might see entries that contain { } or * syntax. These indicate global filters. Consider these indicators as acceptable URL formats. For example http://{localserver}/* indicates any web service running on the local server, and is legal. For more information on whitelists, see Configuring the whitelist for Flex applications (TechNote 19251).

Once you have added the service to the application, the web service operations, operation parameters, and operation result objects display in the Data panel (Figure 3).

Figure 3. The Data panel with a web service.

In the next sections you learn how to:

• Create a binding to the web service operation parameters
• Create a binding from the web service operation result to a component
• Create an event that invokes the web service operation

Binding a Component to a Web Service Request

Use the following steps to bind the dept ComboBox to the getList operation’s parameter deptId.

1. Select the pre-populated ComboBox in Design view.
2. Open the Tag Inspector by selecting Window > Tag Inspector (F9) and selecting the Bindings tab.

3. Click the Plus (+) button. This displays the Add Binding - Step 1 dialog box.

   In the Add Binding dialog box, you must select the binding direction and a property to bind to. The binding direction specifies how data will flow. Data can flow FROM the selected component (an out binding), or TO the selected component (an in binding). When you select a direction radio button, the default property for the direction displays in the selected component properties list. The selected component properties are a list of properties that are bindable for the selected component. The list of component properties changes depending upon the binding direction. When the direction is TO (or in), the write and read/write properties of the selected component display. When the direction is FROM (or out), the read and read/write properties of the selected component display.

   For this binding, data needs to flow from a ComboBox property to the web service operation’s argument. Select the radio button to the left of “Data will flow FROM ‘dept’". The selectedItem is the default property of the ComboBox, so it is selected by default in the list of properties; it also displays in the Binding Source field at the bottom of the dialog box. The selectedItem property of the ComboBox is an object composed of a data and a label. In this case, you must bind to the data field. Type .data at the end of the selectedItem property in the Binding source text field so that it is: selectedItem.data. Click Next.

   

   Figure 4. The Add Binding – Step 1 dialog box with FROM selected.

4. The second bindings dialog box appears. This dialog box contains a list of components that are in the MXML application and a list of component properties that can be bound TO or FROM.

   If you select FROM in the initial binding dialog box, the binding is TO the component property you select in the secondary dialog box. Data will flow from the component property you selected in the initial dialog to the component property you select in the second bindings dialog box.

   Conversely, if you select TO in the initial binding dialog box, then the binding is FROM the component property you select in the secondary dialog box. Data will flow to the component property you selected in the initial dialog box from the component property you select in the second binding's dialog box.

   When you select TO (or in) in the initial binding dialog box, the secondary dialog box’s component property list displays read and read/write properties. When the direction is FROM or out in the initial binding dialog box, the secondary dialog box’s component property list displays write and read/write properties.

   For this binding, data needs to flow to the web service operation’s deptId argument. Select the web service service1 in the “Data will flow TO “ tree on the left.

5. Expand the getList operation and its request object in the “Selected component property” tree and select the deptId argument. The Binding destination displays service1.getList.request.deptId.

   

   Figure 5. The Add Binding – Step 2 dialog box displaying TO.

6. Click Finish. This creates the binding between the ComboBox and the web service operation argument. Look in Code view. See the generated code:

    <mx:WebService serviceName="SampleEmployeeWS" id="service1">
         <mx:operation name="getList">
           <mx:request>
             <deptId>{dept.selectedItem.data}</deptId>
           </mx:request>
         </mx:operation>
   </mx:WebService>
   

   In Code or Design view, when you select a component with a binding, the component icon, name (or type), and bindings display in the Bindings panel. Selecting the binding in the Bindings panel causes binding direction to display in the Direction field and the component property that the binding is TO or FROM to display the Bound to field. Double-click the binding to edit the full binding. Clicking the Bound to field makes the second binding dialog box appear so that you can edit it.

   When you select the ComboBox in Code or Design view, the selectedItem.data binding displays in the Bindings panel. Selecting the binding displays the direction as out and the Bound to field displays service1.getList.request.deptId. When you select the web service, service1, in the Data panel, getList.request.deptId displays in the Bindings panel. Selecting the binding displays the direction as in and the Bound to field displays dept.selectedItem.data.

   

   Figure 6. The Bindings panel when you select the ComboBox binding

   

   Figure 7. The Bindings panel when you select the web service binding

Binding a Component To a Web Service Result

To display the result of your web service operation call, you must create a binding from the web service result to a component property. This is a similar process to the previous binding, but the direction is opposite. The data needs to flow to the component property from the web service operation result instead of from the component property to the web service operation request.

1. Select the DataGrid component in Design view and click the Plus (+) button in the Bindings panel. This displays the Add Binding - Step 1 dialog box.
2. The web service result data needs to flow to the DataGrid. Select the "Data will flow TO <mx:DataGrid>" radio button if it hasn't been selected. The default property, dataProvider, is selected in the Component property list.
3. Notice that the binding syntax displays in the Binding Destination field at the bottom of the dialog box as dataProvider.

4. Click Next to go to the second binding dialog box.

   

   Figure 8. The Add Binding – Step 1 dialog with TO selected.

5. In the second bindings dialog box, select the web service service1 in the “Data will flow FROM…” tree.
6. Expand the getList operation in the selected component property tree.

7. Since the DataGrid dataProvider property expects an array, select the result:(Array) node under the getList operation. The Bindings source at the bottom of the dialog box displays service1.getList.result.

   

   Figure 9. The Add Binding – Step 2 dialog displaying FROM.

8. Click Finish. The Binding icon now appears in Design view

9. Go to Code view. Notice the added binding in the DataGrid’s dataProvider property:

   <mx:DataGrid widthFlex="1" dataProvider="{service1.getList.result}">
   

Invoking a Web Service from Component Events

Now that you have set up bindings to the web service operation arguments and result object, you must set up an event that invokes/calls the web service operation. You invoke web services with ActionScript code.

For this exercise, the ActionScript will execute when a Button fires a click event; web service operations can be fired from any component event.

 
Using the Network Monitor To See SOAP Messages and ActionScript Objects
Now that you have set up the bindings and the trigger, it is time to test the application. The Network Monitor helps you debug Flex applications that use data services such as web services, Remote Objects, or HTTP. With the Network Monitor, you can examine the SOAP, AMF, Remote Object, XML, and HTTP traffic as it flows between the Flex application and the data service or services. 
The Network Monitor also supports simple trace statements for basic application debugging. Network Monitor traces, such as the one below, display in the Network Monitor at runtime. 
NetworkDebugger.NetworkMonitor.trace('trace text goes here');
  
Select Window > Network Monitor (Ctrl + Alt + N) to open the Network Monitor.
Select the Enable Flex Network Monitor checkbox to activate the Network Monitor.
 
Figure 12. The Network Monitor in the enabled state.
Choose File > Run (F6) or click the Run button on the toolbar to preview the application. As the application loads, see the entries appear in the Network Monitor. 
In testing this sample application, you aren’t interested in the HTTP traffic, so select the filter icon and deselect HTTP.
Note: You do not lose the data when you deselect a filter, you only hide it. If you need the data, simply select the filter.
 
Figure 13. The Network Monitor after selecting Run, with filtering button selected
Because you have filtered out the HTTP traffic, you will see the following web service events:
First, the initialization of the web service where the web service WSDL is requested 
Second, the WSDL that is received in response to the WSDL request
Select Product Management in the ComboBox and click the Get Employee List Button to trigger the web service operation. Notice that a few SOAP and web service events appear.
Selecting the first SOAP event displays the SOAP envelope sent to the web service in the details pane.
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <SOAP-ENV:Body xmlns:ns1="http://localhost:8400/samples/services/EmployeeWS">
      <ns1:getList SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <deptId xsi:type="xsd:string">PM</deptId>
      </ns1:getList>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Selecting the first web service RPC event displays the SOAP envelope as represented in ActionScript.
Method: getList
Parameter 1:
name : deptId
type : string
value : PM
Selecting the second SOAP event displays the SOAP envelope received from the web service in response to the web service call.
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Body>
      <ns1:getListResponse xmlns:ns1="http://localhost:8300/samples/services/EmployeeWS" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <getListResult xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="xsd:anyType[2]">
            <item href="#id0"/>
            <item href="#id1"/>
         </getListResult>
      </ns1:getListResponse>
      <multiRef xmlns:ns2="http://www.macromedia.com/samples" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" id="id0" SOAP-ENC:root="0" xsi:type="ns2:Employee">
         <name xsi:type="xsd:string">Ronnie Hodgman</name>
         <phone xsi:type="xsd:string">555-219-2030</phone>
         <email xsi:type="xsd:string">rhodgman@fictitious.com</email>
         <salary xsi:type="xsd:double">0.0</salary>
      </multiRef>
      <multiRef xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:ns3="http://www.macromedia.com/samples" id="id1" SOAP-ENC:root="0" xsi:type="ns3:Employee">
         <name xsi:type="xsd:string">Joanne Wall</name>
         <phone xsi:type="xsd:string">555-219-2012</phone>
         <email xsi:type="xsd:string">jwall@fictitious.com</email>
         <salary xsi:type="xsd:double">0.0</salary>
      </multiRef>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Selecting the second web service RPC event displays the response to the web service call as represented in ActionScript.
[array] : 
length[Number] : 2
[0][object] : 
SOAP-ENC:root[String] : 0
email[String] : rhodgman@fictitious.com
id[String] : id0
name[String] : Ronnie Hodgman
phone[String] : 555-219-2030
salary[Number] : 0
xmlns:SOAP-ENC[String] : http://schemas.xmlsoap.org/soap/encoding/
xmlns:ns2[String] : http://www.macromedia.com/samples
xsi:type[String] : ns2:Employee

[1][object] : 
SOAP-ENC:root[String] : 0
email[String] : jwall@fictitious.com
id[String] : id1
name[String] : Joanne Wall
phone[String] : 555-219-2012
salary[Number] : 0
xmlns:SOAP-ENC[String] : http://schemas.xmlsoap.org/soap/encoding/
xmlns:ns3[String] : http://www.macromedia.com/samples
xsi:type[String] : ns3:Employee
 
Figure 14. The Network Monitor after with the web service ActionScript object selected.
Developing and debugging applications can be time consuming. As you have seen, with Flex Builder’s visual data binding you can quickly wire together simple Flex applications. The Network Monitor eases the process of debugging data services in Flex applications, making you more productive.