SOAP with Attachments API for Java

The SOAP with Attachments API for Java or SAAJ provides a standard way to send XML documents over the Internet from the Java platform.

SAAJ enables developers to produce and consume messages conforming to the SOAP 1.1 and 1.2 specifications and SOAP with Attachments note.

Developers can also use it to write SOAP messaging applications directly instead of using JAX-RPC or JAX-WS.

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 cannot 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 SOAP with Attachments API Version 1.3

The essential object for using SAAJ is a SOAP Message 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.

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. The current Axis2 project attempts a major redesign of the Axis architecture for greater speed and flexibility while still supporting a SAAJ Interface.

References

• Java Web Services in a Nutshell

External links

• Oracle's "Overview of SAAJ" (from the "The Java EE 5 Tutorial")
• SOAP with Attachments API for Java (SAAJ) Specification 1.3 (JSR 67)
• The SAAJ Standard Implementation Project