Develop web services clients with Flex

 原帖:http://www.ibm.com/developerworks/webservices/library/ws-macroflex/

 

Introduction

Open standards are being embraced by enterprises as a means to drive down high integration and maintenance costs. The reality of today’s heterogeneous software systems is that it is imperative to employ some strategy involving open standards, and web services are quickly becoming an important piece to this puzzle. Up until now it has been quite tedious and cumbersome to build rich GUI clients to interact with these systems. Part of the problem is that Web Services Description Language (WSDL) tends to be the only description of the service endpoints, and it can sometimes be difficult to follow (even more so for the designers and user interface developers within the organization). Flex is a Rich Internet Application platform by Macromedia that bridges this distinct gap between user interface designers and the more traditional server-side developers. Traditional back-end programmers can leverage an extensive set of visually appealing controls, effects, layouts, and existing Flash components, together with their in-depth knowledge of the service endpoints, to put together an attractive client application. A designer can use these same facilities and leverage their creative skill set to build a comparable client, while shielded from complex service definitions. The end result, no matter what type of resources are available to your project at any given time, is the ability to easily create a highly interactive and engaging application that integrates your investment in web services.

 

 

Back to top

Understand WSDL

Flex uses existing WSDL definitions by referencing a URL where the document is located, in order to exchange messages between SOAP service endpoints (SOAP messaging in Flex is constrained to only use HTTP as the transport mechanism). The following elements are commonly found within a WSDL document:

Table 1. Common WSDL Elements

Element	Description
types	Defines data types that a web service’s messages can use.
message	Defines the data that a web services operation transfers.
portType	Defines one or more operations that a web service provides.
operation	Defines a combination of input, output, and fault messages.
input	Specifies a message that a client such as a Flex application sends to a web service.
output	Specifies a message that a web service sends to a client such as a Flex application.
fault	Specifies an error value returned as a result of a problem processing a message.
binding	Specifies the protocol used to communicate with a web service. Bindings exist for SOAP, HTTP GET, HTTP POST, and MIME. Flex supports the SOAP binding only.
service	Defines a collection of ports. Each service maps to one portType and specifies different ways to access the operations in that portType.
port	A web services endpoint that specifies an association between a binding and a network address.

It helps to have a general idea of how these elements come together in a WSDL document to define various web services and what they mean. Flex however tries to hide the complexity of the service definition from the developer, and for the most part it is sufficient to have a basic understanding of what functionality the service is to provide.

It is also important to point out that WSDL provides two very distinct styles of describing service operations: Remote Procedure Call (RPC) and document-oriented styles. A Flex call to a RPC service operation sends a SOAP message specifying the operation and wrapping its respective arguments. A Flex call to a document-oriented operation sends a SOAP message that encapsulates an XML document. Flex provides support for both, but the subtle differences between the two have implications as to the specific mark-up tags used. This paper walks you through various examples of these two styles in more detail in the examples below.

 

 

Back to top

Use web services in Flex

The basis for declaring a web service within your Flex application is to use the <mx:WebService> MXML tag (XML tags prefixed by mx are part of the MXML namespace and are used to construct an MXML file). Typically you associate awsdl attribute with this tag, and this points to the referencing WSDL URL. Flex provides a named service construct that moves some of this declaration to a specific block in the flex-config.xml document. The Flex documentation covers the use of named services in more detail. It also helps to use an id attribute with the Web Service in order to refer to it throughout the MXML application.

<mx:WebService id="serviceID" wsdl="http://somehost/someService/service.wsdl"> <mx:operation name="someOP" result="someResultHandler()"fault= "someFaultHandler()"> <mx:request> <!-- parameters --> </mx:request> </mx:operation> </mx:WebService>

A corresponding ActionScript serviceID.send() call now invokes this web services functionality. It is important to point out that when using the send() method with no parameters, all parameter binding should be defined within the actual web services definition. In other words, parameter binding is implicitly associated using an XML data model within the<mx:request> tags.

<mx:WebService id="serviceID" wsdl="http://somehost/someService/service.wsdl"> <mx:operation name="someOP" result="someResultHandler()"fault= "someFaultHandler()"> <mx:request> <param1>{input1.text}</param1> <param2>{input2.text}</param2> </mx:request> </mx:operation> </mx:WebService>

The other way of binding parameters to this service call is to explicitly pass them. A corresponding call that explicitly binds parameters looks like serviceID.send(input1.text, input2.text), where it is no longer necessary to use the XML data model within the MXML declaration as previously described.

You have now seen the mechanism for invoking a web service from a Flex application, but how do you process the results? Taking a closer look at the declaration above, you will notice a result and fault attribute on the<mx:operation> tag. These reference ActionScript methods to process the results and handle any faults your service call may have. The point to make here is that the invocation of your service as described above is an asynchronous call. This is an important difference to note since you are probably used to the case where a return from a method call implies that its work has finished completely. In your Flex application, statements that are defined after send()immediately executes without waiting for a return from the web service. The application is able to process the results of the service call when the result handler (referenced in the operation attribute) is notified that the web service has finished execution. In the case that there were some error, the associated fault handler is notified instead.

Hopefully you are getting a clearer picture of how integrating your web services can be less tedious using the Flex environment. We now walk you through some examples describing the WSDL-specific MXML tags contained in the web services declaration that we did not discuss in this section.

 

 

Back to top

WSDL to Flex mapping by example

About the examples

The following examples cover different ways of defining SOAP-based web services operations using WSDL, as well as how the WSDL definition maps to MXML’s web services constructs. We mentioned in the previous section that web services can be declared in MXML using a parameter binding mechanism. This means that the parameters of the operation are included as part of the web services declaration (within an XML data model) as follows:

<mx:WebService> <mx:operation> <mx:request> <!--parameters here--> </mx:request> </mx:operation> </mx:WebService>

The <mx:request> element inside the <mx:operation> element contains a mixture of XML and Flex Bindings necessary to construct the content of the message’s SOAP Body.

The WSDL files used in the examples were automatically generated using IBM® WebSphere® Application Developer V5.1 Web Services Wizard (This Wizard and WebSphere Application Server WebService support are based on JSR 109). The Wizard generates the WSDL file, type mappings, serializers, and configuration entries required to host the Web Service in WebSphere Application Server V5.X (We used V5.1). Although there are multiple ways of declaring Web Services using WSDL, the following examples emphasize the set of WSDL definitions that are generated by this tool.

We begin by describing the mappings between the WSDL definition and the MXML web services declaration that are common to any WSDL file. These include MXML elements and attributes which values are independent of the specific SOAP binding settings. Then, more complex mappings are explained, which depend on the operation style (Document or RPC), encoding mechanism used (literal or encoded), type (simple or complex) of parameter, and number of parameters.

Common mappings

The first step in declaring a web service using MXML is to select the web services WSDL definition. You can do this by setting the wsdl attribute of the <mx:WebService> element to the URL of the WSDL file (Newer versions of Flex allow you to lookup the WSDL URL by using the name of the service). Then you select the target service and port by setting the service and port attributes of the <mx:WebService> element. Figure 1 shows you where to find the values of these attributes in the WSDL definition.

Figure 1: Mappings for service and port. Top: WSDL File, Bottom: MXML File
 

These attributes are optional. For service, it defaults to the name of the first <wsdl:service> (XML tags prefixed by wsdlare part of the WSDL namespace and are used to construct a WSDL file). For port it defaults to the name of the first<wsdl:port> contained in the selected <wsdl:service>. To avoid confusion, it's a best practice to set these attributes if the WSDL definition contains multiple <wsdl:service> and <wsdl:port> elements.

After selecting the service and port to use from the WSDL definition, a <mx:operation> element is added inside the<mx:WebService> element for each operation that will be invoked. The name attribute of each <mx:operation>element corresponds to the name of the <wsdl:operation> element that defines the web services call. The selected<wsdl:operation> must be part of the target <wsdl:service> and <wsdl:port>. Figure 2 shows you where you can locate the value of the name attribute in the WSDL definition.

Figure 2: Mapping for operation. Top: WSDL File, Bottom: MXML File
 

The <mx:operation> element has other attributes which values are independent of the WSDL but are worth mentioning. The result and fault attributes are ActionScript Event Handlers. They contain ActionScript code that is executed, respectively, once a SOAP response or a SOAP fault arrives.

Request mapping

After selecting the web services operations, Flex’s parameter binding mechanism is used to declare the parameters to these operations. As follows, each <mx:operation> element contains a <mx:request> element, which includes a mixture of XML and Flex bindings using ‘{}’.

<mx:WebService> <mx:operation> <mx:request> <node1>{var1}</node1> <node2>{var2}</node2> </mx:request> </mx:operation> </mx:WebService>

In general, the XML elements map to WSDL or Schema constructs and the MXML bindings refer to variables in the scope of the <mx:WebService> element.

Determining the content of each <mx:request> element can be challenging since it requires knowledge of the SOAP binding rules for WSDL. In particular, based on the operation style (document or literal) and the encoding mechanism (literal or encoded), the XML content of the <mx:request> element maps to different WSDL elements.

Common mappings

Document Oriented - Literal

The SOAP binding section in the WSDL definition determines the structure of the body in the SOAP message. It sets, among other properties, the operation style and the encoding mechanisms used. The operation style is defined in the style attribute of the <soap:operation> element inside the binding (XML tags prefixed by soap are part of the SOAP Binding namespace and are used inside WSDL definitions). Its value can be document for a Document Oriented operation or rpc for an RPC operation. In a Document Oriented operation, XML documents are exchanged within the SOAP body without any additional wrapping elements. In an RPC-style operation, the SOAP body is structured to represent a procedure call. It contains an element named after the operation wrapping a sequence of elements containing data and named after each of the operation’s parameters. Table 2 illustrates the differences in meaning between the SOAP bodies that the two styles generate.

Table 2. Semantic difference of Document and RPC-style operations

Document Style	RPC Style
<soap:Body> <node1> <node2> <node3>data</node3> <node4>data</node4> </node2> <node5>data</node5> </node1> ... </soap:Body>	<soap:Body> <operation_name> <parameter1>data</parameter1> <parameter2> <complex_element> <value1>data</value1> </complex_element> </parameter2> ... </operation_name> </soap:Body>

The encoding mechanism is determined by the use attribute of the <soap:body> in the binding. Its value can be literalfor a Literal/non-Encoded message or encoded for a message that needs to go through a defined set of encoding rules.

The following set of examples use a web service with three operations using the Document-Literal style. The differences among the three operations are the number and the complexity of their parameters. Figures 3, 4, and 5 illustrate how the content of the <mx:request> element map to elements defined in the WSDL definition for this web service.

Figure 3: Mapping of one parameter operation for a Document-Literal service call
 

Figure 4: Mapping of multiple parameter operation for a Document-Literal service call
 

Figure 5: Mapping of a complex parameter operation for a Document-Literal service call
 

The <wsdl:message> element for the request portion of the operation contains a <wsdl:part> element that refers to a schema-defined element using the attribute element. In a Document-Literal operation request, the element that the part refers to appears directly inside the SOAP body with no additional wrappers. As a result, the XML content of the<mx:request> element maps to the schema-defined elements that the message part refers to.

RPC-Oriented - Literal

The following examples use a web service with three operations with the same parameter signature as the previous example, but are defined in the WSDL as RPC-Literal operations. For these cases, the <wsdl:message> element contains one or more <wsdl:part> elements. Each <wsdl:part> element refers, with the value of the type attribute, to a schema-defined type. Figures 6, 7, and 8 illustrate how, for these cases, the content of the <mx:request> element maps to elements in the WSDL definition.

Figure 6: Mapping of one parameter operation for a RPC-Literal service call
 

Figure 7: Mapping of multiple parameter operation for a RPC-Literal service call
 

Figure 8: Mapping of a complex parameter operation for a RPC-Literal service call
 

The tested version of Flex (Beta 3) lays out each part in the order that they appear defined inside the <wsdl:message>element in the WSDL definition. It ignores the order set by the   parameterOrderattribute in the   >wsdl:operation>  element in the port type definition.

In an RPC-Oriented request, the SOAP message body contains a sequence of elements named after each <wsdl:part> element, all wrapped by an element named after the target<wsdl:operation>. Each element named after the <wsdl:part>is of the type specified in the type attribute. As a result, the top-level XML elements in the <mx:request> map to the names of the <wsdl:part> elements. The content of each of these XML elements depend on the type of the associated <wsdl:part>. In the case of a complex schema type, as in Figure 8, this content can be additional XML elements that map to schema-defined elements.

RPC-Oriented - Encoded

In a RPC-Encoded operation call, the content of the <mx:request> element maps to WSDL constructs in the same way as in the RPC-Literal example. It only differs in that the content of the SOAP message body contains extra type information that the encoding mechanism generates. It is important to note that the WS-I Basic Profile 1.0 does not include in its recommendation the use of any encoding mechanism. It prefers the use of literal (non-encoded) XML.

Other cases

The WSDL definitions used for these examples were automatically generated by Application Developer V5.1 Web Services Wizard. As a result, the structure of the generated WSDL follows a convention based on the values of the operation style. In particular, for Document-style operations, each <wsdl:message> element contains one <wsdl:part>that refers to a schema element. For RPC operations, a <wsdl:message> element contains a sequence of <wsdl:part>that refer to schema types. In a Literal message, the content of the SOAP body depends on whether the <wsdl:part>refers to an element or a type. Table 3 lists the possible combinations and explains the resulting SOAP message body (The shaded cells represent the cases of the above examples).

Table 3. Possible message part definitions and resulting body when using literal XML

Operation Style	Part refers to	SOAP Body
Document	element	The element referred to by the part appears inside the Body
	type	The type referred to by the part is used as the schema type for the Body (can’t handle multiple parts)
RPC	element	The element referred to by the part appears inside wrapping element named after the part.
	Type	The type referred to by the part is used as the schema type for the wrapping element named after the part.

Result mapping

Up until this point, we focused on defining the MXML elements needed to invoke a web services operation. Now we discuss how to process the result received from the web services call. As mentioned above, Flex treats all web services calls as asynchronous, meaning that the client is not blocked to wait for the response from the web service, rather it continues executing, and an event is fired once the result message is received. The result attribute of the<mx:operation> tag refers to the ActionScript code executed once the result message is received. Flex will deserialize the SOAP response into a graph of ActionScript objects. The result member of the operation object is a reference to this graph. The fully qualified name of the result object is as follows:

<value of WebService id>.<value of operation name>.result

The ActionScript dot notation is used to further navigate the result object, but requires that you know what the resultobject represents in the response XML. The same rules for mapping the WebService request to the WSDL file apply to mapping the result object and the WSDL.

 

 

Back to top

Conclusion

The move by organizations to quickly adopt strategies involving web services places a premium on having adequately adept development environments for building applications that use them. Moreover, since WSDL is typically the only service description, it can be tedious and time consuming to develop applications that integrate existing services. Macromedia Flex is a Rich Internet Application platform positioned exactly to address this set of requirements. Designers and server-side developers alike can create interactive and visually appealing applications easily while leveraging most systems' heavy investment in web services. Hopefully we have demonstrated that with a little understanding of basic WSDL constructs and how they correlate with the Flex <mx:WebService> declaration, rapid development of rich and engaging applications using Web Services is now a realistic requirement.

 

 

Back to top

Get the tools used in this article

If you are a developerWorks subscriber, you have a single user license to use WebSphere Studio Application Developer, and other DB2®, Lotus®, Rational®, Tivoli®, and WebSphere products -- including the Eclipse-based WebSphere Studio IDE -- to develop, test, evaluate, and demonstrate your applications. If you are not a subscriber, you can subscribe today.

 

Resources

• Find the Web Services Description Language (WSDL) 1.1 Specification from the World Wide Web Consortium (W3C). 
  
  
• Download Flex from Macromedia and consult the Flex Reference Documentation for more information. 
  
  
• Access web services knowledge, tools, and skills with Speed-start web services, which offers the latest Java-based software development tools and middleware from IBM (trial editions), plus online tutorials and articles, and an online technical forum.
  
  
• Browse for books on these and other technical topics.
  
  
• Want more? The developerWorks SOA and web services zone hosts hundreds of informative articles and introductory, intermediate, and advanced tutorials on how to develop web services applications.