For an updated, online version of these release notes, see Release Notes.

Revised: 09/26/2003

Contents

• Read This Section First
• What This Release Includes
• New Features
• Sample Applications
• Known Issues

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 Java^TM 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 Java^TM (SAAJ) 1.2.

This release includes

• The SAAJ 1.2 RI
• API documentation
• Sample applications

This release depends on the following components:

• JAXP (1.2.4)
• JavaMail^TM API (1.1.3 / 1.2) and JavaBeans^TM Activation Framework (JAF)

The SAAJ RI release contents are arranged in the following structure within the Java WSDP release:

New Features

SAAJ 1.2 has the following new features:

• DOM integration
• SOAPMessage properties
• New methods for ease of use

DOM Integration

SAAJ APIs now extend Document Object Model (DOM) APIs, as follows:

• javax.xml.soap.Node extends org.w3c.dom.Node
• javax.xml.soap.SOAPElement extends org.w3c.dom.Element
• javax.xml.soap.SOAPPart implements org.w3c.dom.Document
• javax.xml.soap.Text extends org.w3c.dom.Text

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.

SOAPMessage Properties

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.

• Set character encoding (CHARACTER_SET_ENCODING, with a value of "utf-8" or "utf-16")
• Turn on writing an XML Declaration at the start of the SOAP part of the message (WRITE_XML_DECLARATION, with a value of "true" or "false")

New Methods for Ease of Use

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:

• The method Node.setValue(String) sets the value of the current node or its child Text node.
• The SOAPFault methods getFaultString() and setFaultString(String, Locale) provide locale support for fault strings.
• The method SOAPBody.addDocument(Document) adds the root node of a DOM document as a child of the SOAPBody element. This method makes it easier to wrap documents in a SOAP message.
• The SOAPHeader methods examineAllHeaderElements(), extractAllHeaderElements(), and examineMustUnderstandHeaderElements(String) allow the programmer to extract and examine all header elements or only those with the MustUnderstand attribute set to true.
• The SOAPMessage methods getSOAPBody() and getSOAPHeader() allow the programmer to access the body and header elements directly, instead of having to navigate through the SOAPPart and the Envelope.

Sample Applications

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 samples.html.

• saaj-simple - A simple example of sending and receiving a message using the SAAJ API (the javax.xml.soap package)
• 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 http://java.sun.com/j2se.

• At this release of the SAAJ RI, the Content-Type headers are produced on multiple lines, although the HTTP Binding 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 prefix:localName, 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.