HTTP services and web services

When you use explicit parameter passing with an HTTPService component, you specify an object that contains name-value pairs as an argument to the send() method. A send() method parameter must be a simple base type such as Object. You cannot use complex nested objects because there is no generic way to convert them to name-value pairs.

The following examples show two ways to call an HTTP service using the send() method with a parameter.

<?xml version="1.0"?> 
<!-- ds\rpc\RPCSend.mxml --> 
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"> 
 
    <mx:Script> 
        <![CDATA[ 
            public function callService():void { 
                var params:Object = new Object(); 
                params.param1 = 'val1'; 
                myService.send(params); 
            } 
        ]]> 
    </mx:Script> 
 
    <mx:HTTPService 
        id="myService" 
        destination="catalog" 
        useProxy="true"/> 
        
    <!-- HTTP service call with a send() method that takes 
      a variable as its parameter. The value of the variable is an Object. -->     
    <mx:Button label="send() with variable" click="myService.send({param1: 'val1'});"/> 
    
    <!-- HTTP service call with an object as a send() method parameter 
      that provides query parameters. -->      
    <mx:Button label="send() with query params" click="callService();"/> 
</mx:Application>

When using the WebService component, you call a service by directly calling the service method, or by calling the Operation.send() method of the Operation object that represents the operation. When you use explicit parameter passing, you specify the parameters as arguments to the method that you use to invoke the operation.

The following example shows MXML code for declaring a WebService component and calling a service using explicit parameter passing in the click event listener of a Button control. A ComboBox control provides data to the service, and event listeners handle the service-level result and fault events:

<?xml version="1.0"?> 
<!-- ds\rpc\RPCParamPassingWS.mxml --> 
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"> 
    
    <mx:Script> 
        <![CDATA[ 
            import mx.controls.Alert; 
        ]]> 
    </mx:Script> 
 
    <mx:WebService 
        id="employeeWS" 
        destination="SalaryManager"/> 
 
    <mx:ComboBox id="dept" width="150"> 
        <mx:dataProvider> 
            <mx:ArrayCollection> 
                <mx:source> 
                    <mx:Object label="Engineering" data="ENG"/> 
                    <mx:Object label="Product Management" data="PM"/> 
                    <mx:Object label="Marketing" data="MKT"/> 
                </mx:source> 
            </mx:ArrayCollection> 
        </mx:dataProvider> 
    </mx:ComboBox> 
 
    <mx:Button label="Get Employee List" 
        click="employeeWS.getList(dept.selectedItem.data);"/> 
</mx:Application>

Parameters to an HTTPService component correspond to query parameters of the requested URL. When an HTTP service takes query parameters, you can specify them by using the request property. The request property takes an Object of name-value pairs used as parameters to the URL. The names of the properties must match the names of the query parameters that the service expects. If the HTTPService.contentType property is set to application/xml, the request property must be an XML document.

When you use parameter binding, you call a service by using the send() method but specify no arguments to the method. The HTTPService component automatically adds the parameters specified by the request property to the request.

The following example binds the selected data of a ComboBox control to the request property:

<?xml version="1.0"?> 
<!-- ds\rpc\HttpServiceParamBind.mxml. Compiles --> 
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"> 
 
    <mx:HTTPService 
        id="employeeSrv" 
        destination="catalog"> 
        <mx:request> 
            <deptId>{dept.selectedItem.data}</deptId> 
        </mx:request> 
    </mx:HTTPService> 
 
    <mx:HBox> 
        <mx:Label text="Select a department:"/> 
        <mx:ComboBox id="dept" width="150"> 
            <mx:dataProvider> 
                <mx:ArrayCollection> 
                    <mx:source> 
                        <mx:Object label="Engineering" data="ENG"/> 
                        <mx:Object label="Product Management" data="PM"/> 
                        <mx:Object label="Marketing" data="MKT"/> 
                    </mx:source> 
                </mx:ArrayCollection> 
            </mx:dataProvider> 
        </mx:ComboBox> 
        <mx:Button label="Get Employee List" click="employeeSrv.send();"/> 
    </mx:HBox> 
 
    <mx:DataGrid dataProvider="{employeeSrv.lastResult.employees.employee}" 
        width="100%"> 
        <mx:columns> 
            <mx:DataGridColumn dataField="name" headerText="Name"/> 
            <mx:DataGridColumn dataField="phone" headerText="Phone"/> 
            <mx:DataGridColumn dataField="email" headerText="Email"/> 
        </mx:columns> 
    </mx:DataGrid> 
</mx:Application>

When you use parameter binding with a WebService component, you typically declare an operation by using the operation property. Each operation property corresponds to an instance of the Operation class, which defines a request property that contains the XML nodes that the operation expects.

The following example binds the data of a selected ComboBox item to the getList() operation. When you use parameter binding, you call a service by using the send() method with no arguments:

<?xml version="1.0"?> 
<!-- ds\rpc\WebServiceParamBind.mxml --> 
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"> 
 
    <mx:Script> 
        <![CDATA[ 
            import mx.utils.ArrayUtil; 
            import mx.controls.Alert; 
        ]]> 
    </mx:Script> 
 
    <mx:ArrayCollection 
        id="employeeAC" 
        source="{ArrayUtil.toArray(employeeWS.getList.lastResult)}"/> 
 
    <mx:WebService 
        id="employeeWS" 
        destination="wsDest" 
        showBusyCursor="true" 
        fault="Alert.show(event.fault.faultString);"> 
        <mx:operation name="getList"> 
            <mx:request> 
                <deptId>{dept.selectedItem.data}</deptId> 
            </mx:request> 
        </mx:operation> 
    </mx:WebService> 
 
    <mx:HBox> 
        <mx:Label text="Select a department:"/> 
        <mx:ComboBox id="dept" width="150"> 
            <mx:dataProvider> 
                <mx:ArrayCollection> 
                    <mx:source> 
                        <mx:Object label="Engineering" data="ENG"/> 
                        <mx:Object label="Product Management" data="PM"/> 
                        <mx:Object label="Marketing" data="MKT"/> 
                    </mx:source> 
                </mx:ArrayCollection> 
            </mx:dataProvider> 
        </mx:ComboBox> 
        <mx:Button label="Get Employee List" click="employeeWS.getList.send();"/> 
    </mx:HBox> 
 
    <mx:DataGrid dataProvider="{employeeAC}" width="100%"> 
        <mx:columns> 
                <mx:DataGridColumn dataField="name" headerText="Name"/> 
                <mx:DataGridColumn dataField="phone" headerText="Phone"/> 
                <mx:DataGridColumn dataField=" to email" headerText="Email"/> 
        </mx:columns> 
    </mx:DataGrid> 
</mx:Application>

You can manually specify an entire SOAP request body in XML with all of the correct namespace information defined in the request property. Set the value of the format attribute of the request property to xml, as the following example shows:

<?xml version="1.0"?> 
<!-- ds\rpc\WebServiceSOAPRequest.mxml --> 
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" verticalGap="10"> 
    <mx:WebService id="ws" wsdl="http://api.google.com/GoogleSearch.wsdl" 
        useProxy="true"> 
        <mx:operation name="doGoogleSearch" resultFormat="xml"> 
            <mx:request format="xml"> 
                <ns1:doGoogleSearch xmlns:ns1="urn:GoogleSearch" 
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                    xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
                    <key xsi:type="xsd:string">XYZ123</key> 
                    <q xsi:type="xsd:string">Balloons</q> 
                    <start xsi:type="xsd:int">0</start> 
                    <maxResults xsi:type="xsd:int">10</maxResults> 
                    <filter xsi:type="xsd:boolean">true</filter> 
                    <restrict xsi:type="xsd:string"/> 
                    <safeSearch xsi:type="xsd:boolean">false</safeSearch> 
                    <lr xsi:type="xsd:string" /> 
                    <ie xsi:type="xsd:string">latin1</ie> 
                    <oe xsi:type="xsd:string">latin1</oe> 
                </ns1:doGoogleSearch> 
            </mx:request> 
        </mx:operation> 
    </mx:WebService> 
</mx:Application>

Some web services require that you pass a SOAP header when you call an operation. Add a SOAP header to all web service operations or individual operations by calling the addHeader() or addSimpleHeader() method of the WebService or Operation object.

When you use the addHeader() method, you first create SOAPHeader and QName objects separately. The addHeader() method has the following signature:

addHeader(header:mx.rpc.soap.SOAPHeader):void

To create a SOAPHeader object, you use the following constructor:

SOAPHeader(qname:QName, content:Object)

The content parameter of the SOAPHeader() constructor is a set of name-value pairs based on the following format:

{name1:value1, name2:value2}

To create the QName object in the first parameter of the SOAPHeader() method, you use the following constructor:

QName(uri:String, localName:String)

The addSimpleHeader() method is a shortcut for a single name-value SOAP header. When you use the addSimpleHeader() method, you create SOAPHeader and QName objects in parameters of the method. The addSimpleHeader() method has the following signature:

addSimpleHeader(qnameLocal:String, qnameNamespace:String, headerName:String, 
    headerValue:Object):void

The addSimpleHeader() method takes the following parameters:

• qnameLocal is the local name for the header QName.

• qnameNamespace is the namespace for the header QName.

• headerName is the name of the header.

• headerValue is the value of the header. This value can be a String if it is a simple value, an Object that undergoes basic XML encoding, or XML if you want to specify the header XML yourself.

The following calls to the addSimpleHeader() and addSimpleHeader() methods are equivalent:

addHeader(new Qname(qNs,qLocal), {name:val}); 
addSimpleHeader(qLocal, qNs, name, val);

Both methods add a SOAPHeader object to a collection of headers. Each SOAPHeader is encoded as follows:

<qnamePrefix:qnameLocal> 
    content 
</qnamePrefix:qnameLocal>

If the content parameter contains simple data, its String representation is used. If it contains an Object, its structure is converted to XML. For example, if the content parameter passed to the method contains the following data:

{name:value}

The SOAPHeader is encoded as follows:

<qnamePrefix:qnameLocal> 
    <headerName>headerValue</headerName> 
</qnamePrefix:qnameLocal>

If the content parameter contains a property with the same name as qnameLocal, the value of that property is used as the header content. Therefore, if qnameLocal equals headerName, the SOAPHeader object is encoded as follows:

<qnamePrefix:headerName> 
    headerValue 
</qnamePrefix:headerName>

The code in the following example shows how to use the addHeader() method and the addSimpleHeader() method to add a SOAP header. The methods are called in the headers() function, and the event listener is assigned in the load property of an WebService component:

<?xml version="1.0"?> 
<!-- ds\rpc\WebServiceAddHeader.mxml --> 
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"> 
    <mx:Script> 
        <![CDATA[ 
            import mx.rpc.soap.SOAPHeader; 
            
            private var header1:SOAPHeader;     
            private var header2:SOAPHeader;     
            public function headers():void { 
 
                // Create QName and SOAPHeader objects. 
                var q1:QName = new QName("http://soapinterop.org/xsd", "Header1"); 
                header1 = new SOAPHeader(q1, {string:"bologna",int:"123"}); 
                header2 = new SOAPHeader(q1, {string:"salami",int:"321"}); 
    
                // Add the header1 SOAP Header to all web service requests. 
                ws.addHeader(header1); 
 
                // Add the header2 SOAP Header to the getSomething operation. 
                ws.getSomething.addHeader(header2); 
 
                // Within the addSimpleHeader method, 
                // which adds a SOAP header to web 
                //service requests, create SOAPHeader and QName objects. 
                ws.addSimpleHeader("header3", "http://soapinterop.org/xsd", "foo", "bar"); 
            } 
        ]]> 
    </mx:Script> 
 
    <mx:WebService id="ws" 
        destination="wsDest" 
        load="headers();"/> 
</mx:Application>

Use the clearHeaders() method of a WebService or Operation object to remove SOAP headers that you added to the object, as the following example shows:

<?xml version="1.0"?> 
<!-- ds\rpc\WebServiceClearHeader.mxml --> 
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"> 
 
    <!-- The value of the destination property is for demonstration only 
        and is not a real destination. --> 
    <mx:Script> 
        <![CDATA[ 
            import mx.rpc.*; 
            import mx.rpc.soap.SOAPHeader; 
                
            private function headers():void { 
                // Create QName and SOAPHeader objects. 
                var q1:QName = new QName("Header1", "http://soapinterop.org/xsd"); 
                var header1:SOAPHeader = new SOAPHeader(q1, {string:"bologna",int:"123"}); 
                var header2:SOAPHeader = new SOAPHeader(q1, {string:"salami",int:"321"}); 
                    // Add the header1 SOAP Header to all web service request. 
                ws.addHeader(header1); 
                // Add the header2 SOAP Header to the getSomething operation. 
                ws.getSomething.addHeader(header2); 
 
                // Within the addSimpleHeader method, which adds a SOAP header to all 
                // web service requests, create SOAPHeader and QName objects. 
                ws.addSimpleHeader("header3","http://soapinterop.org/xsd", "foo", "bar"); 
            } 
 
            // Clear SOAP headers added at the WebService and Operation levels. 
            private function clear():void { 
                ws.clearHeaders(); 
                ws.getSomething.clearHeaders(); 
            } 
        ]]> 
    </mx:Script> 
 
    <mx:WebService id="ws" 
        destination="wsDest" 
        load="headers();"/> 
 
    <mx:HBox> 
        <mx:Button label="Clear headers and run again" 
            click="clear();"/> 
    </mx:HBox> 
</mx:Application>

Some web services require that you change to a different endpoint URL after you process the WSDL and make an initial call to the web service. For example, suppose you want to use a web service that requires you to pass security credentials. After you call the web service to send login credentials, it accepts the credentials and returns the actual endpoint URL that is required to use the business operations. Before calling the business operations, change the endpointURI property of your WebService component.

The following example shows a result event listener that stores the endpoint URL that a web service returns in a variable, and then sets the endpoint URL for subsequent requests:

public function onLoginResult(event:ResultEvent):void { 
 
    //Extract the new service endpoint from the login result.  
    var newServiceURL = event.result.serverUrl; 
 
    // Redirect all service operations to the URL received in the login result.  
    serviceName.endpointURI=newServiceURL;     
}

A web service that requires you to pass security credentials can also return an identifier that you must attach in a SOAP header for subsequent requests; for more information, see Working with SOAP headers.