Sample WebService application

The following sample code is for an application that uses a WebService component to call web service operations.

MXML code

The application in the following example calls a web service that queries a SQL database table called users and returns data to the application, where it is bound to the dataProvider property of a DataGrid control and displayed in the DataGrid control. The application also sends the user name and e-mail address of new users to the web service, which performs an insert into the user database table. The back-end implementation of the web service is a ColdFusion component; the same ColdFusion component is accessed as a remote object in Using RemoteObject components.

<?xml version="1.0" encoding="utf-8"?> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
        xmlns:s="library://ns.adobe.com/flex/spark" 
        xmlns:mx="library://ns.adobe.com/flex/mx" minWidth="955" minHeight="600"> 
    <fx:Declarations> 
        <s:WebService 
            id="userRequest" 
            wsdl="http://localhost:8500/flexapp/returnusers.cfc?wsdl"> 
             
            <mx:operation name="returnRecords" resultFormat="object" 
                          fault="mx.controls.Alert.show(event.fault.faultString)" 
                          result="remotingCFCHandler(event)"/> 
             
            <mx:operation name="insertRecord" result="insertCFCHandler()" 
                          fault="mx.controls.Alert.show(event.fault.faultString)"/> 
        </s:WebService> 
    </fx:Declarations> 
    <fx:Script> 
        <![CDATA[ 
            import mx.rpc.events.ResultEvent; 
             
            private function remotingCFCHandler(e:ResultEvent):void  
            { 
                dgUserRequest.dataProvider = e.result; 
            } 
             
            private function insertCFCHandler():void  
            { 
                userRequest.returnRecords(); 
            } 
            private function clickHandler():void  
            { 
                userRequest.insertRecord(username.text, emailaddress.text); 
            } 
        ]]> 
    </fx:Script> 
     
    <mx:Form x="22" y="10" width="300"> 
        <mx:FormItem> 
            <s:Label text="Username" />     
            <s:TextInput id="username"/> 
        </mx:FormItem> 
        <mx:FormItem> 
            <s:Label text="Email Address" />     
            <s:TextInput id="emailaddress"/> 
        </mx:FormItem> 
        <s:Button label="Submit" click="clickHandler()"/> 
    </mx:Form> 
     
    <mx:DataGrid id="dgUserRequest" x="22" y="160"> 
        <mx:columns> 
            <mx:DataGridColumn headerText="User ID" dataField="USERID"/> 
            <mx:DataGridColumn headerText="User Name" dataField="USERNAME"/> 
        </mx:columns> 
    </mx:DataGrid> 
     
    <s:TextInput x="22" y="320" id="selectedemailaddress" text="{dgUserRequest.selectedItem.emailaddress}"/>      
</s:Application>

WSDL document

The following example shows the WSDL document that defines the API of the web service:

<?xml version="1.0" encoding="UTF-8"?> 
<wsdl:definitions targetNamespace="http://flexapp" 
    xmlns:apachesoap="http://xml./xml-soap" 
    xmlns:impl="http://flexapp" xmlns:intf="http://flexapp" 
    xmlns:soapenc="http://schemas./soap/encoding/" 
    xmlns:tns1="http://rpc.ldfusion" 
    xmlns:wsdl="http://schemas./wsdl/" 
    xmlns:wsdlsoap="http://schemas./wsdl/soap/" 
    xmlns:xsd="http://www./2001/XMLSchema"> 
<!--WSDL created by ColdFusion version 8,0,0,171651--> 
    <wsdl:types> 
<schema targetNamespace="http://rpc.ldfusion" xmlns="http://www./2001/XMLSchema"> 
    <import namespace="http://flexapp"/> 
    <import namespace="http://schemas./soap/encoding/"/> 
    <complexType name="CFCInvocationException"> 
<sequence/> 
    </complexType> 
 
    <complexType name="QueryBean"> 
<sequence> 
    <element name="columnList" nillable="true" type="impl:ArrayOf_xsd_string"/> 
    <element name="data" nillable="true" type="impl:ArrayOfArrayOf_xsd_anyType"/> 
</sequence> 
    </complexType> 
</schema> 
<schema targetNamespace="http://flexapp" xmlns="http://www./2001/XMLSchema"> 
    <import namespace="http://rpc.ldfusion"/> 
 
    <import namespace="http://schemas./soap/encoding/"/> 
    <complexType name="ArrayOf_xsd_string"> 
<complexContent> 
    <restriction base="soapenc:Array"> 
<attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:string[]"/> 
    </restriction> 
</complexContent> 
    </complexType> 
    <complexType name="ArrayOfArrayOf_xsd_anyType"> 
 
<complexContent> 
    <restriction base="soapenc:Array"> 
<attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:anyType[][]"/> 
    </restriction> 
</complexContent> 
    </complexType> 
</schema> 
    </wsdl:types> 
 
    <wsdl:message name="CFCInvocationException"> 
 
<wsdl:part name="fault" type="tns1:CFCInvocationException"/> 
</wsdl:message> 
<wsdl:message name="returnRecordsRequest"> 
</wsdl:message> 
<wsdl:message name="insertRecordResponse"> 
</wsdl:message> 
<wsdl:message name="returnRecordsResponse"> 
<wsdl:part name="returnRecordsReturn" type="tns1:QueryBean"/> 
</wsdl:message> 
<wsdl:message name="insertRecordRequest"> 
<wsdl:part name="username" type="xsd:string"/> 
<wsdl:part name="emailaddress" type="xsd:string"/> 
</wsdl:message> 
<wsdl:portType name="returncfxml"> 
<wsdl:operation name="insertRecord" parameterOrder="username emailaddress"> 
<wsdl:input message="impl:insertRecordRequest" name="insertRecordRequest"/> 
<wsdl:output message="impl:insertRecordResponse" name="insertRecordResponse"/> 
<wsdl:fault message="impl:CFCInvocationException" name="CFCInvocationException"/> 
</wsdl:operation> 
<wsdl:operation name="returnRecords"> 
<wsdl:input message="impl:returnRecordsRequest" name="returnRecordsRequest"/> 
<wsdl:output message="impl:returnRecordsResponse" name="returnRecordsResponse"/> 
<wsdl:fault message="impl:CFCInvocationException" name="CFCInvocationException"/> 
</wsdl:operation> 
</wsdl:portType> 
<wsdl:binding name="returncfxml.cfcSoapBinding" type="impl:returncfxml"> 
<wsdlsoap:binding style="rpc" transport="http://schemas./soap/http"/> 
<wsdl:operation name="insertRecord"> 
<wsdlsoap:operation soapAction=""/> 
<wsdl:input name="insertRecordRequest"> 
<wsdlsoap:body encodingStyle="http://schemas./soap/encoding/" namespace="http://flexapp" use="encoded"/> 
</wsdl:input> 
<wsdl:output name="insertRecordResponse"> 
<wsdlsoap:body encodingStyle="http://schemas./soap/encoding/" namespace="http://flexapp" use="encoded"/> 
</wsdl:output> 
<wsdl:fault name="CFCInvocationException"> 
<wsdlsoap:fault encodingStyle="http://schemas./soap/encoding/" name="CFCInvocationException" namespace="http://flexapp" use="encoded"/> 
</wsdl:fault> 
</wsdl:operation> 
<wsdl:operation name="returnRecords"> 
<wsdlsoap:operation soapAction=""/> 
<wsdl:input name="returnRecordsRequest"> 
<wsdlsoap:body encodingStyle="http://schemas./soap/encoding/" namespace="http://flexapp" use="encoded"/> 
</wsdl:input> 
<wsdl:output name="returnRecordsResponse"> 
<wsdlsoap:body encodingStyle="http://schemas./soap/encoding/" namespace="http://flexapp" use="encoded"/> 
</wsdl:output> 
<wsdl:fault name="CFCInvocationException"> 
<wsdlsoap:fault encodingStyle="http://schemas./soap/encoding/" name="CFCInvocationException" namespace="http://flexapp" use="encoded"/> 
</wsdl:fault> 
</wsdl:operation> 
</wsdl:binding> 
<wsdl:service name="returncfxmlService"> 
<wsdl:port binding="impl:returncfxml.cfcSoapBinding" name="returncfxml.cfc"> 
<wsdlsoap:address location="http://localhost:8500/flexapp/returnusers.cfc"/> 
</wsdl:port> 
</wsdl:service> 
</wsdl:definitions>

The following example shows a web service call in an ActionScript script block. Calling the useWebService() method declares the service, sets the destination, fetches the WSDL document, and calls the echoArgs() method of the service.

<?xml version="1.0"?> 
<!-- fds\rpc\WebServiceInAS.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
               xmlns:s="library://ns.adobe.com/flex/spark" 
               xmlns:mx="library://ns.adobe.com/flex/mx" minWidth="955" 
    <fx:Script> 
        <![CDATA[ 
        import mx.rpc.soap.WebService; 
        import mx.rpc.events.ResultEvent; 
        import mx.rpc.events.FaultEvent; 
        private var ws:WebService; 
        public function useWebService(intArg:int, strArg:String):void { 
            ws = new WebService(); 
            ws.wsdl="http://myserver:8500/flexapp/app1.cfc?wsdl"; 
            ws.echoArgs.addEventListener("result", echoResultHandler); 
            ws.addEventListener("fault", faultHandler); 
            ws.loadWSDL(); 
            ws.echoArgs(intArg, strArg); 
        } 
 
        public function echoResultHandler(event:ResultEvent):void { 
            var retStr:String = event.result.echoStr; 
            var retInt:int = event.result.echoInt; 
         //Do something. 
        } 
 
        public function faultHandler(event:FaultEvent):void { 
      //deal with event.fault.faultString, etc 
        } 
        ]]> 
    </fx:Script> 
</mx:Application>

WebService operations are usually accessible by simply naming them after a service variable. However, naming conflicts can occur if an operation name happens to match a defined method on the service. You can use the following method in ActionScript on a WebService component to return the operation of the given name:

public function getOperation(name:String):Operation

You can view a WSDL document in a web browser, a simple text editor, an XML editor, or a development environment such as Adobe Dreamweaver, which contains a built-in utility for displaying WSDL documents in an easy-to-read format.

A WSDL document contains the tags described in the following table.

<binding>

<fault>

<input>

<message>

<operation>

<output>

<port>

<portType>

<service>

<types>

A WSDL file can specify either RPC-oriented or document-oriented (document-literal) operations. Flex supports both operation styles.

When calling an RPC-oriented operation, an application sends a SOAP message that specifies an operation and its parameters. When calling a document-oriented operation, an application sends a SOAP message that contains an XML document.

In a WSDL document, each <port> tag has a binding property that specifies the name of a particular <soap:binding> tag, as the following example shows:

<binding name="InstantMessageAlertSoap" type="s0:InstantMessageAlertSoap"> 
    <soap:binding transport="http://schemas./soap/http" 
        style="document"/>

The style property of the associated <soap:binding> tag determines the operation style. In this example, the style is document.

Any operation in a service can specify the same style or override the style that is specified for the port associated with the service, as the following example shows:

<operation name="SendMSN"> 
    <soap:operation soapAction="http://www./ws/imalert/ 
        SendMSN"        style="document"/> 

Flex uses Java server sessions to maintain the state of web service endpoints that use cookies to store session information. This feature acts as an intermediary between applications and web services. It adds an endpoint's identity to whatever the endpoint passes to an application. If the endpoint sends session information, the application receives it. This feature requires no configuration, and it is not supported for destinations that use the RTMP channel when using the proxy service.

A SOAP header is an optional tag in a SOAP envelope that usually contains application-specific information, such as authentication information.

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

SOAPHeader(qname:QName, content:Object)

QName(uri:String, localName:String)

{name1:value1, name2:value2}

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

<?xml version="1.0" encoding="utf-8"?> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
        xmlns:s="library://ns.adobe.com/flex/spark" 
        xmlns:mx="library://ns.adobe.com/flex/mx" minWidth="955" minHeight="600"> 
    <fx:Declarations> 
        <!-- The value of the destination property is for demonstration only 
            and is not a real destination. --> 
        <mx:WebService id="ws" wsdl="http://myserver:8500/flexapp/app1.cfc?wsdl" load="headers();"/> 
    </fx:Declarations> 
     
    <fx: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:///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:///xsd", 
                                                                "foo", "bar"); 
            } 
             
            // Clear SOAP headers added at the WebService and Operation levels. 
            private function clear():void { 
                ws.clearHeaders(); 
                ws.getSomething.clearHeaders(); 
            } 
        ]]> 
    </fx:Script> 
    <s:Button label="Clear headers and run again" click="clear()"/> 
</s: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 that you want to use a web service that requires you to pass security credentials. When 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 service's business operations. Before calling the business operations, you must 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 passes that variable into a function to change 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 might also return an identifier that you must attach in a SOAP header for subsequent requests. For more information, see Working with SOAP headers.

Encoding ActionScript data

Decoding XML schema and SOAP to ActionScript 3

XML Schema element support

<choice> 
<all> 
<union

<attribute use="required"/> 
 
<element 
    substitutionGroup="..." 
    unique="..." 
    key="..." 
    keyref="..." 
    field="..." 
    selector="..."/> 
 
<simpleType> 
    <restriction> 
        <minExclusive> 
        <minInclusive> 
        <maxExclusiv> 
        <maxInclusive> 
        <totalDigits> 
        <fractionDigits> 
        <length> 
        <minLength> 
        <maxLength> 
        <enumeration> 
        <whiteSpace> 
        <pattern> 
    </restriction> 
</simpleType> 
 
<complexType 
    final="..." 
    block="..." 
    mixed="..." 
    abstract="..."/> 
 
<any 
processContents="..."/> 
 
<annotation>

Customizing web service type mapping

package 
{ 
     public class User 
     { 
       public function User() {} 
 
       public var firstName:String; 
       public var lastName:String; 
     } 
}

<tns:getUserResponse xmlns:tns="http://example.uri"> 
     <tns:firstName>Ivan</tns:firstName> 
     <tns:lastName>Petrov</tns:lastName> 
</tns:getUserResponse>

SchemaTypeRegistry.getInstance().registerClass(new QName("http://example.uri", "getUserResponse"), User);

var qn:QName = new QName("http://me", "qname"); 
var typeReg1:SchemaTypeRegistry = new SchemaTypeRegistry(); 
var typeReg2:SchemaTypeRegistry = new SchemaTypeRegistry(); 
typeReg1.registerClass(qn, someClass); 
myWS.someOperation.decoder.typeRegistry = typeReg1; 
 
typeReg2.registerClass(qn, anotherClass); 
myWS.anotherOperation.decoder.typeRegistry = typeReg2;

Using custom web service serialization

myWS.someOperation.decoder = new MyDecoder();