O'Reilly Media | Web Services Essentials

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Today, the principal use of the World Wide Web is for interactive access to documents and applications. In almost all cases, such access is by human users, typically working through Web browsers, audio players, or other interactive front-end systems. The Web can grow significantly in power and scope if it is extended to support communication between applications,from one program to another.

—From the W3C XML ProtocolWorking Group Charter

Welcome to the world of web services. This chapter will ground you in the basics of web service terminology and architecture. It does so by answering the most common questions, including:

What exactly is a web service?
What is the web service protocol stack?
What is XML messaging? Service description? Service discovery?
What are XML-RPC, SOAP, WSDL, and UDDI? How do these technologies complement each other and work together?
What security issues are unique to web services?
What standards currently exist?

A web service is any service that is available over the Internet, uses a standardized XML messaging system, and is not tied to any one operating system or programming language. (See Figure 1-1.)

Figure 1-1: A basic web service

There are several alternatives for XML messaging. For example, you could use XML Remote Procedure Calls (XML-RPC) or SOAP, both of which are described later in this chapter. Alternatively, you could just use HTTP GET/POST and pass arbitrary XML documents. Any of these options can work. (See Figure 1-2.)

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

A web service is any service that is available over the Internet, uses a standardized XML messaging system, and is not tied to any one operating system or programming language. (See Figure 1-1.)

Figure 1-1: A basic web service

There are several alternatives for XML messaging. For example, you could use XML Remote Procedure Calls (XML-RPC) or SOAP, both of which are described later in this chapter. Alternatively, you could just use HTTP GET/POST and pass arbitrary XML documents. Any of these options can work. (See Figure 1-2.)

Figure 1-2: XML messaging for web services

Although they are not required, a web service may also have two additional (and desirable) properties:

A web service should be self-describing. If you publish a new web service, you should also publish a public interface to the service. At a minimum, your service should include human-readable documentation so that other developers can more easily integrate your service. If you have created a SOAP service, you should also ideally include a public interface written in a common XML grammar. The XML grammar can be used to identify all public methods, method arguments, and return values.
A web service should be discoverable. If you create a web service, there should be a relatively simple mechanism for you to publish this fact. Likewise, there should be some simple mechanism whereby interested parties can find the service and locate its public interface. The exact mechanism could be via a completely decentralized system or a more logically centralized registry system.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

There are two ways to view the web service architecture. The first is to examine the individual roles of each web service actor; the second is to examine the emerging web service protocol stack.

There are three major roles within the web service architecture:

Service provider: This is the provider of the web service. The service provider implements the service and makes it available on the Internet.
Service requestor: This is any consumer of the web service. The requestor utilizes an existing web service by opening a network connection and sending an XML request.
Service registry: This is a logically centralized directory of services. The registry provides a central place where developers can publish new services or find existing ones. It therefore serves as a centralized clearinghouse for companies and their services.

Figure 1-6 shows the major web service roles and how they interact with each other.

Figure 1-6: Web service roles

A second option for viewing the web service architecture is to examine the emerging web service protocol stack. The stack is still evolving, but currently has four main layers. Following is a brief description of each layer.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

XML has exploded onto the computing scene in recent years. It has gained rapid acceptance because it enables diverse computer systems to share data more easily, regardless of operating system or programming language. There are dozens of XML tools, including parsers and editors that are available for nearly every operating system and every programming language, including Java, Perl, Python, C#, C, C++, and Ruby. When developers decided to build a web service messaging system, XML was therefore a natural choice. There are two main contenders for XML messaging: XML-RPC and SOAP. The following sections provide descriptions of both protocols.

XML-RPC is a simple protocol that uses XML messages to perform RPCs. Requests are encoded in XML and sent via HTTP POST. XML responses are embedded in the body of the HTTP response. Because XML-RPC is platform-independent, it allows diverse applications to communicate. For example, a Java client can speak XML-RPC to a Perl server.

To gain a high-level understanding of XML-RPC, consider a simple weather service. The service expects a zip code and returns the current temperature for the area. Here is a sample XML-RPC request to the weather service (HTTP headers omitted):

<?xml version="1.0" encoding="ISO-8859-1"?>
<methodCall>
   <methodName>weather.getWeather</methodName>
   <params>
      <param><value>10016</value></param>
   </params>
</methodCall>

The request consists of a simple methodCall element that specifies the method name and any method parameters.

Here is a sample XML-RPC response from the weather service:

<?xml version="1.0" encoding="ISO-8859-1"?>
<methodResponse>
   <params>
      <param>
         <value><int>65</int></value>
      </param>
   </params>
</methodResponse>

The response consists of a single

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

WSDL currently represents the service description layer within the web service protocol stack. In a nutshell, WSDL is an XML grammar for specifying a public interface for a web service. This public interface can include information on all publicly available functions, data type information for all XML messages, binding information about the specific transport protocol to be used, and address information for locating the specified service. WSDL is not necessarily tied to a specific XML messaging system, but it does include built-in extensions for describing SOAP services.

Example 1-1 provides a sample WSDL file. This file describes the public interface for the weather service we examined previously. Obviously, there are many details to consider when looking at the example. For now, just focus on two points. First, the message elements specify the individual XML messages that are transferred between computers. In this case, we have a getWeatherRequest and a getWeatherResponse. Second, the service element specifies that the service is available via SOAP at http://localhost:8080/soap/servlet/rpcrouter.

Example 1-1. WeatherService.wsdl

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="WeatherService"
   targetNamespace="http://www.ecerami.com/wsdl/WeatherService.wsdl"
   xmlns="http://schemas.xmlsoap.org/wsdl/"
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
   xmlns:tns="http://www.ecerami.com/wsdl/WeatherService.wsdl"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema">

   <message name="getWeatherRequest">
      <part name="zipcode" type="xsd:string"/>
   </message>
   <message name="getWeatherResponse">
      <part name="temperature" type="xsd:int"/>
   </message>

   <portType name="Weather_PortType">
      <operation name="getWeather">
         <input message="tns:getWeatherRequest"/>
         <output message="tns:getWeatherResponse"/>
      </operation>
   </portType>
   
   <binding name="Weather_Binding" type="tns:Weather_PortType">
      <soap:binding style="rpc" 
         transport="http://schemas.xmlsoap.org/soap/http"/>
      <operation name="getWeather">
         <soap:operation soapAction=""/>
         <input>
            <soap:body
               encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
               namespace="urn:examples:weatherservice"
               use="encoded"/>
         </input>
         <output>
            <soap:body
               encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
               namespace="urn:examples:weatherservice"
               use="encoded"/>
         </output>
      </operation>
   </binding>

   <service name="Weather_Service">
      <documentation>WSDL File for Weather Service</documentation>
      <port binding="tns:Weather_Binding" name="Weather_Port">
         <soap:address 
            location="http://localhost:8080/soap/servlet/rpcrouter"/>
      </port>
   </service>
</definitions>

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

UDDI currently represents the discovery layer within the web service protocol stack. UDDI was originally created by Microsoft, IBM, and Ariba, and represents a technical specification for publishing and finding businesses and web services.

At its core, UDDI consists of two parts. First, UDDI is a technical specification for building a distributed directory of businesses and web services. Data is stored within a specific XML format. The UDDI specification includes API details for searching existing data and publishing new data. Second, the UDDI Business Registry is a fully operational implementation of the UDDI specification. Launched in May 2001 by Microsoft and IBM, the UDDI registry now enables anyone to search existing UDDI data. It also enables any company to register itself and its services.

The data captured within UDDI is divided into three main categories:

White pages: This category includes general information about a specific company; for example, business name, business description, and address.
Yellow pages: This category includes general classification data for either the company or the service offered. For example, this data may include industry, product, or geographic codes based on standard taxonomies.
Green pages: This category includes technical information about a web service (a pointer to an external specification and an address for invoking the web service).

Figure 1-13 shows a sample screenshot of the Microsoft UDDI site. From this site, you can easily publish your own services or search for existing ones.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

The bottom of the web service protocol stack is service transport. This layer is responsible for actually transporting XML messages between two computers.

Currently, HTTP is the most popular option for service transport. HTTP is simple, stable, and widely deployed. Furthermore, most firewalls allow HTTP traffic. This allows XML-RPC or SOAP messages to masquerade as HTTP messages. This is good if you want to easily integrate remote applications, but it does raise a number of security concerns. (See Section 1.7 later in this chapter.)

While HTTP does get the job done, a number of critics have argued that HTTP is not ideal for web services. In particular, HTTP was originally designed for remote document retrieval, and is now being reworked to support RPCs. RPCs demand greater efficiency and reliability than document retrieval does.

There are some developers who argue that HTTP is enough of a foundation for messaging and that the layers above HTTP are as much a problem as a solution. For some of this perspective, called Representational State Transfer, or REST, see http://internet.conveyor.com/RESTwiki/moin.cgi.

One promising alternative to HTTP is the Blocks Extensible Exchange Protocol (BEEP). BEEP is a new IETF framework of best practices for building new protocols. In particular, BEEP is layered directly on TCP and includes a number of built-in features, including an initial handshake protocol, authentication, security, and error handling. Using BEEP, one can create new protocols for a variety of applications, including instant messaging, file transfer, content syndication, and network management.

SOAP is not tied to any specific transport protocol. In fact, you can use SOAP via HTTP, SMTP, or FTP. One promising idea is therefore to use SOAP over BEEP. Doing so provides several performance advantages over HTTP. Specifically, BEEP does require an initial handshake, but after the handshake, the protocol requires only 30 bytes of overhead for each message, making it much more efficient than HTTP. Furthermore, BEEP supports multiple channels of data over the same connection, providing extra efficiency over HTTP.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Security is critical to web services. However, neither the XML-RPC nor SOAP specifications make any explicit security or authentication requirements. Furthermore, the web services community has proposed numerous security frameworks and protocols, but has yet to reach consensus on a comprehensive security package.

Very broadly, there are three specific security issues: confidentiality, authentication, and network security.

If a client sends an XML request to a server, can we ensure that the communication remains confidential?

Fortunately, both XML-RPC and SOAP run primarily on top of HTTP, and XML communications can therefore be encrypted via the Secure Sockets Layer (SSL). SSL is a proven technology, is widely deployed, and is therefore a very viable option for encrypting messages.

However, a key element of web services is that a single web service may consist of a chain of applications. For example, one large service might tie together the services of three other applications. In this case, SSL is not adequate; the messages need to be encrypted at each node along the service path, and each node represents a potential weak link in the chain. Currently, there is no agreed-upon solution to this issue, but one promising solution is the W3C XML Encryption Standard. This standard provides a framework for encrypting and decrypting entire XML documents or just portions of an XML document, and it is likely to receive widespread industry support. Information on the XML Encryption Standard is available at http://www.w3.org/Encryption/.

If a client connects to a web service, how do we identify the user? And is the user authorized to use the service?

One solution is to leverage HTTP authentication. HTTP includes built-in support for Basic and Digest authentication, and services can therefore be protected in much the same manner as HTML documents are currently protected. Most security experts, however, agree that HTTP authentication is a relatively weak option.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Once you understand each layer in the web service protocol stack, the next important step is to understand how all the pieces fit together. There are two ways of approaching the issue, either from the service requestor perspective or the service provider perspective. In this section, we examine both perspectives and look at a typical development plan for each.

The service requestor is any consumer of web services. Here is a typical development plan for a service requestor:

First, you must identify and discover those services that are relevant to your application. This first step therefore usually involves searching the UDDI Business Directory for partners and services.
Once you have identified the service you want, the next step is to locate a service description. If this is a SOAP service, you are likely to find a WSDL document. If this is an XML-RPC service, you are likely to find some human-readable instructions for integration.
Third, you must create a client application. For example, you may create an XML-RPC or SOAP client in the language of your choice. If the service has a WSDL file, you also have the option of automatically creating client code via a WSDL invocation tool.
Finally, run your client application to actually invoke the web service.

A snapshot of the service requestor perspective is provided in Figure 1-14.

Figure 1-14: Developing web services: the service requestor perspective

The service provider is any provider of one or more web services. Here is a typical development plan for a service provider:

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Web services are still in their infancy, but they are poised to make great inroads in the world of distributed application development. The most crucial elements to the long-term success of web services, however, will be standardization and the coherency of those standards. Currently, none of the web service technologies described in this book has any official standing with the W3C or the IETF. SOAP and WSDL have both been submitted to the W3C, but have no official recommendation status. XML-RPC has not been submitted to any standards body. UDDI is currently under the purview of an industry consortium and will probably go through several more iterations before being handed over to a standards body.

In September 2000, the W3C created an XML Protocol Group. This group represented the W3C's first official foray into the world of web services. Its first task was to create an official recommendation for SOAP, and the group is currently finalizing a SOAP 1.2 specification. In January 2002, the W3C incorporated the XML Protocol Group into a more general Web Services Activity. The new Activity adds Working Groups for Web Services Architecutre and Web Services Description.

Information about the W3C Web Services Activity is available at http://www.w3.org/2002/ws/.

Most people new to web services are initially overwhelmed by the long list of proposed standards and the complex interactions between each. Standardizing each layer in the web service protocol stack will be a major challenge. Making sure all the layers fit together and make coherent sense to developers will be an even greater challenge.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

XML-RPC provides an XML- and HTTP-based mechanism for making method or function calls across a network. XML-RPC offers a very simple, but frequently useful, set of tools for connecting disparate systems and for publishing machine-readable information. This chapter provides a complete overview of XML-RPC, covering the following topics:

An introduction to the main concepts and history of XML-RPC
An exploration of XML-RPC usage scenarios, examining its use in glue code and information publishing
A technical overview of XML-RPC, including a detailed explanation of XML-RPC data types, requests, and responses
An example demonstrating the use of XML-RPC to connect programs written in Java and Perl

XML-RPC permits programs to make function or procedure calls across a network. XML-RPC uses the HTTP protocol to pass information from a client computer to a server computer, describing the nature of requests and responses with a small XML vocabulary. Clients specify a procedure name and parameters in the XML request, and the server returns either a fault or a response in the XML response. XML-RPC parameters are a simple list of types and content—structs and arrays are the most complex types available. XML-RPC has no notion of objects and no mechanism for including information that uses other XML vocabularies. Despite those limitations, it has proven capable of a wide variety of tasks.

XML-RPC emerged in early 1998; it was published by UserLand Software and initially implemented in their Frontier product. It has remained largely stable since then. The XML-RPC specification is available at http://www.xmlrpc.com/spec, and a list of implementations (55 at this writing, in a wide variety of languages) is available at http://www.xmlrpc.com/directory/1568/

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

XML-RPC permits programs to make function or procedure calls across a network. XML-RPC uses the HTTP protocol to pass information from a client computer to a server computer, describing the nature of requests and responses with a small XML vocabulary. Clients specify a procedure name and parameters in the XML request, and the server returns either a fault or a response in the XML response. XML-RPC parameters are a simple list of types and content—structs and arrays are the most complex types available. XML-RPC has no notion of objects and no mechanism for including information that uses other XML vocabularies. Despite those limitations, it has proven capable of a wide variety of tasks.

XML-RPC emerged in early 1998; it was published by UserLand Software and initially implemented in their Frontier product. It has remained largely stable since then. The XML-RPC specification is available at http://www.xmlrpc.com/spec, and a list of implementations (55 at this writing, in a wide variety of languages) is available at http://www.xmlrpc.com/directory/1568/.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

In a programming universe seemingly obsessed with objects, XML-RPC may seem too limited for many applications. While XML-RPC certainly has limitations, its inherent simplicity gives it some significant advantages when developers need to integrate systems of very different types. XML-RPC's selection of data types is relatively small, but provides enough granularity that developers can express information in forms any programming language can use.

XML-RPC is used in two main areas, which overlap at times. Systems integrators and programmers building distributed systems often use XML-RPC as glue code, connecting disparate parts inside a private network. By using XML-RPC, developers can focus on the interfaces between systems, not the protocol used to connect those interfaces. Developers building public services can also use XML-RPC, defining an interface and implementing it in the language of their choice. Once that service is published to the Web, any XML-RPC-capable client can connect to that service, and developers can create their own applications that use that service.

As distributed systems have become more and more common (by design or by accident), developers have had to address integration problems more and more frequently. Systems that originally ran their own show have to work with other systems as organizations try to rationalize their information management and reduce duplication. This often means that Unix systems need to speak with Windows, which needs to speak with Linux, which needs to speak with mainframes. A lot of programmers have spent a lot of time building custom protocols and formats to let different systems speak to each other.

Instead of creating custom systems that need extensive testing, documentation, and debugging, developers can use XML-RPC to connect programs running on different systems and environments. Using this approach, developers can use existing APIs and add connections to those APIs as necessary. Some problems can be solved with a single procedure, while others require more complex interactions, but the overall approach is much like developing any other set of interfaces. In glue code situations, the distinction between client and server isn't especially significant—the terms only identify the program making the request and the program responding. The same program may have both client and server implementations, allowing it to use XML-RPC for both incoming and outgoing requests.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

XML-RPC consists of three relatively small parts:

XML-RPC data model: A set of types for use in passing parameters, return values, and faults (error messages)
XML-RPC request structures: An HTTP POST request containing method and parameter information
XML-RPC response structures: An HTTP response that contains return values or fault information

The data structures are used by both the request and response structures. The combination of the three parts defines a complete Remote Procedure Call.

It's entirely possible to use XML-RPC without getting into the markup details presented later in this chapter. Even if you plan to stay above the details, however, you probably should read the following sections to understand the nature of the information you'll be passing across the network.

The XML-RPC specification defines six basic data types and two compound data types that represent combinations of types. While this is a much more restricted set of types than many programming languages provide, it's enough to represent many kinds of information, and it seems to have hit the lowest common denominator for many kinds of program-to-program communications.

All of the basic types are represented by simple XML elements whose content provides the value. For example, to define a string whose value is "Hello World!", you'd write:

<string>Hello World!</string>

The basic types for XML-RPC are listed in Table 2-1.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Using XML-RPC in your applications generally means adding an XML-RPC library and making some of your function calls through that library. Creating functions that will work smoothly with XML-RPC requires writing code that uses only the basic types XML-RPC supports. Otherwise, there is very little fundamental need to change your coding style. Adding XML-RPC support may require writing some wrapper code that connects your code with the library, but this generally isn't very difficult.

As XML-RPC becomes more and more widespread, some environments are building in XML-RPC. UserLand Frontier has done that for years, while the Perl and Python communities are discussing similar integration.

To demonstrate XML-RPC, we're going to create a server that uses Java to process XML-RPC messages, and Java and Perl clients to call procedures on that server. Although this demonstration is simple, it illustrates the connections needed to establish communications between programs using XML-RPC.

The Java side of the conversation uses the Apache XML Project's Apache XML-RPC, available at http://xml.apache.org/xmlrpc/. The Apache package includes a few key pieces that make integrating XML-RPC with Java easier:

An automated registration process for adding methods to the XML-RPC server
A built-in server that only speaks XML-RPC, reducing the need to create full-blown servlets
A client package that makes calling remote methods fairly simple

This demonstration will use a procedure registered with the built-in server of the Apache package and a client for testing the procedure.

For much more information about the Apache XML-RPC package, including data type details and information about creating servlets for XML-RPC processing, see Chapter 3 of

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

XML-RPC is a very simple concept with a limited set of capabilities. Those limitations are in many ways the most attractive feature of XML-RPC, as they substantially reduce the difficulty of implementing the protocol and testing its interoperability. While XML-RPC is simple, the creative application of simple tools can create sophisticated and powerful architectures. In cases where a wide variety of different systems need to communicate, XML-RPC may be the most appropriate lowest common denominator.

Some use cases only require basic functionality, like the library-style functionality described earlier. XML-RPC can support much richer development than these examples show, using combinations of arrays and structs to pass complex sets of information. While calculating the area of a circle may not be very exciting, working with matrices or processing sets of strings may be more immediately worthwhile. XML-RPC itself doesn't provide support for state management, but applications can use parameters to sustain conversations beyond a single request-response cycle, much as web developers use cookies to keep track of extended conversations.

Servers may be able to use XML-RPC to deliver information requested by clients, providing a window on a large collection of information. The O'Reilly Network's Meerkat uses XML-RPC this way, letting clients specify the information they need to receive through XML-RPC procedures. XML-RPC can also be very useful in cases where a client needs to deliver information to a server, both for logging-style operations and operations where the client needs to set properties on a server program. The richness of the interface is up to the developer, but the possibilities are definitely there.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

SOAP is an XML-based protocol for exchanging information between computers. Although SOAP can be used in a variety of messaging systems and can be delivered via a variety of transport protocols, the initial focus of SOAP is remote procedure calls transported via HTTP. SOAP therefore enables client applications to easily connect to remote services and invoke remote methods. For example (as we shall soon see), a client application can immediately add language translation to its feature set by locating the correct SOAP service and invoking the correct method.

Other frameworks, including CORBA, DCOM, and Java RMI, provide similar functionality to SOAP, but SOAP messages are written entirely in XML and are therefore uniquely platform- and language-independent. For example, a SOAP Java client running on Linux or a Perl client running on Solaris can connect to a Microsoft SOAP server running on Windows 2000.

SOAP therefore represents a cornerstone of the web service architecture, enabling diverse applications to easily exchange services and data.

Although still in its infancy, SOAP has received widespread industry support. Dozens of SOAP implementations now exist, including implementations for Java, COM, Perl, C#, and Python. At the same time, hundreds of SOAP services are blossoming across the Web.

This chapter aims to provide you with the essentials of SOAP. The following topics are covered:

A quick overview of the SOAP protocol and a sample SOAP conversation
Details about the SOAP XML Message specification
An overview of the SOAP encoding rules, including rules for simple types, arrays, and structs
Details about using SOAP via HTTP
An overview of the W3C activities related to SOAP
An overview of the four main SOAP implementations and a description of the main SOAP interoperability issues

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

The SOAP specification defines three major parts:

SOAP envelope specification: The SOAP XML Envelope defines specific rules for encapsulating data being transferred between computers. This includes application-specific data, such as the method name to invoke, method parameters, or return values. It can also include information about who should process the envelope contents and, in the event of failure, how to encode error messages.
Data encoding rules: To exchange data, computers must agree on rules for encoding specific data types. For example, two computers that process stock quotes need an agreed-upon rule for encoding float data types; likewise, two computers that process multiple stock quotes need an agreed-upon rule for encoding arrays. SOAP therefore includes its own set of conventions for encoding data types. Most of these conventions are based on the W3C XML Schema specification.
RPC conventions: SOAP can be used in a variety of messaging systems, including one-way and two-way messaging. For two-way messaging, SOAP defines a simple convention for representing remote procedure calls and responses. This enables a client application to specify a remote method name, include any number of parameters, and receive a response from the server.

To examine the specifics of the SOAP protocol, we begin by presenting a sample SOAP conversation. XMethods.net provides a simple weather service, listing current temperature by zip code. (See Figure 3-1.) The service method, getTemp, requires a zip code string and returns a single float value.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

If you are eager to start coding your own SOAP applications, you may want to skip ahead to the Section 3.6 section, later in this chapter. Otherwise, the following section provides additional details regarding the SOAP specification itself.

A one-way message, a request from a client, or a response from a server is officially referred to as a SOAP message. Every SOAP message has a mandatory Envelope element, an optional Header element, and a mandatory Body element. (See Figure 3-2.) Each of these elements has an associated set of rules, and understanding the rules will help you debug your own SOAP applications.

Figure 3-2: Main elements of the XML SOAP message

Every SOAP message has a root Envelope element. In contrast to other specifications, such as HTTP and XML, SOAP does not define a traditional versioning model based on major and minor release numbers (e.g., HTTP 1.0 versus HTTP 1.1). Rather, SOAP uses XML namespaces to differentiate versions. The version must be referenced within the Envelope element. For example:

<SOAP-ENV:Envelope 
   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"

The SOAP 1.1 namespace URI is http://schemas.xmlsoap.org/soap/envelope/, whereas the SOAP 1.2 namespace URI is http://www.w3.org/2001/09/soap-envelope. If the Envelope is in any other namespace, it is considered a versioning error.

The optional Header element offers a flexible framework for specifying additional application-level requirements. For example, the Header element can be used to specify a digital signature for password-protected services; likewise, it can be used to specify an account number for pay-per-use SOAP services. Many current SOAP services do not utilize the

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

SOAP includes a built-in set of rules for encoding data types. This enables the SOAP message to indicate specific data types, such as integers, floats, doubles, or arrays. Most of the time, the encoding rules are implemented directly by the SOAP toolkit you choose, and are therefore hidden from you. It is nonetheless useful to understand the basics of SOAP encoding, particularly if you are intercepting SOAP messages and trying to debug an application. Note also that while the W3C specification encourages the use of SOAP encoding rules, these rules are not required; this enables you to choose a different encoding schema, should the need arise.

When exploring the SOAP encoding rules, it is important to note that the XML 1.0 specification does not include rules for encoding data types. The original SOAP specification therefore had to define its own data encoding rules. Subsequent to early drafts of the SOAP specification, the W3C released the XML Schema specification. The XML Schema Part 2: Datatypes specification provides a standard framework for encoding data types within XML documents. The SOAP specification therefore adopted the XML Schema conventions. However, even though the latest SOAP specification adopts all the built-in types defined by XML Schema, it still maintains its own convention for defining constructs not standardized by XML Schema, such as arrays and references. Arrays are discussed in detail in the Section 3.3.2 section, later in this chapter.

SOAP data types are divided into two broad categories: scalar types and compound types. Scalar types contain exactly one value, such as a last name, price, or product description. Compound types contain multiple values, such as a purchase order or a list of stock quotes. Compound types are further subdivided into arrays and structs. Arrays contain multiple values, each of which is specified by an ordinal position. Structs also contain multiple values, but each element is specified by an accessor name.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

SOAP is not tied to any one transport protocol. In fact, SOAP can be transported via SMTP, FTP, IBM's MQSeries, or Microsoft Message Queuing (MSMQ). However, the SOAP specification includes details on HTTP only, and HTTP remains the most popular SOAP transport protocol.

Quite logically, SOAP requests are sent via an HTTP request and SOAP responses are returned within the content of the HTTP response. While SOAP requests can be sent via an HTTP GET, the specification includes details on HTTP POST only. (HTTP POST is preferred because most servers place a character limit on GET requests.) Additionally, both HTTP requests and responses are required to set their content type to text/xml.

As an additional requirement, clients must specify a SOAPAction header. The SOAPAction header is a server-specific URI used to indicate the intent of the request. This makes it possible to quickly determine the nature of the SOAP request, without actually examining the SOAP message payload. In practice, the header is frequently used by firewalls as a mechanism for blocking out SOAP requests or for quickly dispatching SOAP messages to specific SOAP servers.

The SOAP specification mandates that the client must provide a SOAPAction header, but the actual value of the SOAPAction header is dependent on the SOAP server implementation. For example, to access the AltaVista BabelFish Translation service, hosted by XMethods, you must specify the urn:xmethodsBabelFish#BabelFish as the SOAPAction header. Even if the server does not require a full SOAPAction header, the client must specify an empty string (""), or a null value. For example:

SOAPAction: ""
SOAPAction:

Here is a sample request sent via HTTP to the XMethods Babelfish Translation service:

POST /perl/soaplite.cgi HTTP/1.0
Host: services.xmethods.com
Content-Type: text/xml; charset=utf-8
Content-Length: 538
SOAPAction: "urn:xmethodsBabelFish#BabelFish"

<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope
   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
   xmlns:xsd="http://www.w3.org/1999/XMLSchema">
   <SOAP-ENV:Body>
      <ns1:BabelFish 
      xmlns:ns1="urn:xmethodsBabelFish"
      SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <translationmode xsi:type="xsd:string">en_fr</translationmode>
         <sourcedata xsi:type="xsd:string">Hello, world!</sourcedata>
      </ns1:BabelFish>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

SOAP 1.1 was originally submitted to the W3C in May 2000. Official submitters included large companies, such as Microsoft, IBM, and Ariba, and smaller companies, such as UserLand Software and DevelopMentor.

In September 2000, the W3C created a new XML Protocol Working Group. The goal of the group is to hammer out an XML protocol for information exchange and recommend the protocol as an official W3C recommendation.

In July 2001, the XML Protocol Working Group released a "working draft" of SOAP 1.2. Within the W3C, this document is officially a work in progress, meaning that the document is likely to be updated many times before it is finalized. However, so far, SOAP 1.2 does not represent a radical departure from SOAP 1.1 and is primarily aimed at clarifying ambiguous issues within the SOAP 1.1 specification. Most developers should therefore find the transition from 1.1 to 1.2 relatively painless.

The W3C has broken the SOAP 1.2 specification into two parts. Part I describes the SOAP messaging framework and envelope specification. Part II describes the SOAP encoding rules, the SOAP-RPC convention, and HTTP binding details.

Once finalized, SOAP may work its way up to official W3C recommendation status. Until that time, however, it is important to note that SOAP has no official commitment from the W3C. Even SOAP 1.1 has a status of "Note", meaning that it is currently open to the W3C membership for discussion.

SOAP originally stood for Simple Object Access Protocol. The W3C was uncomfortable with maintaining this definition, primarily because the specification does not actually mandate the use of objects. On the other hand, the W3C was also reluctant to define a new name, such as XML Protocol, or XML-P, primarily because the term SOAP was already well established among developers. Hence, in a bizarre twist of fate, the name SOAP stays, but the W3C now says it no longer stands for anything.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Dozens of SOAP implementations now freely exist on the Internet. In fact, as of this writing, SOAPWare.org has referenced a total of 65 implementations. Here are four of the most popular and widely cited implementations.

Apache SOAP (http://xml.apache.org/soap/): Open source Java implementation of the SOAP protocol; based on the IBM SOAP4J implementation
Microsoft SOAP ToolKit 2.0 (http://msdn.microsoft.com/soap/default.asp): COM implementation of the SOAP protocol for C#, C++, Visual Basic, or other COM-compliant languages
SOAP::Lite for Perl (http://www.soaplite.com/): Perl implementation of the SOAP protocol, written by Paul Kulchenko, that includes support for WSDL and UDDI
GLUE from the Mind Electric (http://www.themindelectric.com): Java implementation of the SOAP protocol that includes support for WSDL and UDDI

Complete information on Apache SOAP is provided in Chapter 4 and Chapter 5. SOAP::Lite and GLUE are discussed briefly in Chapter 6. For a more complete list, or to find a SOAP implementation for your language or platform of choice, check out http://www.soapware.org/directory/4/implementations.

SOAP was specifically designed to solve platform and language interoperability problems. It is therefore ironic that SOAP itself has its own interoperability problems, but alas, this is currently true. For example, as of this writing, there are known interoperability issues between Apache SOAP, SOAP::Lite for Perl, and the Microsoft SOAP ToolKit. Apache SOAP requires all parameters to be typed via the

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Apache SOAP is an open source Java implementation of the SOAP specification. The original Apache code is based on IBM's SOAP4J, which IBM donated to the Apache open source community. Like all Apache projects, Apache SOAP is free for both noncommercial and commercial purposes. The source code is readily available, and an active group of programmers is busy adding new features for future releases.

This chapter provides a quick start introduction to using Apache SOAP. The goal is to present the most important essentials so that you can start coding and get to work. Four specific topics will be covered:

Installation instructions for using Apache SOAP with the open source Jakarta Tomcat server
A "Hello, SOAP!" client/service application for demonstrating basic SOAP RPC coding
An overview of deploying and managing SOAP services via the web-based administration tool and the command-line ServiceManagerClient tool
Tips for viewing live SOAP conversations using the TcpTunnelGui tool

If you are only creating SOAP clients, all you need to do is download the correct suite of files and include the relevant JAR files within your CLASSPATH (details to follow). If, however, you are creating SOAP services, you need the right files plus a Java servlet engine. For example, you can install Apache SOAP to BEA WebLogic Application Server, IBM WebSphere, or Allaire JRun. This section includes specific instructions for installing to the open source Apache Jakarta Tomcat 3.2 server. Tomcat is free, easy to set up, and gets you running in just a few minutes.

You need a Java servlet engine to set up SOAP services because the Apache SOAP service, called rpcrouter, is really just a Java servlet that has been configured to receive SOAP requests.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

If you are only creating SOAP clients, all you need to do is download the correct suite of files and include the relevant JAR files within your CLASSPATH (details to follow). If, however, you are creating SOAP services, you need the right files plus a Java servlet engine. For example, you can install Apache SOAP to BEA WebLogic Application Server, IBM WebSphere, or Allaire JRun. This section includes specific instructions for installing to the open source Apache Jakarta Tomcat 3.2 server. Tomcat is free, easy to set up, and gets you running in just a few minutes.

You need a Java servlet engine to set up SOAP services because the Apache SOAP service, called rpcrouter, is really just a Java servlet that has been configured to receive SOAP requests.

To install Apache SOAP to Jakarta Tomcat, you need to download five distribution files. First, download the Tomcat and Apache SOAP distributions:

Apache Jakarta Tomcat: http://jakarta.apache.org/tomcat/
Apache SOAP: http://xml.apache.org/soap/

Then, download the Xerces Java Parser, Java Mail, and JavaBeans Activation Framework distributions:

Xerces Java Parser (Version 1.1.2 or higher): http://xml.apache.org/xerces-j/index.html
Java Mail: http://java.sun.com/products/javamail/
JavaBeans Activation Framework: http://java.sun.com/products/javabeans/glasgow/jaf.html

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|

Table of Contents