10.1 What Is a Web Service?

Strictly speaking, web services have been around for many years. By definition, a web service is any form of service that can be accessed by an application over the Internet. In the past few years, however, the term web services has come to mean any service that utilizes one of the standardized XML web service technologies, such as SOAP or XML-RPC.

The advantages of XML are widely known. Any technology can communicate with any other technology if they share a common language. XML is a standardized way of transferring information that almost every technology can understand. XML does, however, have some disadvantages. It is cumbersome, because the data has to be described using plain text tags. So, while it is human-readable, it doesn't provide the best format for transmitting binary data across wires. Flash Remoting circumvents this problem by passing data between the Flash Remoting adapter (the proxy for the web service) and the Flash client (the movie in the user's browser) using the AMF format discussed in Chapter 1.

A thorough discussion of web services is beyond the scope of this book. For more information on SOAP and web services, see Programming Web Services with SOAP by Pavel Kulchenko, James Snell, and Doug Tidwell (O'Reilly), which is a great introduction to SOAP-based web services. You can also find information at the W3C at http://www.w3.org/TR/SOAP.

A web service consists of three parts:

The service description

This is usually stored in a Universal Description, Discovery, and Integration (UDDI) service repository, such as XMethods at http://www.xmethods.com.

The service provider

The application server where the web service exists. The service provider generally provides a public description of the service, in the form of a Web Services Description Language (WSDL) document (an XML file with a .wsdl extension).

The service consumer

The application that consumes the web service, usually by sending an XML request to the service provider. In our case, the Flash Remoting adapter on our server is the service consumer and our Flash movie on the user's browser will access the content provided by the service.

A typical web service might look like this ASP.NET web service, written in Visual Basic.NET:

<%@ WebService language="VB" class="HelloUser" %>

Imports System
Imports System.Web.Services
Imports System.Xml.Serialization
<WebService(Namespace:="http://oreilly.com/frdg/")>Public Class HelloUser

    <WebMethod> Public Function sayHello(username as String) As String
      Dim currentTime as String
      currentTime = DateTime.Now.ToLongTimeString( )
      return "Hello " & username & ". It is " + currentTime
    End Function

End Class

The process of consuming a web service begins with a request to the server for a .wsdl document.

10.1.1 WSDL

The .wsdl file is where the publicly accessible service description lives. The language is XML, but it is strictly formatted to specifications so that a consumer of a web service can know exactly what is in the web service and how to utilize it. The .wsdl file is akin to a contract between the service provider and the consumer of the service. It contains information about what is needed by the service and what will be returned.

The .wsdl file consists of the following:

  • Information on all publicly available methods and how to interface to them

  • Datatype information for all method responses and requests

  • Address where the service can be found

  • Information about the protocol to be used

In many cases, the .wsdl file is an automatically generated document (as you saw earlier in the ColdFusion example in Chapter 1). The .wsdl file for a HelloUser web service, shown as a .cfc in Chapter 2, might look like this:

<?xml version="1.0" encoding="utf-8"?>
<definitions xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
xmlns:s="http://www.w3.org/2001/XMLSchema" xmlns:s0="http://oreilly.com/frdg/
    <s:schema elementFormDefault="qualified" targetNamespace="http://oreilly.com/frdg/">
      <s:element name="sayHello">
            <s:element minOccurs="0" maxOccurs="1" name="username"
             type="s:string" />
      <s:element name="sayHelloResponse">
            <s:element minOccurs="0" maxOccurs="1" name="sayHelloResult"
             type="s:string" />
      <s:element name="string" nillable="true" type="s:string" />
  <message name="sayHelloSoapIn">
    <part name="parameters" element="s0:sayHello" />
  <message name="sayHelloSoapOut">
    <part name="parameters" element="s0:sayHelloResponse" />
  <portType name="HelloUserSoap">
    <operation name="sayHello">
      <input message="s0:sayHelloSoapIn" />
      <output message="s0:sayHelloSoapOut" />
  <binding name="HelloUserSoap" type="s0:HelloUserSoap">
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
     style="document" />
    <operation name="sayHello">
      <soap:operation soapAction="http://oreilly.com/frdg/sayHello"
style="document" />
        <soap:body use="literal" />
        <soap:body use="literal" />
  <service name="HelloUser">
    <port name="HelloUserSoap" binding="s0:HelloUserSoap">
      <soap:address location="http://localhost/HelloUser.asmx" />

The .wsdl file tells consumers how to use the service. Specifically, it tells us the name of the service:

<service name="HelloUser">

the methods available:

<s:element name="sayHello">

the arguments of the method:

<s:element minOccurs="0" maxOccurs="1" name="username" type="s:string" />

and the response:

<s:element minOccurs="0" maxOccurs="1" name="sayHelloResult" type="s:string" />

More information on the WSDL specification can be found at http://www.w3.org/TR/wsdl.

The next point to consider is where to find the .wsdl files. In many cases, this is handled by UDDI.

10.1.2 UDDI

UDDI is the specification that allows web services to be listed in central service registries. Typically, the WSDL description of a web service is embedded into a UDDI registry. You can think of a UDDI registry as a table of contents to publicly available web services. A UDDI registry contains listings of WSDL documents and other web services. Three large UDDI registries can be found at http://www.xmethods.com, http://uddi.microsoft.com, and http://www-3.ibm.com/services/uddi.

Currently, the most popular technology for web services is SOAP.

10.1.3 SOAP

SOAP is nothing more than a standardized XML format that acts as an envelope for the service request and result. You pass your request to the web service using a SOAP envelope, and the service responds with a SOAP envelope. Because SOAP is based in XML, it is free of environmental dependencies, so you can use SOAP freely among different environments. SOAP envelopes are typically sent over HTTP, as the HTTP port 80 is readily available and accessible by most systems, and open to most firewalls.

Flash Remoting allows you to call your web service using familiar ActionScript syntax. The details of SOAP translation are hidden in the Flash Remoting adapter on the server. You call the service from Flash using a simple method name, and the Flash movie sends an AMF packet with the request to the Flash Remoting adapter on the server. The Flash Remoting adapter issues the request for the .wsdl file on the application server (a GET request). The server (ColdFusion MX, ASP.NET, PHP, or Java) proxies the request and creates a SOAP request to the web service. The SOAP response is sent back to Flash Remoting, which translates the response back to an AMF packet that the Flash Player can understand. (If using Flash Player 7, SOAP support is built into the Player and does not require a server-side Remoting adapter.)

The SOAP packet consists of two parts: the header and the body. The header is an optional element that contains information about the content. The body is contained in a <soap:Envelope> tag and contains the information about the request or the response.

A typical request envelope might look like this:

POST /com/oreilly/frdg/HelloUser.asmx HTTP/1.0
Content-Length: 355
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://oreilly.com/frdg/sayHello"

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
<sayHello xmlns="http://oreilly.com/frdg/">

This request was created by an ASP.NET application server upon receiving the GET request from the Flash Remoting adapter on the server. The sayHello( ) method of the web service can be plainly seen within the envelope body, along with the username parameter that was supplied in the Flash movie, "Tom". A response to that request might look like this:

HTTP/1.1 200 OK
Server: Microsoft-IIS/5.0
Date: Wed, 01 Jan 2003 01:20:19 GMT
Cache-Control: private, max-age=0
Content-Type: text/xml; charset=utf-8
Content-Length: 371

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
<sayHelloResponse xmlns="http://oreilly.com/frdg/">
<sayHelloResult>Hello Tom. It is 8:20:19 PM</sayHelloResult>

Again, the sayHello( ) method response can be identified as a <sayHelloResponse> tag in this envelope. The response from the server is contained within the <sayHelloResult> tag. In the case of Flash Remoting, the SOAP packets are processed entirely on the server. An AMF packet is returned to the Flash movie.

Handy utilities exist to examine SOAP packets. Check http://msdn.microsoft.com/webservices/downloads/microsoft/default.aspx for Microsoft's SOAP Toolkit, which contains the Trace Utility for ASP.NET web services. For Java, the TCPTunnelGUI tool, which is part of the Apache SOAP package at http://xml.apache.org/soap, works well. More information on SOAP can be found at http://www.w3.org/TR/SOAP.

As you saw in Chapter 1, you can create your own web services easily using ColdFusion. This chapter, however, focuses on consuming web services from Flash, not creating your own. One of the nice things about Flash Remoting is that you don't have to know about UDDI, WSDL, SOAP, or XML. All you need is the location of the .wsdl file, and the requirements of the service. You can usually find human-readable descriptions of web services from the service provider, or you can examine the .wsdl file to determine the services requirements.

    Part III: Advanced Flash Remoting