Applications created with the Flex framework can interact with SOAP-based web services that define their interfaces in a Web Services Description Language 1.1 (WSDL 1.1) document, which is available as a URL. WSDL is a standard format for describing the messages that a web service understands, the format of its responses to those messages, the protocols that the web service supports, and where to send messages. The Flex web service API generally supports Simple Object Access Protocol (SOAP) 1.1, XML Schema 1.0 (versions 1999, 2000, and 2001), and WSDL 1.1 RPC-encoded, RPC-literal, and document-literal (bare and wrapped style parameters). The two most common types of web services use remote procedure call (RPC) encoded or document-literal SOAP bindings; the terms encoded and literal indicate the type of WSDL-to-SOAP mapping that a service uses.
Flex supports web service requests and results that are formatted as SOAP messages. SOAP provides the definition of the XML-based format that you can use for exchanging structured and typed information between a web service client, such as an application built with Flex, and a web service.
Adobe® Flash® Player operates within a security sandbox that limits what applications built with Flex and other applications built with Flash can access over HTTP. Applications built with Flash are allowed HTTP access only to resources on the same domain and by the same protocol from which they were served. This presents a problem for web services, because they are typically accessed from remote locations. The proxy service, available in LiveCycle Data Services and BlazeDS, intercepts requests to remote web services, redirects the requests, and then returns the responses to the client.
If you are not using LiveCycle Data Services or BlazeDS, you can access web services in the same domain as your application; or a crossdomain.xml (cross-domain policy) file that allows access from your application's domain must be installed on the web server hosting the RPC service.
For API reference information about the WebService component, see mx.rpc.soap.mxml.WebService.
The following sample code is for an application that uses a WebService component to call web service operations.
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>
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.apache.org/xml-soap"
xmlns:impl="http://flexapp" xmlns:intf="http://flexapp"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:tns1="http://rpc.xml.coldfusion"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<!--WSDL created by ColdFusion version 8,0,0,171651-->
<wsdl:types>
<schema targetNamespace="http://rpc.xml.coldfusion" xmlns="http://www.w3.org/2001/XMLSchema">
<import namespace="http://flexapp"/>
<import namespace="http://schemas.xmlsoap.org/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.w3.org/2001/XMLSchema">
<import namespace="http://rpc.xml.coldfusion"/>
<import namespace="http://schemas.xmlsoap.org/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.xmlsoap.org/soap/http"/>
<wsdl:operation name="insertRecord">
<wsdlsoap:operation soapAction=""/>
<wsdl:input name="insertRecordRequest">
<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="http://flexapp" use="encoded"/>
</wsdl:input>
<wsdl:output name="insertRecordResponse">
<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="http://flexapp" use="encoded"/>
</wsdl:output>
<wsdl:fault name="CFCInvocationException">
<wsdlsoap:fault encodingStyle="http://schemas.xmlsoap.org/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.xmlsoap.org/soap/encoding/" namespace="http://flexapp" use="encoded"/>
</wsdl:input>
<wsdl:output name="returnRecordsResponse">
<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="http://flexapp" use="encoded"/>
</wsdl:output>
<wsdl:fault name="CFCInvocationException">
<wsdlsoap:fault encodingStyle="http://schemas.xmlsoap.org/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.
Note: When you declare a WebService component in ActionScript, call the
WebService.loadWSDL()method.
<?xml version="1.0"?>
<!-- fds\rpc\WebServiceInAS.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx: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
}
]]>
</mx:Script>
</mx:Application>
WebService operations are 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.
Tag |
Description |
|---|---|
|
Specifies the protocol that clients, such as applications built with Flex, use to communicate with a web service. Bindings exist for SOAP, HTTP GET, HTTP POST, and MIME. Flex supports the SOAP binding only. |
|
Specifies an error value that is returned as a result of a problem processing a message. |
|
Specifies a message that a client, such as an application built with Flex, sends to a web service. |
|
Defines the data that a WebService operation transfers. |
|
Defines a combination of <input>, <output>, and <fault> tags. |
|
Specifies a message that the web service sends to a web service client, such as an application built with Flex. |
|
Specifies a web service endpoint, which specifies an association between a binding and a network address. |
|
Defines one or more operations that a web service provides. |
|
Defines a collection of <port>tags. Each service maps to one <portType> tag and specifies different ways to access the operations in that <portType> tag. |
|
Defines data types that a web service's messages use. |
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.xmlsoap.org/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.bindingpoint.com/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.
Some web services require that you pass along a SOAP header when you call an operation.
You can add a SOAP header to all web service operations or individual operations
by calling a WebService or Operation object's addHeader() method or
addSimpleHeader() method in an event listener function.
When you use the addHeader() method, you first must 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, use the following constructor:
SOAPHeader(qname:QName, content:Object)
To create the QName object in the first parameter of the SOAPHeader() method,
use the following constructor:
QName(uri:String, localName:String)
The content parameter of the SOAPHeader() constructor is a set of name-value
pairs based on the following format:
{name1:value1, name2:value2}
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:
-
qnameLocalis the local name for the header QName. -
qnameNamespaceis the namespace for the header QName. -
headerNameis the name of the header. -
headerValueis the value of the header. This can be a string if it is a simple value, an object that will undergo basic XML encoding, or XML if you want to specify the header XML yourself.The code in the following example shows how to use the
addHeader()method and theaddSimpleHeader()method to add a SOAP header. The methods are called in an event listener function calledheaders, and the event listener is assigned in theloadproperty of an<mx:WebService>tag:<?xml version="1.0"?> <!-- fds\rpc\WebServiceAddHeader.mxml --> <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" height="600"> <mx:WebService id="ws" wsdl="http://myserver:8500/flexapp/app1.cfc?wsdl" load="headers();"/> <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:Application>
You use the WebService or operation object's clearHeaders() method to remove
SOAP headers that you added to the object, as the following example shows for a
WebService object. You must call clearHeaders() at the level (WebService or
operation) where the header was added.
<?xml version="1.0"?>
<!-- fds\rpc\WebServiceClearHeader.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" height="600" >
<!-- 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();"/>
<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: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 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.
The following table shows the encoding mappings from ActionScript 3.0 types to XML schema complex types.
XML schema definition |
Supported ActionScript 3.0 types |
Notes |
|---|---|---|
Top-level elements |
|
|
xsd:element nillable == true |
Object |
If input value is null, encoded output is set with the xsi:nil attribute. |
xsd:element fixed != null |
Object |
Input value is ignored and fixed value is used instead. |
xsd:element default != null |
Object |
If input value is null, this default value is used instead. |
Local elements |
|
|
xsd:element maxOccurs == 0 |
Object |
Input value is ignored and omitted from encoded output. |
xsd:element maxOccurs == 1 |
Object |
Input value is processed as a single entity. If the associated type is a SOAP-encoded array, then arrays and mx.collection.IListimplementations pass through intact to be special cased by the SOAP encoder for that type. |
xsd:element maxOccurs > 1 |
Object |
Input value should be iterable (such as an array or mx.collections.IList implementation), although noniterable values are wrapped before processing. Individual items are encoded as separate entities according to the definition. |
xsd:element minOccurs == 0 |
Object |
If input value is undefined or null, encoded output is omitted. |
The following table shows the encoding mappings from ActionScript 3.0 types to XML schema built-in types.
XML schema type |
Supported ActionScript 3.0 types |
Notes |
|---|---|---|
xsd:anyType xsd:anySimpleType |
Object |
Boolean -> xsd:boolean ByteArray -> xsd:base64Binary Date -> xsd:dateTime int -> xsd:int Number -> xsd:double String -> xsd:string uint -> xsd:unsignedInt |
xsd:base64Binary |
flash.utils.ByteArray |
mx.utils.Base64Encoder is used (without line wrapping). |
xsd:boolean |
Boolean Number Object |
Always encoded as true or false. Number == 1 then true, otherwise false. Object.toString()== "true" or "1" then true, otherwise false. |
xsd:byte xsd:unsignedByte |
Number String |
String first converted to Number. |
xsd:date |
Date Number String |
Date UTC accessor methods are used. Number used to set Date.time. String assumed to be preformatted and encoded as is. |
xsd:dateTime |
Date Number String |
Date UTC accessor methods are used. Number used to set Date.time. String assumed to be preformatted and encoded as is. |
xsd:decimal |
Number String |
Number.toString()is used. Infinity, -Infinity, and NaN are invalid for this type. String first converted to Number. |
xsd:double |
Number String |
Limited to range of Number. String first converted to Number. |
xsd:duration |
Object |
Object.toString() is called. |
xsd:float |
Number String |
Limited to range of Number. String first converted to Number. |
xsd:gDay |
Date Number String |
Date.getUTCDate() is used. Number used directly for day. String parsed as Number for day. |
xsd:gMonth |
Date Number String |
Date.getUTCMonth()is used. Number used directly for month. String parsed as Number for month. |
xsd:gMonthDay |
Date String |
Date.getUTCMonth()and Date.getUTCDate()are used. String parsed for month and day portions. |
xsd:gYear |
Date Number String |
Date.getUTCFullYear()is used. Number used directly for year. String parsed as Number for year. |
xsd:gYearMonth |
Date String |
Date.getUTCFullYear()and Date.getUTCMonth() are used. String parsed for year and month portions. |
xsd:hexBinary |
flash.utils.ByteArray |
mx.utils.HexEncoder is used. |
xsd:integer and derivatives: xsd:negativeInteger xsd:nonNegativeInteger xsd:positiveInteger xsd:nonPositiveInteger |
Number String |
Limited to range of Number. String first converted to Number. |
xsd:int xsd:unsignedInt |
Number String |
String first converted to Number. |
xsd:long xsd:unsignedLong |
Number String |
String first converted to Number. |
xsd:short xsd:unsignedShort |
Number String |
String first converted to Number. |
xsd:string and derivatives: xsd:ID xsd:IDREF xsd:IDREFS xsd:ENTITY xsd:ENTITIES xsd:language xsd:Name xsd:NCName xsd:NMTOKEN xsd:NMTOKENS xsd:normalizedString xsd:token |
Object |
Object.toString() is invoked. |
xsd:time |
Date Number String |
Date UTC accessor methods are used. Number used to set Date.time. String assumed to be preformatted and encoded as is. |
xsi:nil |
null |
If the corresponding XML schema element definition has minOccurs > 0, a null value is encoded by using xsi:nil; otherwise the element is omitted entirely. |
The following table shows the mapping from ActionScript 3.0 types to SOAP-encoded types.
SOAPENC type |
Supported ActionScript 3.0 types |
Notes |
|---|---|---|
soapenc:Array |
Array mx.collections.IList |
SOAP-encoded arrays are special cased and are supported only with RPC-encoded style web services. |
soapenc:base64 |
flash.utils.ByteArray |
Encoded in the same manner as xsd:base64Binary. |
soapenc:* |
Object |
Any other SOAP-encoded type is processed as if it were in the XSD namespace based on the localName of the type's QName. |
The following table shows the decoding mappings from XML schema built-in types to ActionScript 3.0 types.
XML schema type |
Decoded ActionScript 3.0 types |
Notes |
|---|---|---|
xsd:anyType xsd:anySimpleType |
String Boolean Number |
If content is empty -> xsd:string. If content cast to Number and value is NaN; or if content starts with "0" or "-0", or it content ends with "E": then, if content is "true" or "false" -> xsd:boolean otherwise -> xsd:string. Otherwise content is a valid Number and thus -> xsd:double. |
xsd:base64Binary |
flash.utils.ByteArray |
mx.utils.Base64Decoder is used. |
xsd:boolean |
Boolean |
If content is "true" or "1" then true, otherwise false. |
xsd:date |
Date |
If no time zone information is present, local time is assumed. |
xsd:dateTime |
Date |
If no time zone information is present, local time is assumed. |
xsd:decimal |
Number |
Content is created via Number(content) and is thus limited to the range of Number. |
xsd:double |
Number |
Content is created via Number(content) and is thus limited to the range of Number. |
xsd:duration |
String |
Content is returned with whitespace collapsed. |
xsd:float |
Number |
Content is converted through Number(content) and is thus limited to the range of Number. |
xsd:gDay |
uint |
Content is converted through uint(content). |
xsd:gMonth |
uint |
Content is converted through uint(content). |
xsd:gMonthDay |
String |
Content is returned with whitespace collapsed. |
xsd:gYear |
uint |
Content is converted through uint(content). |
xsd:gYearMonth |
String |
Content is returned with whitespace collapsed. |
xsd:hexBinary |
flash.utils.ByteArray |
mx.utils.HexDecoder is used. |
xsd:integer and derivatives: xsd:byte xsd:int xsd:long xsd:negativeInteger xsd:nonNegativeInteger xsd:nonPositiveInteger xsd:positiveInteger xsd:short xsd:unsignedByte xsd:unsignedInt xsd:unsignedLong xsd:unsignedShort |
Number |
Content is decoded via parseInt(). |
xsd:string and derivatives: xsd:ID xsd:IDREF xsd:IDREFS xsd:ENTITY xsd:ENTITIES xsd:language xsd:Name xsd:NCName xsd:NMTOKEN xsd:NMTOKENS xsd:normalizedString xsd:token |
String |
The raw content is simply returned as a string. |
xsd:time |
Date |
If no time zone information is present, local time is assumed. |
xsi:nil |
null |
|
The following table shows the decoding mappings from SOAP-encoded types to ActionScript 3.0 types.
SOAPENC type |
Decoded ActionScript type |
Notes |
|---|---|---|
soapenc:Array |
Array mx.collections.ArrayCollection |
SOAP-encoded arrays are special cased. If makeObjectsBindable is true, the result is wrapped in an ArrayCollection; otherwise a simple array is returned. |
soapenc:base64 |
flash.utils.ByteArray |
Decoded in the same manner as xsd:base64Binary. |
soapenc:* |
Object |
Any other SOAP-encoded type is processed as if it were in the XSD namespace based on the localName of the type's QName. |
The following table shows the decoding mappings from custom data types to ActionScript 3.0 data types.
Custom type |
Decoded ActionScript 3.0 type |
Notes |
|---|---|---|
Apache Map |
Object |
SOAP representation of java.util.Map. Keys must be representable as strings. |
Apache Rowset |
Array of objects |
|
ColdFusion QueryBean |
Array of objects mx.collections.ArrayCollection of objects |
If makeObjectsBindable is true, the resulting array is wrapped in an ArrayCollection. |
The following XML schema structures or structure attributes are only partially implemented in Flex 4:
<choice>
<all>
<union
The following XML Schema structures or structure attributes are ignored and are not supported in Flex 4:
<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>
When consuming data from a web service invocation, Flex usually creates untyped anonymous ActionScript objects that mimic the XML structure in the body of the SOAP message. If you want Flex to create an instance of a specific class, you can use an mx.rpc.xml.SchemaTypeRegistry object and register a QName object with a corresponding ActionScript class.
For example, suppose you have the following class definition in a file named User.as:
package
{
public class User
{
public function User() {}
public var firstName:String;
public var lastName:String;
}
}
Next, you want to invoke a getUser operation on a web service that returns the
following XML:
<tns:getUserResponse xmlns:tns="http://example.uri">
<tns:firstName>Ivan</tns:firstName>
<tns:lastName>Petrov</tns:lastName>
</tns:getUserResponse>
Make sure you get an instance of your User class instead of a generic Object when you invoke the getUser operation, you need the following ActionScript code inside a method in your application:
SchemaTypeRegistry.getInstance().registerClass(new QName("http://example.uri", "getUserResponse"), User);
SchemaTypeRegistry.getInstance() is a static method that returns the default
instance of the type registry. In most cases, that is all you need. However,
this registers a given QName with the same ActionScript class across all web
service operations in your application. If you want to register different
classes for different operations, you need the following code in a method in
your application:
var qn:QName = new QName("http://the.same", "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;
There are two approaches to take full control over how ActionScript objects are serialized into XML and how XML response messages are deserialized. The recommended one is to work directly with E4X.
If you pass an instance of XML as the only parameter to a web service operation,
it is passed on untouched as the child of the <SOAP:Body> node in the
serialized request. Use this strategy when you need full control over the SOAP
message. Similarly, when deserializing a web service response, you can set the
operation's resultFormat property to e4x. This returns an XMLList object with
the children of the <SOAP:Body> node in the response message. From there, you
can implement the necessary custom logic to create the appropriate ActionScript
objects.
The second and more tedious approach is to provide your own implementations of mx.rpc.soap.ISOAPDecoder and mx.rpc.soap.ISOAPEncoder. For example, if you have written a class called MyDecoder that implements ISOAPDecoder, you can have the following in a method in your application:
myWS.someOperation.decoder = new MyDecoder();
When you invoke someOperation, Flex calls the decodeResponse() method of the
MyDecoder class. From that point on it is up to the custom implementation to
handle the full SOAP message and produce the expected ActionScript objects.