Manage Learn to apply best practices and optimize your operations.

SOAP with Attachments API for Java (SAAJ)

In this Web services advisor, William Brogden discusses a number of toolkits for SOAP servers and clients that have been created.

 SOAP toolkits in Java

Over the years since SOAP first entered the awareness of Java programmers, roughly since 1998, a number of toolkits for SOAP servers and clients have been created. Although considerable stability in the SOAP specification has been achieved, the continuous parallel developments in general XML tools and the competing visions of various vendors have prevented any one toolkit becoming the universal choice of Java programmers.

Java has the  Java Community Process procedure sponsored by Sun which attempts to define standard APIs (called Java Specification Requests, JSRs) by agreement between industry representatives. JSRs related to SOAP include JSR-67, which has produced two related specifications. The most basic functions are covered by a specification called SOAP with Attachments API for Java (SAAJ) version 1.3, most recently updated in April 2006.

The other product of this group is the Java API for Messaging or JAXM, currently in version 1.1. JAXM builds on SAAJ by adding message transmission APIs.

Why SOAP needs attachments

As an XML-based messaging protocol, SOAP messages require considerable processing power and memory. All parts of a SOAP message must conform to XML rules for allowed characters and character sequences so binary data can not be included directly. Furthermore, SOAP implementations typically parse the entire SOAP message before deciding what to do with the contents, so large data fields could easily exceed available memory. For all these reasons it was recognized that SOAP requires some mechanism for carrying large payloads and binary data as an attachment rather than inside the SOAP message envelope.

The obvious mechanism to use is the same one used for attachments to e-mail messages, the multipart MIME approach in which a collection of message parts are identified by headers and separators. The first part is always a complete SOAP message envelope while following parts depend on the application.

The SOAP with Attachments API Version 1.3

The essential object for using SAAJ is a SOAPMessage object created by a call to the createMessage method of MessageFactory. The problem of the existence of both SOAP 1.1 and SOAP 1.2 Web services is solved by having MessageFactory implementations which let the programmer specify the style to be generated. The scope of the SAAJ standard emphasizes the API for constructing SOAP messages, but it does provide the abstract SOAPConnection class, which implementations can use for simple message transmission.

Logically enough, the essential parts of a SOAP message each have corresponding Java classes in SAAJ. The most significant feature of this toolkit is that these core classes representing various parts of SOAP message implement the appropriate org.w3c.dom interfaces. This means that the SOAP objects are compatible with the familiar XML manipulation tools in the standard Java library.

In the SAAJ toolkit, a SOAPMessage object contains a complete SOAP message. A message is either a SOAP-formatted XML document or a MIME multipart message whose first section is an XML document. The SOAP formatted XML is contained in a SOAPPart object which implements the org.w3c.dom Document interface. All SOAPMessages contain a single SOAPPart, which in turn contains a SOAPEnvelope corresponding to the root element of the document.

Inside the Envelope element, a SOAP message is required to have a Body element and may have one Header element. SAAJ provides the SOAPHeader and SOAPBody objects to enable the programmer to manipulate the content of these elements. SAAJ just provides the mechanism, actually creating the contents of the SOAPBody and SOAPHeader is up to the programmer.

A SOAPMessage object may have zero, one or many additional AttachmentPart objects with any MIME content type such as an XML document, plain text or an image. If it has zero attachments the message will be transmitted as a plain XML document. Adding one or more attachments automatically cause transmission as a collection of MIME parts. Attachments are added using the AttachmentPart class, which requires a data source, typically an InputStream, and a MIME content type. Since the Java standard library provides many ways to create an InputStream, this approach is extremely flexible.

SAAJ in Sun's Java Web Services Developer's Pack and Enterprise Edition

The J2EE version 1.4 contains the 1.2 version of SAAJ, which only handles SOAP 1.1 messages. The latest Enterprise Edition 5 contains SAAJ version 1.3. If you don't want to use the full Enterprise Edition, the latest edition of the Java Web Service Developer's Pack contains an implementation of SAAJ 1.3 with full documentation and examples. The open source Glassfish project also contains SAAJ 1.3.

Open source implementations at the Apache Software Foundation

A few years ago the Apache Software Foundation's SOAP project provided the most widely used open source SOAP implementation. More recently a major reorganization of Web service related projects merged the original Apache SOAP and the current "Axis" projects into the Apache Web Services Project. Currently there are two rather different versions of the Apache Software Project's SOAP/Web Services toolkits. The Axis project, which follows up the original Apache SOAP project, is a widely used Web services toolkit which implements SAAJ. There is also an Axis2 project, which attempts a major redesign of the Axis architecture for greater speed and flexibility while still supporting a SAAJ interface.

What next?

The SOAP/XML/Java world does not seem inclined to stand still. The W3C is working on a "SOAP Message Transmission Optimization Mechanism," which will undoubtedly require yet another version of Java toolkits such as SAAJ.


Don Box reflects on "A Brief History of SOAP"

Dave Winer's "History of SOAP"

The XML Protocol Working Group at the W3C includes SOAP 1.2 and SOAP 1.2 Attachment Feature

SOAP Message Transmission Optimization Mechanism recommendation of the W3C

A list of SOAP implementations, both open source and commercial, in various languages

A summary of XML Protocols used for messaging and remote procedure calls

SAAJ 1.3 specification in PDF form

Java Web Services Developer Pack which includes SAAJ 1.3

The main entry point for Apache Software Foundation Web Services related projects

Dig Deeper on Topics Archive

Start the conversation

Send me notifications when other members comment.

Please create a username to comment.