5.0 Introduction
This chapter examines how to build Java clients that can talk to SOAP-based web services using the SOAP with Attachments API for Java (SAAJ) API.
SOAP, standardized by the W3C in 2000, is a platform-agnostic way of creating and sending messages in a distributed system.
You may be familiar with SOAP as an acronym for Simple Object Access Protocol, but version 1.2 of the spec, published in 2003, throws out the explanation of the acronym with the direct, clear, and yet mysterious statement that “This is no longer the case.” Perhaps they decided it wasn’t so simple after all….
Because SOAP is based on XML, it is relatively easy for humans to read and understand, and the structure of a SOAP message itself is simple. SOAP messages are always wrap-ped in a container called the envelope; the envelope always contains a body, which carries the payload of the message in one or more XML documents. Optionally, your envelope can include headers, very similar to HTTP headers. If something goes wrong during processing, a SOAP fault will be added as the body content. The structure of a SOAP 1.1 envelope is depicted in Figure 5-1. The * in the figure denotes that there can be multiple instances of that type.
Developers on either end of the web service can extract the content of the SOAP enve-lope using XML tools for processing.
SAAJ 1.3 creates messages that adhere to both the SOAP 1.1 and SOAP 1.2 specifications. Which version of SOAP you use will depend on your vendor. I have tried to make distinctions between these versions where they matter. The namespace for SOAP 1.1 (the default for most tools still as of this writing) is http://schemas.xmlsoap.org/soap/envelope/. The namespace for SOAP 1.2 is http://www.w3.org/2003/05/soap-envelope.
SOAP messages typically travel over HTTP (though sometimes JMS and other mech-anisms can be used). Corporate firewalls generally allow exchange of HTTP traffic already, and have sophisticated mechanisms, including firewall rules, subnets, and so forth, in place to deal with that traffic. Because SOAP reuses the HTTP transport layer, adopting SOAP as a standard for web services was convenient, contributing to SOAP’s early popularity. Moreover, developers found it easy to use SOAP because XML was already familiar to them, and many platforms have native XML tools. Quickly, SOAP became a popular way of doing web services.
SOAP-ENV:Envelope SOAP-ENV:Header
SOAP-ENV:Body
SOAP-ENV:faultCode SOAP-ENV:faultString SOAP-ENV:faultActor SOAP-ENV:Fault*
SOAP-ENV:Detail Body Entry*
DetailEntry*
SOAP-ENV:encodingStyle SOAP-ENV:mustUnderstand SOAP-ENV:actor
Header Entry*
Figure 5-1. Structure of a SOAP envelope
The SOAP with Attachments API for Java (SAAJ) was created to specifically address the needs of burgeoning SOAP-based web services developers. It allows you to pro-grammatically manipulate SOAP envelopes. Using its classes and methods, you can create an envelope, add a header to the envelope, put data in the header, create a SOAP body, add an XML document to the SOAP body, and add the body to the envelope.
Once your message is complete, you can ship the complete SOAP message off over HTTP to invoke a web service using a dispatcher. SAAJ 1.3, which we examine in this chapter, is the foundational API for working with web services in Java. Every Java EE vendor provides a SAAJ implementation.
There is a charter at the W3 for SOAP-JMS. This work is in the early stages as of this writing, but the idea is to ensure standardize the binding mechanism to interoperability between implementations created by web services vendors for SOAP over JMS. You can read more about it at http://www.w3.org/2007/08/soap-jms-charter.html.
It should be noted, however, that in recent years SAAJ has been superseded by JAX-WS (Java API for XML Web Services). SAAJ operates at the plumbing level, requiring you to build every aspect of your SOAP envelopes by hand. The code can get long and somewhat tedious, and requires in-depth knowledge of the internal structure of the requests and responses you must work with when invoking web services. JAX-WS reuses SAAJ and acts as a layer of abstraction above it. Think of SAAJ as the XML view and JAX-WS as the object view of a message exchange.
Here’s an example of a SOAP envelope in XML with HTTP header data:
POST /StockQuote HTTP/1.1 Host: www.soacookbook.com:8080
Content-Type: text/xml; charset="utf-8"
Content-Length: n SOAPAction: ""
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<m:GetStockQuote xmlns:m="urn:com:soacookbook">
<ticker>JAVA</ticker>
</m:GetStockQuote>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Once you have used SAAJ to create a SOAP message structure, you can send requests and receive responses using a SOAPConnection object. SAAJ connections are based on the java.net.URL class, which is extendable to support any network protocol.
Like email messages, SOAP envelopes may also contain attachments of any type of document (XML, binary image, or any valid MIME type). The SAAJ API allows you to work with such attachments as well.
You can read more about SAAJ at https://saaj.dev.java.net.