Using WebService componentsApplications created with the Flex framework can interact with 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 a Flex application, and a web service. Adobe? Flash? Player operates within a security sandbox that limits what Flex applications 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 ES 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 ES 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. Sample WebService applicationThe following sample code is for an application that uses a WebService component to call web service operations. MXML codeThe 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 documentThe 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>
Calling web services in ActionScriptThe 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,
you must call the WebService.loadWSDL() method.
<?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>
Reserved Operation namesWebService 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 Reading WSDL documentsYou 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.
RPC-oriented operations and document-oriented operationsA 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"/>
Stateful web servicesFlex 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. Working with SOAP headersA SOAP header is an optional tag in a SOAP envelope that usually contains application-specific information, such as authentication information. Adding SOAP headers to web service requestsSome 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:
Clearing SOAP headersYou 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" 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>
Redirecting a web service to a different URLSome 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. Serializing web service dataEncoding ActionScript dataThe following table shows the encoding mappings from ActionScript 3 types to XML schema complex types.
The following table shows the encoding mappings from ActionScript 3 types to XML schema built-in types.
The following table shows the mapping from ActionScript 3 types to SOAP-encoded types.
Decoding XML schema and SOAP to ActionScript 3The following table shows the decoding mappings from XML schema built-in types to ActionScript 3 types.
The following table shows the decoding mappings from SOAP-encoded types to ActionScript 3 types.
The following table shows the decoding mappings from custom data types to ActionScript 3 data types.
XML Schema element supportThe 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>
Customizing web service type mappingWhen 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 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://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 serializationThere 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 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.  |
|
|
