SAAJ
Encyclopedia
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 specification and SOAP with Attachments note.
Developers can also use it to write SOAP
messaging applications directly instead of using JAX-RPC
or JAX-WS
.
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.
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.
XML
Extensible Markup Language is a set of rules for encoding documents in machine-readable form. It is defined in the XML 1.0 Specification produced by the W3C, and several other related specifications, all gratis open standards....
documents over the Internet
Internet
The Internet is a global system of interconnected computer networks that use the standard Internet protocol suite to serve billions of users worldwide...
from the Java
Java (programming language)
Java is a programming language originally developed by James Gosling at Sun Microsystems and released in 1995 as a core component of Sun Microsystems' Java platform. The language derives much of its syntax from C and C++ but has a simpler object model and fewer low-level facilities...
platform.
SAAJ enables developers to produce and consume messages conforming to the SOAP 1.1 specification and SOAP with Attachments note.
Developers can also use it to write SOAP
SOAP
SOAP, originally defined as Simple Object Access Protocol, is a protocol specification for exchanging structured information in the implementation of Web Services in computer networks...
messaging applications directly instead of using JAX-RPC
JAX-RPC
Java API for XML-based RPC allows a Java application to invoke a Java-based Web Service with a known description while still being consistent with its WSDL description. It can be seen as Java RMIs over Web services. JAX-RPC 2.0 was renamed JAX-WS 2.0 . JAX-RPC 1 is deprecated with Java EE 6...
or JAX-WS
JAX-WS
The Java API for XML Web Services is a Java programming language API for creating web services. It is part of the Java EE platform from Sun Microsystems. Like the other Java EE APIs, JAX-WS uses annotations, introduced in Java SE 5, to simplify the development and deployment of web service clients...
.
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 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
MIME
Multipurpose Internet Mail Extensions is an Internet standard that extends the format of email to support:* Text in character sets other than ASCII* Non-text attachments* Message bodies with multiple parts...
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 AxisApache Axis
Apache Axis is an open source, XML based Web service framework. It consists of a Java and a C++ implementation of the SOAP server, and various utilities and APIs for generating and deploying Web service applications. Using Apache Axis, developers can create interoperable, distributed computing...
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.