For an updated, online version of these release notes, see Release Notes.
Before you work with this release, make sure that you have installed the required software and are on a supported operating system. You can find this information in the JavaTM Web Services Developer Pack (Java WSDP) home page and Release Notes and the SAAJ home page.
This release is based on the specification for the SOAP with Attachments API for JavaTM (SAAJ) 1.2.
This release includes
This release depends on the following components:
The SAAJ RI release contents are arranged in the following structure within the Java WSDP release:
||Release documentation for the SAAJ RI|
||JAR files used by the SAAJ RI|
||WAR files for the sample programs|
||SAAJ API documentation|
SAAJ 1.2 has the following new features:
SAAJ APIs now extend Document Object Model (DOM) APIs, as follows:
DOM is already in use in many environments. Now that SAAJ trees are also DOM trees, SAAJ will integrate more easily with many applications and tools.
Some details about the formatting and encoding of a SOAP message can affect interoperability. Giving the end user control over these details, while retaining the same defaults as SAAJ 1.1, allows SAAJ 1.2 to deliver a higher degree of potential interoperability without sacrificing usability or backward compatibility.With SAAJ 1.2, users can now use fields of the
SOAPMessageclass to do the following:
CHARACTER_SET_ENCODING, with a value of "utf-8" or "utf-16")
WRITE_XML_DECLARATION, with a value of "true" or "false")
The SAAJ 1.2 API provides methods that make it easier for the end user to conform to the recommendations of SOAP 1.1 or WS-I. The new methods automate frequent or error-prone tasks, leading to higher productivity, fewer errors, and lower technical support requirements. In addition, because the average developer may not have extensive knowledge of DOM APIs, the SAAJ API supports common SOAP use cases that involve DOM. Some of these methods are as follows:
Node.setValue(String)sets the value of the current node or its child
setFaultString(String, Locale)provide locale support for fault strings.
SOAPBody.addDocument(Document)adds the root node of a DOM document as a child of the
SOAPBodyelement. This method makes it easier to wrap documents in a SOAP message.
examineMustUnderstandHeaderElements(String)allow the programmer to extract and examine all header elements or only those with the MustUnderstand attribute set to true.
getSOAPHeader()allow the programmer to access the body and header elements directly, instead of having to navigate through the
This release contains the following sample applications. You can reach the
samples by starting Tomcat and then opening
http://localhost:8080/index.html in a browser.
Instructions for running the sample applications, along with more detailed
descriptions, are in the file
saaj-simple- A simple example of sending and receiving a message using the SAAJ API (the
saaj-book- Another example of sending and receiving a message using the SAAJ API
saaj-translator- A simple example of sending and receiving a message using the SAAJ API to get a translation of a word using a translation service
uddiping- A standalone sample using the SAAJ API that talks to a live UDDI registry
At this release, the SAAJ RI has the following known issues:
The Apache XML Security library, which is used by the XWS-Security
libraries, will sometimes create duplicate
xmlns attributes when
used with J2SE SDK 1.4.2 b-28 to create signatures in DOM documents, and in
SAAJ documents in particular, from a standalone application. If you encounter
this problem, the recommended solution is to install a later version of J2SE
SDK 1.4.2, such as the version currently available from
At this release of the SAAJ RI, the Content-Type headers are produced on
multiple lines, although the
section of the SOAP with Attachments specification says, "SOAP
message senders should send Content-Type headers on a single long line."
This problem occurs because the implementation relies on the
javax.mail.internet.ContentType class to generate the Content-Type
header. The problem will be fixed in a subsequent release.
According to the SOAP 1.1 specification, a fault code is required to be a
QName. Hence it must be of the form
where the prefix has been defined in a namespace declaration.
At SAAJ 1.1, the
SOAPFault.setFaultCode(String faultCode) method
did not enforce this restriction. This problem has been fixed in SAAJ 1.2.
An exception will now be thrown if the fault code is not a qualified QName.
Also, a new method,
SOAPFault.setFaultCode(Name name), has been
introduced in SAAJ 1.2.