3.2. Web Service Proxy

The Flex WebService component facilitates the interaction of a Flex client with a SOAP-based web service. Using this component, a Flex client can invoke remote operations on a web service and access data using such a service. Like HTTPService, the WebService component can access the services directly as long as these services are served from trusted domains. The domain from which the Flex client was served and those that define a security policy in a crossdomain.xml file are trusted domains as far as the Flex client is concerned. Read the note on crossdomain.xml at the beginning of this chapter if you need to review its features.

A SOAP web service publishes its available operations, the parameters it takes, the message type it returns, and the encoding it embodies in an XML-based format file, commonly called the WSDL. WSDL, which stands for Web Services Description Language, has become an acronym for the file itself as well as representing the format and the protocol. WSDL can be stored locally in the file system or be available as a web resource over a URI.

A web service component first expects to read and parse a WSDL for a service. If it successfully parses this, it calls the exposed operations. It can bind parameters to these operations and can receive responses, which it can subsequently consume.

Web service calls can be directed via a web service proxy on the server. This helps access SOAP-complaint services from domains that may not be explicitly trusted or where server-side control may be an advantage.

Before we dig deeper into web service proxy services, let's first view the involved communication stack. Figure 3-2 depicts the communication stack. It's analogous to Figure 3-1, which depicts the stack for an HTTP service proxy.

You will notice that up to the destination, the communication stack for the web services proxy is the same as for the HTTPServiceProxy. Things change at the adapter level. The web services proxy leverages the SOAPProxyAdapter. The SOAPProxyAdapter extends the HTTPProxyAdapter.

Figure 3.2. Figure 3-2

Flex supports WSDL 1.1 and supports both the RPC/encoded and document/literal WSDL bindings. Figure 3-3 depicts the different possible WSDL style/use combinations, which are RPC/encoded, RPC/literal, document/encoded, and document/literal. WSDL defines a web service, whereas WSDL binding describes how the web service is bound to the SOAP message protocol. RPCs and document style often make developers believe that these styles correspond to the programming styles that each of their names suggest. Contrarily though, these styles have nothing to do with the programming styles. The styles only address the WSDL-to-SOAP message mapping.

To illustrate further, a simple operation or method in Java can be written as follows:

public void aMethod(String x, int y);

Figure 3.3. Figure 3-3

When this method is exposed as a web service operation, it publishes an RPC/encoded WSDL for the service as follows:

<message name="aMethodRequest">
    <part name="x" type="xsd:string"/>
    <part name="y" type="xsd:int"/>
</message>
<message name="empty"/>

<portType name="aPortType">
    <operation name="aMethod">
        <input message="aMethodRequest"/>
        <output message="empty"/>
    </operation>
</portType>
....

Now if we were to call this method with parameters "hello" and 4, then the corresponding SOAP message would be as follows:

<soap:envelope>
    <soap:body>
        <aMethod>
            <x xsi:type="xsd:string">hello</x>
            <y xsi:type="xsd:int">4</y>
        </aMethod>
    </soap:body>
</soap:envelope>

If you chose the document/literal WSDL binding instead, then the WSDL would be as follows:

<types>
    <schema>
        <element name="xElement" type="xsd:string"/>
        <element name="yElement" type="xsd:int"/>
    </schema>
</types>

<message name="aMethodRequest">
    <part name="x" element="xElement"/>
    <part name="y" element="yElement"/>
</message>
<message name="empty"/>

<portType name="aPortType">
    <operation name="aMethod">
        <input message="aMethodRequest"/>
        <output message="empty"/>
    </operation>
</portType>
....

This time calling the operation with "hello" and 4 as the parameter involves a SOAP message as follows:

<soap:envelope>
    <soap:body>
        <xElement>hello</xElement>
        <yElement>4</yElement>
    </soap:body>
</soap:envelope>

In general, calling web service operations from Flex is straightforward. A WSDL is first read. If the WSDL is read and parsed successfully, web service operations are invoked by passing the required parameters. Event handlers are defined for success and failure conditions, which trigger result and fault events, respectively. On success, the response is obtained from the result event object and used within a Flex application as desired.

Alternatively, a Flex application can access a web service with the help of a client side library that publishes the endpoints. Using this option, the Flex application does not need to load and parse the WSDL.

As with the HTTP service, you set the useProxy property to true in order to leverage the proxy service. You also set the id and destination properties. The id is a reference to the WebService instance, and the destination points to a remote named destination configuration in services-config.xml. Such a WebService might look as follows:

<mx:WebService
    id="aWebService"
    useProxy="true"
    destination="wsdestination"/>

Next, we explore the server-side configuration for such a web service.

3.2.1. Configuring a Web Service Proxy

Two of the most important SOAP web service proxy configurations are:

• wsdl

• soap

A web service call is a two step-process. In the first step, an HTTP GET call is made to read and parse the WSDL. The wsdl property of WebService object specifies the URI for the WSDL. In the second step a web service operation is invoked. Web service operations are called using HTTP POST method. The soap property specifies the endpoint at which the operation can be invoked. Wildcards can be included in the URL to allow for multiple operations and their multiple related URL(s).

The soap destinations can be secured using constraints and the underlying Java EE authentication and authorization schemes as with the HTTPProxyService.

An example of destination configuration is:

<adapters>
    <adapter-definition
        id="soap-proxy"
        class="flex.messaging.services.http.SOAPProxyAdapter"/>
</adapters>
<destination id="wsdestination">
    <properties>
            <wsdl>http://www.shanky.org/samplews.asmx?wsdl</wsdl>
            <soap>*</soap>
    </properties>
    <adapter ref="soap-proxy"/>
</destination>

Two web service destination properties, wsdl and soap, are shown in the configuration above. You are already familiar with WSDL. The soap property is an optional property where you can explicitly specify the SOAP endpoint URL for HTTP POST based request-response. A wildcard, as shown above, implies all endpoints are exposed. The SOAP endpoint details are contained in the port section of a WSDL.

When you use BlazeDS, you can also leverage the state management in web services, without any extra configuration. Web service cookies are stored as Java session information in BlazeDS.

Although not exhaustive, that is as much as I have to say on web services as far as the proxy features go.