Java Web Services | O'Reilly Media

BUY THIS BOOK

This print book is out of stock, with no immediate plans to reprint.

Safari Books Online

What is this?

Looking to Reprint this content?

Tell a friend

Java Web Services

By David A. Chappell, Tyler Jewell
Price: $39.95 USD
£28.50 GBP

Cover | Table of Contents | Colophon

Chapter 1: Welcome to Web Services

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

The promise of web services is to enable a distributed environment in which any number of applications, or application components, can interoperate seamlessly among and between organizations in a platform-neutral, language-neutral fashion. This interoperation brings heterogeneity to the world of distributed computing once and for all.

This book defines the fundamentals of a web service. It explores the core technologies that enable web services to interoperate with one another. In addition, it describes the distributed computing model that the core web service technologies enable and how it fits into the bigger picture of integration and deployment within the J2EE platform. It also discusses interoperability between the J2EE platform and other platforms such as .NET.

A web service is a piece of business logic, located somewhere on the Internet, that is accessible through standard-based Internet protocols such as HTTP or SMTP. Using a web service could be as simple as logging into a site or as complex as facilitating a multi-organization business negotiation.

Given this definition, several technologies used in recent years could have been classified as web service technology, but were not. These technologies include win32 technologies, J2EE, CORBA, and CGI scripting. The major difference between these technologies and the new breed of technology that are labeled as web services is their standardization. This new breed of technology is based on standardized XML (as opposed to a proprietary binary standard) and supported globally by most major technology firms. XML provides a language-neutral way for representing data, and the global corporate support ensures that every major new software technology will have a web services strategy within the next couple years. When combined, the software integration and interoperability possibilities for software programs leveraging the web services model are staggering.

A web service has special behavioral characteristics:

XML-based: By using XML as the data representation layer for all web services protocols and technologies that are created, these technologies can be interoperable at their core level. As a data transport, XML eliminates any networking, operating system, or platform binding that a protocol has.

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

What Are Web Services?

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

A web service has special behavioral characteristics:

XML-based: By using XML as the data representation layer for all web services protocols and technologies that are created, these technologies can be interoperable at their core level. As a data transport, XML eliminates any networking, operating system, or platform binding that a protocol has.
Loosely coupled: A consumer of a web service is not tied to that web service directly; the web service interface can change over time without compromising the client's ability to interact with the service. A tightly coupled system implies that the client and server logic are closely tied to one another, implying that if one interface changes, the other must also be updated. Adopting a loosely coupled architecture tends to make software systems more manageable and allows simpler integration between different systems.
Coarse-grained: Object-oriented technologies such as Java expose their services through individual methods. An individual method is too fine an operation to provide any useful capability at a corporate level. Building a Java program from scratch requires the creation of several fine-grained methods that are then composed into a coarse-grained service that is consumed by either a client or another service. Businesses and the interfaces that they expose should be coarse-grained. Web services technology provides a natural way of defining coarse-grained services that access the right amount of business logic.

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

Web Services Adoption Factors

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

Web services are new technologies and require a paradigm shift. The adoption of web services is directly impacted by the adoption of the paradigm of web services development.

A paradigm shift can happen quickly in a large wave, when suddenly the whole world is doing something differently, and no one notices how and when it happened until after the fact. An example of such a shift is the World Wide Web phenomenon that began around 1995. The combination of HTML, HTTP, and the CGI programming model is not the most efficient way to accomplish the services offered by these technologies, yet the CGI model gained widespread grassroots acceptance because it was simple and easy to adopt.

The acceptance of CGI started the wave. To become a lasting paradigm shift, the model of web-based business needed broader acceptance among corporate IT and industry leaders. This acceptance was encouraged by continuing standards development within W3C and IETF and through continuing technology innovations such as ISAPI, NSAPI, Java Servlets, and application servers. Eventually, high-level architectures and infrastructures such as .NET and J2EE were created to hold everything together.

Unlike the initial adoption of the Web, which was driven by grass-roots demand, the adoption of web services will be driven downward by corporations. It's still a paradigm shift, but it's likely to move more slowly. The adoption of the fax machine provides a good analogy. Because fax machines were initially large expensive devices, they were adopted first by large businesses as a way to communicate between their offices. As more companies bought fax machines, they became important for business-to-business communications. Today, fax machines are nearly ubiquitous—you can fax in your pizza order. We expect to see the same trend in web services. They will be used first for internal business communications before they become part of everyday life. In all cases, though—the rapid adoption of the Web, the slower adoption of the fax machine, and the current adoption of web services—the same factor has enabled the paradigm shift. That factor is a standards communications mechanism. Whether the standard be the phone line and FAX protocols, the TCP/IP stack and HTTP (together with the phone line and modem protocols), or the web service protocols, standards have been, and continue to be, the key factor in enabling the acceptance of new technologies.

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

Web Services in a J2EE Environment

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

A common thread found throughout various web services specifications is the regular reference to web services "platforms" and "providers." A web services platform is an environment used to host one or more web services. It includes one or more SOAP servers, zero or more UDDI business registries, the security and transaction services used by the web services hosted on it, and other infrastructure provisions. A web services provider is generally considered a vendor-supplied piece of middleware infrastructure, such as an ORB, an application server, or a MOM. The provider may fully supply a platform, or it may deliver some base J2EE functionality plus some web service add-ons.

Web services are a new approach for exposing and advertising enterprise services that are hosted on a platform. These platform services still have a variety of enterprise requirements, such as security, transactions, pooling, clustering, and batch processing. Web services do not provide these infrastructure capabilities, but expose the services that do. J2EE and .NET still play an important role in the enterprise as platform definitions: they define the behavior of core capabilities that every software program needs internally. Web services, however, offer a standard way to expose the services deployed onto a platform.

An important question is, "What is being web service enabled?" If the answer is the business systems that run the enterprise, then the role of J2EE in the whole web services picture becomes abundantly clear. The core requirements of a web service enabled ecosystem are the same as they have always been—scalability, reliability, security, etc. Web services provide new ways of wrapping things at the edge of the enterprise, but if you poke your head through the web services hype, the requirements for holding together your core systems don't change that much. The implemention of the web services backbone should still be based on the J2EE architecture. Web services and J2EE come together at multiple points. The use of each J2EE component depends on the application's requirements, just as it did prior to the advent of web services. If the nature of the web service is for lightweight, quick-and-dirty processing, then use a web container and implement the web service directly as a JSP. If the solution requires a distributed component model, then use EJB. If the solution requires a highly distributed, highly reliable, loosely coupled environment, then use JMS. Naturally, any of these combinations is allowed and encouraged, as illustrated in Figure 1-4.

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

What This Book Discusses

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

This is a book on Java and web services. It is for developers who need to develop client- or server-side programs that either use web services or are exposed as web services. Web services are built on XML and have specifications that focus on the XML nature of the technology. These specifications do not discuss how these technologies might be bound to a particular programming language such as Java. As a result, a plethora of industry technologies that facilitate Java/web service integration have been proposed.

This book introduces the basics of SOAP, WSDL, and UDDI, and then discusses some of the different Java technologies available for using each of these platforms within a Java program. The technologies we've chosen range from open source initiatives, such as the Apache project, to big-ticket commercial packages. One reason for touching on so many different packages is that the web services story is still developing; a number of important standards are still in flux, and vendors are providing their own solutions to these problems. Of course, this book looks at the standards efforts designed to consolidate and standardize how Java programs interface with web services. Most notably, this book discusses Java/XML technologies, such as JAXR, JAX-RPC, and JAXM, and how they can be used in a web services environment.

These standards are still works in progress; their status may be clarified by the time we write a second edition. In the meantime, we thought it was important (and even critical) to show you how things look. Just be aware that changes are certain between now and the time when these standards are finalized and actual products are released.

Additionally, for developers who are producing J2EE applications, this book discusses different technologies that are being proposed to web service-enable standard J2EE applications. This book discusses how a web service facade can integrate with a J2EE infrastructure. It also introduces some of the standards efforts proposed for solidifying this work.

This book also discusses the points that developers need to understand to make their web services secure and interoperable with other web services. It provides an in-depth look at web service interoperability across multiple platforms, including the topic of .NET.

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

Chapter 2: Inside the Composite Computing Model

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

What is the "composite computing model," you ask? The most straightforward definition we've found is:

An architecture that uses a distributed, discovery-based execution environment to expose and manage a collection of service-oriented software assets.

A software asset is nothing more than a piece of business logic; it can be a component, a queue, or a single method that performs a useful function that you decide to expose to the outside world. Like the client-server and n-tier computing models, the composite computing model represents the architectural principles for governing roles and responsibilities of its constituents. It was designed to solve a specialized group of business problems that have the following requirements:

Dynamic discovery of the business logic's capabilities
Separation between the description of the business logic's capabilities and its implementation
The ability to quickly assemble impromptu computing communities with minimal coordinated planning efforts, installation procedures, or human intervention

The computing industry has been moving towards this model for some time now; much of the last decade has been devoted to defining and refining distributed-computing technologies that allow you to look up components on the fly; discovering a component's interface at runtime; and building applications from components on an ad-hoc basis, often using components in ways that weren't anticipated when they were developed. Listing the steps by which we arrived at the composite computing model is a tangent we won't follow, but remember that Java has played, and continues to play, a very important role in the development of distributed technologies.

In short, the "composite computing model" is the direction in which computing has headed ever since networking became cheap and easy. Instead of trying to build larger applications on ever larger computers, we're trying to assemble smaller components that interact with one another across many computers, and possibly thousands of miles. Instead of building a large, monolithic, proprietary inventory system, for example, we're trying to build services that access inventory databases and can easily be combined as needed. Instead of forcing a customer to call customer service to find out if your plant can deliver 10,000 widgets by Wednesday (and if another plant can deliver 15,000 gadgets by Thursday), you can run an application that knows how to search for vendors that supply widgets and gadgets, figures out how to query each vendor's service interface, and says, "Yes, we can do a production run of 5,000 next week at a cost of $40,000." If you're not working on applications that do this now, you will be soon.

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

Service-Oriented Architecture

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

The composite computing model defines a vision for what computing should be. Service-oriented architecture (SOA) represents a way to achieve this vision using the set of technologies that make up the Web Services Technology Stack. This set of technologies currently consists of SOAP, WSDL, and UDDI, though other components may be added in the future.

Like other concepts associated with web services, the SOA seemed to appear almost out of nowhere in September 2000. The originator was IBM and the introduction mechanism was an article by the IBM Web Services Architecture team on the developerWorks web site (http://www.ibm.com/developerWorks). Since then, this group has used it as a way to extol the virtues of web services to nontechnical users. The SOA is an instance of a composite computing model, and thus something that can be used to further our understanding of it.

Conceptually, the SOA model is comprised of three roles performing three fundamental interactions. The components of the SOA are our good friends, web services. Each web service is made up of two parts:

Service: The implementation for a web service. A service can be as minuscule as a JavaScript file or as elaborate as a 30-year-old, industrial-strength COBOL application running on a mainframe. The key requirement is that it be on a network-accessible platform, provided by the web service provider.
Service description: The interface for a web service. It is expressed in XML and is governed by one or more standards. This description includes the datatypes, operations, protocol bindings and network location (i.e., the URL, etc.) for the web service's implementation. Additional documents provide categorization and other metadata to facilitate discovery.

The SOA is based upon the interactions between three roles: a provider, a registry (or broker), and a requestor. These roles are illustrated in Figure 2-1. The interactions between these roles involve publishing information about a service, finding which services are available, and binding to those services.

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

The P2P Model

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

The SOA provides a powerful framework for building next-generation applications. However, for some enterprises, the centralized hub-and-spoke structure of the SOA is too inflexible. Some enterprises want to build web service solutions that require real-time views of work in progress, inventories, logistics, etc. Other businesses want to exploit highly successful peer-to-peer (P2P) applications, such as instant messaging and content distribution.

The P2P approach differs from the SOA in that no attempt is made to define explicit roles. Any node, or peer, can operate in any role it knows about or can discover through other peers on the P2P network. We often think that this "be whatever you can discover" capability makes the P2P model more suitable for doing web services than the SOA.

Despite its legal problems, looking at an application such as Napster (or its close relative, Gnutella) from a web services perspective is useful. Users publish the files they are willing to share and these files are listed in a registry. (Napster had a centralized database that served as a registry and Gnutella has a distributed searching mechanism, which is essentially a virtual registry.) Other users can search the registry (physical or virtual) and download files directly from the provider. This process maps nicely onto the SOA, except that there's no clear distinction between provider and requestor or even (in the case of Gnutella) requestor and directory. Peers establish ad hoc, short-term relationships with one another; at any time, a peer can be provider, requestor, or both.

Advocates of P2P computing have often failed to come up with a business model that works in such a decentralized environment. However, that shouldn't prevent us from looking at the technical advantages of the peer-to-peer model and seeing how it might apply to web services. Here are some compelling reasons for considering the P2P approach:

More efficient use of network bandwidth The concentrated, localized traffic congestion typical of today's Web doesn't apply to P2P networking. There is no server as such; interactions are between individual peers, with no centralized bottlenecks. If that peer experiences a hardware failure, another peer can handle the request. If a peer is too busy, it will be slow in replying to a request, and another peer will handle it.

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

Chapter 3: SOAP: The Cornerstone of Interoperability

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

Much like web services, the broad definition of the Simple Object Access Protocol (SOAP) means various things to different people. It's a wire protocol. It's an RPC mechanism. It's an interoperability standard. It's a document exchange protocol. It's a universal business-to-business communications language. It's everything you would ever need. It's not nearly enough.

Actually, it's all of the above. Perhaps the best way to understand what it is and what it isn't is to break down the acronym into its parts and analyze where each one fits.

For starters, the "S" in SOAP stands for "simple." The basic approach of expressing data as XML and transporting it across the Internet using HTTP is simple. In the SOAP protocol, everything that goes across the wire is expressed in terms of HTTP or SMTP headers, MIME encoding, and a special XML grammar for encoding application data and objects.

However, a full understanding of the details and rules of SOAP is not for the faint of heart. For instance, the idea of expressing a SOAP document with attachments using the email and MIME metaphor is simple. Is MIME simple? It is simple only because it uses a data formatting convention that is already in widespread use, is familiar to most IT people, and is conceptually understood by less technical people. Perhaps the "S" should stand for "simpler."

Is XML simple? It can be as simple or as complex as you want it to be. XML provides a way to add semantic meaning to data shipped over the wire. Through XML-Schema, we have a way of describing a complex document such as a purchase order. But XML-Schema is far from simple. SOAP provides conventions for creating "envelopes" for your data. SOAP has explicit rules for encoding application data—even for such things as arrays of binary data—so it can be expressed in an ASCII human-readable form. It isn't all that simple, but it is explainable.

We don't mean to scare anybody off by representing SOAP as overly complex; we will walk you through it and explain it in detail. The good news is that tools and frameworks are already coming to the rescue. In the end, most of us will not worry about how a purchase order gets encoded or how it is sent over the wire. We will all code to a PO object and click on a "Save" button. However, for those of you who consider the best tool of trade to be vi, emacs, or Notepad, we must press on. Even those who like to take advantage of productivity tools and infrastructure need to understand what lies beneath.

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

Simple

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

Perhaps the "S" should stand for "straightforward." In SOAP, nothing is hidden intentionally. Every aspect of a SOAP request is intended to be completely self-describing and largely based on a conglomeration of proven, well-established conventions. That's the real beauty behind SOAP; the platforms and programming languages on both sides of a SOAP conversation are independent of one another, yet they can communicate as long as each side of the conversation can:

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

Object

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

The "O" in SOAP stands for "object" and has to do with its roots as a way of invoking COM objects across the Internet. As with its close cousin XML-RPC, SOAP is fully capable of describing a remote procedure call or method invocation. Here's a typical SOAP document that describes a method invocation on a remote object:

POST /StockQuote HTTP/1.1
Host: www.example.org
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "http://example.org/2001/06/quotes"

<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope" >
 <env:Body>
  <m:GetLastTradePrice
        env:encodingStyle="http://www.w3.org/2001/09/soap-encoding"
        xmlns:m="http://example.org/2001/06/quotes">
    <symbol>DIS</symbol>
 </m:GetLastTradePrice>
 </env:Body>
</env:Envelope>

Section 3.5 discusses the details of this SOAP request. For now, it should suffice to say that the two most important parts are the method name, GetLastTradePrice, and its parameter, the ticker symbol DIS.

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

Access

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

A key feature of SOAP and web services is their accessibility. The initial developers of SOAP intended for all SOAP conversations to be carried out via a "binding" to another lower-level protocol, and that binding would most likely be HTTP or SMTP. These protocols were chosen because they are almost universally available. Most firewalls have been trained to allow HTTP sessions and SMTP exchanges, so SOAP conversations can easily cross corporate boundaries.

It's possible to create a SOAP binding for almost any protocol—however, for the time being, HTTP is the de facto binding (and most widely used). Other bindings, such as SOAP over RMI, or SOAP over JMS (for improved reliability), are emerging.

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

Protocol

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

Put all these factors together and we have a protocol. SOAP is an XML based protocol used to exchange information throughout a distributed environment.

SOAP has its roots in synchronous remote procedure calls over HTTP—although you wouldn't know it by reading the specification these days. In fact, the specification seems to go out of its way to distance itself from that association. Although special provisions are available for performing synchronous RPC calls in SOAP, there is also an asynchronous, message-based document exchange model. Actually, the document exchange model is the default method of exchanging data between two endpoints. An RPC call is a specialized case of combining multiple one-way asynchronous messages into a request-response.

The introduction to Section 2 of the SOAP 1.2 specification says it well:

SOAP messages are fundamentally one-way transmissions from a SOAP sender to a SOAP receiver; however, SOAP messages are often combined to implement patterns such as request/response.
SOAP implementations can be optimized to exploit the unique characteristics of particular network systems. For example, the HTTP binding ... provides for SOAP response messages to be delivered as HTTP responses, using the same connection as the inbound request.

Because SOAP can represent some fairly complex data structures in both the request and response messages, the lines between the two models are blurred. This chapter presents the information that is germane to either model first. The RPC-specific concepts built on the more generic concepts are explained at the end. We use Apache SOAP 2.2 for our examples, which follows a similar design.

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

Anatomy of a SOAP Message

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

The SOAP specification describes four major components: formatting conventions for encapsulating data and routing directions in the form of an envelope, a transport or protocol binding, encoding rules, and an RPC mechanism. The envelope defines a convention for describing the contents of a message, which in turn has implications on how it gets processed. A protocol binding provides a generic mechanism for sending a SOAP envelope via a lower-level protocol such as HTTP. Encoding rules provide a convention for mapping various application datatypes into an XML tag-based representation. Finally, the RPC mechanism provides a way to represent remote procedure calls and their return values. Throughout this book, we'll refer to these four areas collectively as a SOAP message .

We start this discussion by focusing on the document exchange model. To clarify this topic, we use a simple purchase order document, PO.xml . This document is overly simplified because it contains only two things—a ship-to address and an item entry:

<?xml version="1.0" encoding="UTF-8"?>
<PurchaseOrder xmlns="urn:oreilly-jaws-samples">
    <shipTo country="US">
        <name>Joe Smith</name>
        <street>14 Oak Park</street>
        <city>Bedford</city>
        <state>MA</state>
        <zip>01730</zip>
    </shipTo>
    <items>
        <item partNum="872-AA">
            <productName>Candy Canes</productName>
            <quantity>444</quantity>
            <price>1.68</price>
            <comment>I want candy!</comment>
        </item>
    </items>
</PurchaseOrder>

PO.xml is not yet a SOAP document; it's just a vanilla XML document. What makes it become a SOAP document is:

The wrapping of the XML inside of a SOAP body
The wrapping of the SOAP body within a SOAP envelope
The optional inclusion of a SOAP header block
Namespace declarations
Encoding style directives for the serialization of data
The binding of the whole thing to a protocol

As illustrated in Figure 3-1, a SOAP envelope contains two primary components: a header and a body. Both the header and the body can contain multiple blocks of information.

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

Sending and Receiving SOAP Messages

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

We have seen the building blocks of a SOAP message. The next steps are to understand how a message is built and how it is then communicated between two endpoints. To discuss these topics, we present a simple SOAP sender and a SOAP receiver using Apache SOAP and the Apache Tomcat servlet engine. You may find it refreshing to discover that the additional pieces are not placed in the SOAP document by hand. The SOAP-ification is accomplished by using APIs that take care of the dirty work.

Before we look at the code of our first SOAP example, let's run it and observe its behavior. This example consists of a simple HTTP sender class that reads an XML file, wraps it in a SOAP envelope, and sends it to a URL destination. The destination is a simple HTTP servlet that takes the contents of the message and dumps it to the screen. As we progress through concepts such as dynamic headers, SOAP with Attachments, and SOAP-RPC, these examples will become progressively more sophisticated. For now, lets run the simple one. From the command line, run the command:

java SimpleGenericHTTPSoapClient -df ./PO.xml

If this command doesn't work, make sure that SimpleGenericHTTPSoapClient.class is on the classpath and PO.xml is in the current directory.

You should see the following output:

_________________________________________________________
Starting SimpleGenericHTTPSoapClient:
    host url        = http://localhost:8080/examples/servlet/SimpleHTTPReceive
    data file       = ./PO.xml
_________________________________________________________

Sent SOAP Message with Apache HTTP SOAP Client.
Waiting for response....
HTTP POST was successful.

In the command shell running the Tomcat servlet engine, you should see:

Received request.
-----------------------
  SOAPAction = "urn:oreilly-jaws-samples"
  Host = localhost
  Content-Type = text/xml; charset=utf-8
  Content-Length = 695
-----------------------
<?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>
<PurchaseOrder xmlns="urn:oreilly-jaws-samples">
        <shipTo country="US">
                <name>Joe Smith</name>
                <street>14 Oak Park</street>
                <city>Bedford</city>
                <state>MA</state>
                <zip>01730</zip>
        </shipTo>
        <items>
                <item partNum="872-AA">
                        <productName>Candy Canes</productName>
                        <quantity>444</quantity>
                        <price>1.68</price>
                        <comment>I want candy!</comment>
                </item>
        </items>
</PurchaseOrder>
</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!

The Apache SOAP Routing Service

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

Before moving on to the rest of the examples, we need to make a quick note about Apache SOAP's routing and service capability. It's a concept that is likely to be applicable to other SOAP infrastructures you may use in the future. If you have poked around with Apache (or you looked ahead at the rest of the chapter), you may have noticed that many samples use a common URL, which either looks like http://localhost:8080/soap/servlet/messagerouter or http://localhost:8080/soap/servlet/rpcrouter. These special URLs point to Apache's routing and dispatching mechanism. This mechanism looks at the content of the SOAP envelope and decides which class to load and which method to call within that class. Apache refers to this destination as a service . The service is registered with the servlet engine in a two-step process. First, an XML deployment descriptor is created, specifying details about the class name of the service, its associated method call, and the target URI. Then a special org.apache.soap.server.ServiceManagerClient class is invoked to register the service with Apache SOAP.

Using the RPC router, any Java class and method can be registered as a service; the Apache SOAP infrastructure will call the method with the appropriate parameters. An example of SOAP-RPC can be found in Chapter 4. Using the message router, the method name is the tag name of the body entry in the SOAP envelope, and the method always conforms to the following signature:

public void anyMessageMethod(Envelope requestEnvelope, 
   SOAPContext requestContext, SOAPContext responseContext)

for which anyMessageMethod is specified in the deployment descriptor for the service and is also the tag name of the body entry in the SOAP envelope.

Sending SOAP messages to the SimpleHTTPReceive servlet is an excellent way of dumping raw output to the screen. A more convenient way to see the raw output from the sender and the receiver is to use the TunnelGui included with Apache SOAP. TunnelGui is a simple utility that intercepts the HTTP request, displays it in a window on the screen, and forwards the request to the ultimate destination. It's a great tool for analyzing and debugging problems that have to do with unexpected output. To launch the Apache TunnelGui utility, issue the following command:

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

SOAP with Attachments

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

While XML and SOAP are very good at describing data, many kinds of application data aren't well-suited for XML—for example, a piece of binary data such as an image, or a CAD file that contains schematic diagrams of parts being ordered electronically. SOAP with Attachments (SwA) was born in recognition of this limitation. SwA combines the SOAP protocol with the MIME format to allow any arbitrary data to be included as part of a SOAP message. The model is exactly the same as the model used for including email attachments.

The MIME protocol allows multiple arbitrary blocks of data to be strung together in a message, with each block separated by a MIME header. The MIME headers delineate where each part begins and the previous part ends. The next example shows what a MIME header looks like. In SwA, the entire message consists of multiple MIME parts; the first part (part 0) is the SOAP envelope, and the remaining parts (1 through n) are the attachments. All parts are wrapped by the underlying protocol, as illustrated by Figure 3-3.

Figure 3-3: The structure of a SOAP with Attachments message

To construct and deconstruct SwA messages, use the Apache SOAP and JavaMail APIs. Before running the example, note that the example archive contains a text file called attachment.txt. It is a simple text file that contains the string "This is an attachment." There is also a file called poWithAttachment.xml that is identical to PO.xml, except that the root level tag is <PurchaseOrderWithAttachment>. The other modification we have made is the addition of an element with the name of attachment. This element contains an href attribute:

<attachment href="cid:the-attachment"/>

This element helps identify the attachment when processing the document. Now run the example from the command line:

java GenericHTTPSWAClient -df ./poWithAttachment.xml -at attachment.txt

In addition to the purchase order, you should see the following output in the Tomcat console window:

Content-ID = the-attachment
The attachment is...
This is an attachment.

Let's see the raw output from our client by redirecting it at 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!

Chapter 4: SOAP-RPC, SOAP-Faults, and Misunderstandings

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

SOAP-RPC defines a model for representing an RPC and an RPC response using the SOAP infrastructure. It is not necessarily bound tightly to a synchronous request/reply model, or to the HTTP protocol. In fact, both the SOAP 1.1 and 1.2 specifications explicitly state that the use of SOAP-RPC is orthogonal to the protocol binding. The specifications do concede that when SOAP-RPC is bound to HTTP, an RPC invocation maps naturally to an HTTP request, and an RPC return maps naturally to an HTTP response, but this natural mapping is purely coincidental. One of the goals of the SOAP 1.2 effort was to distance itself from the point of view that SOAP is inherently an RPC mechanism. As a result, SOAP-RPC was moved into the optional "Adjuncts" portion of the specification.

That said, what's really important is that SOAP defines a uniform model for representing an RPC and its return value or values. The fundamental requirements for an RPC call are that the body element contains the method name and the parameters and that the parameters are accessible via accessors. In addition, SOAP has provisions for encoding the method signature, header data, and the URI that represents the destination.

In the next example, we'll look at a SOAP-RPC client that calls a remote service that returns the value of a book at Barnes & Noble. The service is hosted and available at http://www.xmethods.net. Let's start by running the client and examining its output:

java GetBookPrice

The default settings look up the price of O'Reilly's Java Message Service, using its ISBN number.

You should see the following output:

_________________________________________________________
Starting GetBookPrice:
    service url     = http://services.xmethods.com:80/soap/servlet/rpcrouter
    ISBN#       = 0596000685
_________________________________________________________

The price for O'Reilly's The Java Message Service book is 34.95

Congratulations! You have just executed a SOAP-RPC invocation over the Internet and received a response with a return value. Let's examine the SOAP messages that just went over the wire and the code that made it happen. To see what the SOAP looks like, we can reroute the transaction to our

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

SOAP-RPC

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

java GetBookPrice

The default settings look up the price of O'Reilly's Java Message Service, using its ISBN number.

You should see the following output:

_________________________________________________________
Starting GetBookPrice:
    service url     = http://services.xmethods.com:80/soap/servlet/rpcrouter
    ISBN#       = 0596000685
_________________________________________________________

The price for O'Reilly's The Java Message Service book is 34.95

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

Error Handling with SOAP Faults

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

SOAP errors are handled using a specialized envelope known as a Fault Envelope. If an error occurs while the server processes a SOAP message, it constructs a SOAP Fault and sends it back to the client. Here's a typical SOAP 1.1 Fault:

<?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>
    <SOAP-ENV:Fault>
        <faultcode>SOAP-ENV:Server</faultcode>
         <faultstring>Test Fault</faultstring>
         <faultactor>/soap/servlet/rpcrouter</faultactor>
         <detail>
            <stackTrace>[SOAPException: faultCode=SOAP-ENV:Server; msg=Test Fault]
            at StockQuantity.getQty(StockQuantity.java:21)
            at java.lang.reflect.Method.invoke(Native Method)
            at org.apache.soap.server.RPCRouter.invoke(RPCRouter.java:146)
            ...
            at org.apache.tomcat.util.ThreadPool$ControlRunnable.run(
                ThreadPool.java:501)
            at java.lang.Thread.run(Thread.java:498)
         </stackTrace>
         </detail>
     </SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

A SOAP Fault is a special element that must appear as an immediate child of the SOAP body element. The <faultcode> and <faultstring> elements are required. The <faultactor> and <detail> elements are optional. Table 4-1 lists the possible values for the faultcodes and their meanings.

Table 4-1: SOAP faultcodes
Faultcode	Meaning
`VersionMismatch`	The SOAP node processing the request encountered a version mismatch. The namespace identifier of the SOAP envelope determines version compatibility.
`MustUnderstand`

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

SOAP Intermediaries and Actors

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

The world of interapplication communication usually involves more than two parties talking with one another in a point-to-point fashion. A SOAP envelope that represents a business transaction may move from place to place as it goes through the various stages of a business process. Each stage in a multihop process may act upon the envelope, modify its contents, and route it along to the next step in a process.

Recognizing that messages may take many hops as they travel from the sender to their final destination, SOAP defines a Message Exchange Model. As illustrated in Figure 4-2, this model defines terminology and roles such as SOAP Node, Intermediary, Actor, the initial SOAP sender, and the ultimate receiver. A node is any object or process performing any of these roles. An intermediary is any node that sits between the initial SOAP sender and the ultimate receiver. An actor is any node that receives a SOAP envelope for processing and can be either an intermediary or the ultimate receiver.

Figure 4-2: Multihop processing terminology

The actor attribute may be used to specify which blocks of information are intended for each step in the process. Each node in a multihop process is responsible for digesting and interpreting the meaning of the actor attribute for each SOAP block and possibly re-inserting it into the SOAP block and forwarding it on to the next node for processing. Any SOAP receiver that encounters a header block without an actor attribute, or an actor attribute equivalent to the special URI http://www.w3.org/2001/09/soap-envelope/actor/next, has to interpret that header block as being intended for it (the current SOAP node). If the current SOAP node cannot fulfill the mustUnderstand requirements, it must generate a SOAP Fault.

An actor attribute with the special value of http://www.w3.org/2001/09/soap-envelope/actor/none indicates that this header is not targeted at anything in particular. This indication is useful for sharing header information across multiple nodes.

There's a lot of confusion about URIs, URNs, and URLs, which are seemingly similar concepts used throughout web services and are gradually infiltrating Internet programming in general. In 2001, the W3C published a document that attempts to clarify these three commonly misused acronyms. The full document can be found at

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

Chapter 5: Web Services Description Language

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

In the previous two chapters, we talked extensively about SOAP and the structure it delivers to web services. Not surprisingly, the adoption of SOAP's messaging formats brought about a need to describe operational information in an equally structured way. WSDL was introduced to address this need.

WSDL is an XML grammar for describing a web service as a collection of access endpoints capable of exchanging messages in a procedure- or document-oriented fashion. A WSDL document is a recipe used to automate the details involved in application-to-application communication.

On one level, WSDL is not that different from CORBA IDL or Microsoft IDL. They are all used to define the interfaces (method signatures) and datatypes for a discreet piece of programming logic.

On another level, WSDL is an altogether different beast, offering a degree of extensibility that has no parallel in the IDL specification. This extensibility allows WSDL to be used to:

Describe endpoints and their messages, regardless of the message format or network protocol used to exchange them.
Treat messages as abstract descriptions of the data being exchanged.
Treat port types as abstract collections of a web services' operations. A port type can then be mapped to a concrete protocol and data format.

If you are feeling a bit dazed after reading these bullet items, it's just the WSDL specification talking! We'll offer fewer "scientific" definitions as we go along; don't let the terms scare you away from this technology.

As the number of communication formats and protocols used on the Internet continues to increase, finding a standard way of describing how two machines should communicate with one another has become increasingly important. WSDL describes what a service does, how to invoke its operations, and where to find it. WSDL has created separate definitions and terminology for defining a web service, the communication endpoint where that web service exists, the legal format for input and output messages for the web service, and an abstract way to declare a binding to a concrete protocol and data format.

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

Introduction to WSDL

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

Everything defined within a WSDL file is abstract: it's just the definition of parameters and constraints for how communication should occur at runtime. The web service implementation has to adhere to the guidelines defined in the WSDL file but has some flexibility over specifics. WSDL also provides the ability to define a binding that attaches an abstract set of message definitions to a concrete protocol or data format. A binding extension is a type of binding defined for a major protocol. WSDL defines out-of-the-box binding extensions for SOAP 1.1, HTTP GET, HTTP POST, and MIME.

Since WSDL is just an abstract description of a web service's interface, it is conceivable that implementation code can be generated from a WSDL definition and that WSDL definitions can be created automatically from existing implementation code. From a programming perspective, using WSDL to generate code is one of its biggest values. Methods of generating WSDL from existing components have also been discovered. Both techniques are a boon to developers and nondevelopers alike and lend credibility to the notion of truly dynamic computing models.

The question that developers have to ask, however, is what they are going to build first. Will you build the service implementation first and then generate the interfaces automatically? Will you create the WSDL for a web service and then use a tool to create the matching J2EE base components necessary to implement the web service?

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

Anatomy of a WSDL Document

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

Let's take a detailed look at the individual parts of a WSDL document. The following code shows the major elements that may appear in a WSDL document. An asterisk (*) next to an element indicates that more than one of these elements may appear. Elements from WSDL binding extensions (i.e., SOAP, HTTP, etc.) were not included here, to keep things simpler:

<definitions>
    <import>*
    <types>
        <schema></schema>*
    </types>
    <message>*
        <part></part>*
    </message>
    <PortType>*
        <operation>*
            <input></input>
            <output></output>
            <fault></fault>*
        </operation>
    </PortType>
    <binding>*
        <operation>*
            <input></input>
            <output></output>
        </operation>
    </binding>
    <service>*
        <port></port>*
    </service>
</definitions>

In the next few sections, we define each of the major WSDL elements and present a real-life example as part of the explanation. Finding a WSDL file sophisticated enough to cover the various facets of the specification while still remaining readable was not simple. The following sections present the WSDL document that defines a web service for the translation of the Z39.50 ASN.1 specification. Z39.50/XER (XML Encoding Rules) allows information described in ASN.1 to be carried in XML. It describes the datatypes and operations that one would need to perform real-time conversions between ASN.1-encoded data structures and XML-encoded data structures.

The ez3950-PortTypes.wsdl file in the examples directory contains the WSDL for this example. This file also depends upon ez3950.xsd, which is in the same directory.

The <definitions> element in a WSDL document acts as a container for the service description. It provides a place to do global declarations of namespaces that are intended to be visible throughout the rest of the document. Here is the <definitions> element from the XML Encoding Rules. Note that some of the namespaces defined in this element have prefixes (xsd, soap, soapenc, xer, etc.), and some do not. These prefixes are bound to a particular namespace but do not govern which schemas are actually available to a schema processor:

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

Best Practices, Makes Perfect

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

One of the biggest mistakes that many developers make when working with WSDL is defining operations and messages that are too fine-grained. By doing so, developers usually define more than they really need. You need to ensure that your web service is coarse-grained and that the messages being defined are more business oriented than programmatic. You shouldn't define a web service operation for every Java method you want to expose. Rather, you should define an operation for each action you need to expose. Deciding what to expose in your web service requires a methodological rather than a technical mindset.

The natural tendency for a developer is to treat a WSDL document like code because it describes the operations and types for the web service. It's not code, though—it's metadata about code. Take care not to include anything that a service requestor doesn't need to know to invoke the web service.

For maximum interoperability and platform neutrality, use XML Schema as your type system whenever possible. If your WSDL is publicly visible, imagine that it is part of a workflow that you do not get to define. It is entirely feasible that the web service your WSDL describes is upstream or downstream of other actions and that a tool uses the WSDL document to instrument it. Realize that your service hasn't necessarily succeeded when the particular application you're developing works; the real test of a successful web service is when other applications that you didn't anticipate use your service.

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