Serializing between ActionScript and web services
Default encoding of ActionScript data
The following table shows the default encoding mappings from ActionScript 3 types to XML schema complex types.
|
XML schema definition |
Supported ActionScript 3 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.IList implementations pass through intact and are handled as a special case 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 default encoding mappings from ActionScript 3 types to XML schema built-in types.
|
XML schema type |
Supported ActionScript 3 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. Note that 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 default mapping from ActionScript 3 types to SOAP-encoded types.
|
SOAPENC type |
Supported ActionScript 3 types |
Notes |
|
soapenc:Array |
Array mx.collections.IList |
SOAP-encoded arrays are special cases and are supported only with RPC-encoded 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. |
Default decoding of XML schema and SOAP to ActionScript 3
The following table shows the default decoding mappings from XML schema built-in types to ActionScript 3 types.
|
XML schema type |
Decoded ActionScript 3 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 if 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. Number.NaN, Number.POSITIVE_INFINITY and Number.NEGATIVE_INFINITY are not allowed. |
|
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(). Number.NaN, Number.POSITIVE_INFINITY and Number.NEGATIVE_INFINITY are not allowed. |
|
xsd:string and derivatives: 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 default decoding mappings from SOAP-encoded types to ActionScript 3 types.
|
SOAPENC type |
Decoded ActionScript type |
Notes |
|
soapenc:Array |
Array |
SOAP-encoded arrays are special cases. 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 default decoding mappings from custom data types to ActionScript 3 data types.
|
Custom type |
Decoded ActionScript 3 type |
Notes |
|
Apache Map http://xml.apache.org/xml-soap:Map |
Object |
SOAP representation of java.util.Map. Keys must be representable as strings. |
|
Apache Rowset http://xml.apache.org/xml-soap:Rowset |
Array of objects |
|
|
ColdFusion QueryBean http://rpc.xml.coldfusion:QueryBean |
Array of objects mx.collections.ArrayCollection of objects |
If makeObjectsBindable is true, the resulting array is wrapped in an ArrayCollection. |
XML Schema element support
The following XML schema structures or structure attributes are only partially implemented in Flex 3:
<choice> <all> <union
The following XML Schema structures or structure attributes are ignored and are not supported in Flex 3:
<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
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>
To 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 Flex 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;
Using custom web service serialization
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 approach 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 Flex application:
myWS.someOperation.decoder = new MyDecoder();
When invoking 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.