Find JSRs
Submit this Search


Ad Banner
 
 
 
 

 SAAJ 1.2 Change Log

SOAP with Attachments API for JavaTM (SAAJ) 1.2

April 10, 2003

 

Quick jump to changes

C001, C002, C003, C004, C005, C006, C007, C008, C009, C010, C011, C012, C013, C014, C015, C016, C017, C018, C019, C020, C021, C022, C023, C024, C025, C026, C027, C028, C029, C030, C031, C032, C033, C034, C035, C036, C037, C038, C039, C040, C041, C042, C043, C044, C045, C046, C047

1) Description

Maintenance revision of the SOAP with Attachments API for JavaTM (SAAJ), version 1.2.

2) Specification Leads

Nicholas Kassem and Phil Goodwin, Sun Microsystems, Inc.

3) Feedback

Comments should be sent to mailto:jaxm-final@sun.com

4) Rationale for proposed changes

The goal of this maintenance release is to provide support for the proposed WS-I Basic Profile of SOAP 1.1. In addition we would like to take the opportunity to make a number of corrections and clarifications to the specification and JavaDocs.

The WS-I Basic Profile does not add any capabilities to the SOAP 1.1 document that it moderates. It does, however, promote the use of some SOAP 1.1 features even as it proscribes the use of others. The goal of this change log is to make it easier for applications to create and use messages that are WS-I conformant. This maintenance release is concerned with the following areas:

  1. The use of literal encoding

  2. Access to SOAP 1.1 features that are of increased prominence

  3. Easier conformance to WS-I recommendations

SOAP 1.2 support has been considered and set aside for the current maintenance cycle in order to reinforce the JCP's focus on WS-I support in J2EE 1.4

5) Summary of Proposed changes

  1. Bind SAAJ APIs to DOM APIs
    Rationale: DOM is already in use in many environments. If SAAJ trees are also DOM trees then SAAJ will be able to integrate more easily with many applications and tools.

  2. Add properties to SOAPMessage
    Rationale: There are several details about the formatting and encoding of a SOAP message that can affect interoperability. Giving the end user control over these details while retaining the same defaults as SAAJ 1.1 allows us to deliver a higher degree of potential interoperability without sacrificing usability or backward compatibility.

  3. Add ease of use methods to key APIs
     Rationale: There are several opportunities in the SAAJ API to make it easier on the end user to conform to the recommendations of SOAP 1.1 or WS-I. These new methods will automate frequent or error-prone tasks, leading to higher productivity, fewer errors - and less technical support.In addition, it is expected that the average developer will not have extensive knowledge of DOM APIs and so we would like to support common SOAP use cases involving DOM through the SAAJ APIs.

  4. Clarify and correct the wording of JavaDocs and specification
    Scope: None of these changes will break backward compatibility or allow new behavior that was explicitly forbidden before. In particular, conforming implementations will not break existing clients and will be capable of passing the existing TCK. Some of these changes will impose new requirements on implementations. Where that is the case the changes will be specifically enumerated in this document.
    Rationale: Corrections of this nature cost little and improve the overall integrity of the specification making correct implementations easier to create, validate and use.


6) Proposed Changes Supporting the addition of DOM Interfaces
The following classes and interfaces would implement interfaces from the org.w3c.dom package:

C001

javax.xml.soap
Interface Node

All Superinterfaces:
org.w3c.dom.Node
public interface Node
extends org.w3c.dom.Node

A representation of a node (element) in an XML document. This interface extends the standard DOM Node interface with methods for getting and setting the value of a node, for getting and setting the parent of a node, and for removing a node.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, getAttributes, getChildNodes, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, hasAttributes, hasChildNodes, insertBefore, isSupported, normalize, removeChild, replaceChild, setNodeValue, setPrefix

C002

javax.xml.soap
Interface SOAPElement

All Superinterfaces:
org.w3c.dom.Element, Node, org.w3c.dom.Node
public interface SOAPElement
extends Node, org.w3c.dom.Element

An object representing the contents in a SOAPBody object, the contents in a SOAPHeader object, the content that can follow the SOAPBody object in a SOAPEnvelope object, or what can follow the detail element in a SOAPFault object. It is the base class for all of the classes that represent the SOAP objects as defined in the SOAP specification.
An object representing an element of a SOAP message that is allowed but not specifically prescribed by a SOAP specification. This interface serves as the base interface for those objects that are specifically prescribed by a SOAP specification.

Methods in this interface that are required to return SAAJ specific objects may "silently" replace nodes in the tree as required to successfully return objects of the correct type. See getChildElements() and javax.xml.soapfor details.



Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, getAttributes, getChildNodes, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, hasAttributes, hasChildNodes, insertBefore, isSupported, normalize, removeChild, replaceChild, setNodeValue, setPrefix
Methods inherited from interface org.w3c.dom.Element
getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getElementsByTagName, getElementsByTagNameNS, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS

C003

javax.xml.soap
Class SOAPPart 

java.lang.Object
  |
  +--javax.xml.soap.SOAPPart
All Implemented Interfaces:
org.w3c.dom.Document, org.w3c.dom.Node
public abstract class SOAPPart
extends java.lang.Object
implements org.w3c.dom.Document
Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
Methods inherited from interface org.w3c.dom.Document
createAttribute, createAttributeNS, createCDATASection, createComment, createDocumentFragment, createElement, createElementNS, createEntityReference, createProcessingInstruction, createTextNode, getDoctype, getDocumentElement, getElementById, getElementsByTagName, getElementsByTagNameNS, getImplementation, importNode
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, getAttributes, getChildNodes, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, hasAttributes, hasChildNodes, insertBefore, isSupported, normalize, removeChild, replaceChild, setNodeValue, setPrefix

C004

javax.xml.soap
Interface Text

All Superinterfaces:
org.w3c.dom.CharacterData, Node, org.w3c.dom.Node, org.w3c.dom.Text
public interface Text
extends Node, org.w3c.dom.Text

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, getAttributes, getChildNodes, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, hasAttributes, hasChildNodes, insertBefore, isSupported, normalize, removeChild, replaceChild, setNodeValue, setPrefix
Methods inherited from interface org.w3c.dom.Text
splitText
Methods inherited from interface org.w3c.dom.CharacterData
appendData, deleteData, getData, getLength, insertData, replaceData, setData, substringData

 

C046

This would be added to the package comment:

In addition the APIs in the javax.xml.soap package extend their counterparts in the org.w3c.dom package. This means that the SOAPPart of a SOAPMessage is also a DOM Level 2 Document, and can be manipulated as such by applications, tools and libraries that use DOM (see http://www.w3.org/DOM/ for more information). It is important to note that, while it is possible to use DOM APIs to add ordinary DOM nodes to a SAAJ tree, the SAAJ APIs are still required to return SAAJ types when examining or manipulating the tree. In order to accomplish this the SAAJ APIs (specifically SOAPElement.getChildElements()) are allowed to "silently" replace objects that are incorrectly typed relative to SAAJ requirements with equivalent objects of the required type. These replacements must never cause the logical structure of the tree to change, so from the perspective of the DOM APIs the tree will remain unchanged. However, the physical composition of the tree will have changed so that references to the nodes that were replaced will refer to nodes that are no longer a part of the tree. The SAAJ APIs are not allowed to make these replacements if they are not required so the replacement objects will never subsequently be "silently" replaced by future calls to the SAAJ API. What this means in practical terms is that an application that starts to use SAAJ APIs on a tree after manipulating it using DOM APIs must assume that the tree has been translated into an all SAAJ tree and that any references to objects within the tree that were obtained using DOM APIs are no longer valid. Switching from SAAJ APIs to DOM APIs is not allowed to cause invalid references and neither is using SAAJ APIs exclusively. It is only switching from using DOM APIs on a particular SAAJ tree to using SAAJ APIs that causes the risk of invalid references.

7) Proposed Changes for Adding Properties to SOAPMessage

These are the additional methods and constants intended to provide user control over SOAPMessage properties.

javax.xml.soap
Class SOAPMessage 

java.lang.Object
  |
  +--javax.xml.soap.SOAPMessage
public abstract class SOAPMessage
extends java.lang.Object

Method Summary
abstract java.lang.String getProperty(java.lang.String property)
Retrieves value of the specified property.
abstract void setProperty(java.lang.String property, java.lang.Object value)
Associates the specified value with the specified property.


Method Detail

C005

getProperty 

public abstract java.lang.Object getProperty(java.lang.String property)
                                      throws SOAPException
Retrieves value of the specified property.


Parameters:
property - the name of the property to retrieve
Returns:
the value of the property or null if no such property exists.
Throws:
SOAPException - if the property name is not recognized.
Since:
SAAJ 1.2

C006

setProperty 

public abstract void setProperty(java.lang.String property,
                                 java.lang.Object value)
                          throws SOAPException
Associates the specified value with the specified property. If there was already a value associated with this property, the old value is replaced.

The valid property names include WRITE_XML_DECLARATION and CHARACTER_SET_ENCODING. All of these standard SAAJ properties are prefixed by "javax.xml.soap". Vendors may also add implementation specific properties. These properties must be prefixed with package names that are unique to the vendor.

Setting the property WRITE_XML_DECLARATION to "true" will cause an XML Declaration to be written out at the start of the SOAP message. The default value of "false" suppresses this declaration.

The property CHARACTER_SET_ENCODING defaults to the value "utf-8" which causes the SOAP message to be encoded using UTF-8. Setting CHARACTER_SET_ENCODING to "utf-16" causes the SOAP message to be encoded using UTF-16.

Some implementations may allow encodings in addition to UTF-8 and UTF-16. Refer to your vendor's documentation for details.




Parameters:
property - the property with which the specified value is to be associated.
value - the value to be associated with the specified property
Throws:
SOAPException - if the property name is not recognized.
Since:
SAAJ 1.2
Field Summary
static java.lang.String CHARACTER_SET_ENCODING
Specifies the character type encoding for the SOAP Message.
static java.lang.String WRITE_XML_DECLARATION
WRITE_XML_DECLARATION specifies whether the SOAP Message should contain an XML declaration; the value must be "true" or "false".

Field Detail

C007

CHARACTER_SET_ENCODING 

public static final java.lang.String CHARACTER_SET_ENCODING
Specifies the character type encoding for the SOAP Message. Valid values include "utf-8" and "utf-16". See vendor documentation for additional supported values. The default is "utf-8".

Since:
SAAJ 1.2
See Also:
SOAPMessage.setProperty, Constant Field Values

C008

WRITE_XML_DECLARATION 

public static final java.lang.String WRITE_XML_DECLARATION
Specifies whether the SOAP Message should contain an XML declaration. The only valid values are "true" and "false". The default is "false".

Since:
SAAJ 1.2
See Also:
SOAPMessage.setProperty, Constant Field Values

Constant Field Values

javax.xml.soap. SOAPMessage
public static final java.lang.String CHARACTER_SET_ENCODING "javax.xml.soap.character-set-encoding"
public static final java.lang.String WRITE_XML_DECLARATION "javax.xml.soap.write-xml-declaration"

 

8) Proposed Changes to Enhance Ease of Use

C009

Change JavaDoc:

javax.xml.soap
Interface Node

Method Summary
void detachNode()
Removes this Node object from the tree. Once removed, this node can be garbage collected if there are no application references to it.

Rationale: This was too much of a restriction on implementors.

C010

Add method:

javax.xml.soap
Interface Node

Method Summary
void setValue(java.lang.String value)
If this is a Text node then this method will set its value, otherwise it sets the value of the immediate (Text) child of this node.
Method Detail

setValue 

public void setValue(java.lang.String value)
If this is a Text node then this method will set its value, otherwise it sets the value of the immediate (Text) child of this node. The value of the immediate child of this node can be set only if, there is one child node and that node is a Text node, or if there are no children in which case a child Text node will be created.



Throws:
java.lang.IllegalStateException - if the node is not a Text node and either has more than one child node or has a child node that is not a Text node.
Since:
SAAJ 1.2


Rationale: This simplifies a common case where developers want to change a value in a tree without changing the structure of the tree. The equivalent operation, using only SAAJ APIs, is thought by some to be cumbersome and error prone.
Add methods:

javax.xml.soap
Interface SOAPFault


Method Summary
Name getFaultCodeAsName()
Gets the mandatory SOAP 1.1 fault code for this SOAPFault object as a SAAJ Name object.
void setFaultCode( Name faultCodeQName)
Sets this SOAPFault object with the given fault code.
void
 setFaultString(java.lang.String faultString, java.util.Locale locale)
Sets the fault string for this SOAPFault object to the given string and localized to the given locale.
java.util.Locale
 getFaultStringLocale()
Gets the locale of the fault string for this SOAPFault object.




Method Detail

C011

getFaultCodeAsName 

public Name getFaultCodeAsName()
Gets the mandatory SOAP 1.1 fault code for this SOAPFault object as a SAAJ Name object. The SOAP 1.1 specification requires the value of the "faultcode" element to be of type QName. This method returns the content of the element as a QName in the form of a SAAJ Name object. This method should be used instead of the getFaultCode method since it allows applications to easily access the namespace name without additional parsing.

In the future, a QName object version of this method may also be added.




Returns:
a Name representing the faultcode
Since:
SAAJ 1.2
See Also:
setFaultCode(Name)


C012

setFaultCode 

public void setFaultCode(Name faultCodeQName) throws SOAPException
Sets this SOAPFault object with the given fault code.

Fault codes, which give information about the fault, are defined in the SOAP 1.1 specification. A fault code is mandatory and must be of type QName. This method provides a convenient way to set a fault code. For example, 

 SOAPEnvelope se = ...;
 // Create a qualified name in the SOAP namespace with a localName
 // of "Client".  Note that prefix parameter is optional and is null
 // here which causes the implementation to use an appropriate prefix.
 Name qname = se.createName("Client", null,
                             SOAPConstants.URI_NS_SOAP_ENVELOPE);
 SOAPFault fault = ...;

 fault.setFaultCode(qname);
It is preferable to use this method over setFaultCode(String).



Parameters:
faultCodeQName - a Name object giving the fault code to be set.It must be namespace qualified.
Throws:
SOAPException - if there was an error in adding the faultcode element to the underlying XML tree.
Since:
SAAJ 1.2
See Also:
getFaultCodeAsName()


C013

setFaultString 

public void setFaultString(java.lang.String faultString,
                            java.util.Locale locale)
                    throws SOAPException
Sets the fault string for this SOAPFault object to the given string and localized to the given locale.



Parameters:
faultString - a String giving an explanation of the fault
locale - a Locale object indicating the native language of the faultString
Throws:
SOAPException - if there was an error in adding the faultString to the underlying XML tree.
Since:
SAAJ 1.2
See Also:
getFaultString()

C014

getFaultStringLocale 

public java.util.Locale getFaultStringLocale()
Gets the locale of the fault string for this SOAPFault object.



Returns:
a Locale object indicating the native language of the fault string or null if no locale was specified

Since:
SAAJ 1.2
See Also:
setFaultString(String, Locale)
Rationale: These two methods allow the fault code to be treated as a fully qualified name, as required by SOAP 1.1.

C015

Add method:

javax.xml.soap
Interface SOAPBody

Method Detail

addDocument 

public SOAPBodyElement addDocument(org.w3c.dom.Document document)
Adds the root node of the DOM Document to this SOAPBody object.

C016

Calling this method invalidates the document parameter. The client application should discard all references to this Document and its contents upon calling addDocument. The behavior of an application that continues to use such references is undefined. [end of C045]




Parameters:
document - the Document object whose root node will be added to this SOAPBody.
Returns:
the SOAPBodyElement that represents the root node that was added.
Throws:
SOAPException - if the Document cannot be added
Since:
SAAJ 1.2

Rationale: This user requested method makes it easier to use DOM in SAAJ applications. Without this method the end user must rely entirely on DOM APIs to perform this operation. C045 allows a wider range of implementation choices including possible optimizations at the expense of some usability.

C047

Add methods:

javax.xml.soap
Interface SOAPBody

Method Detail

addFault 

public SOAPFault addFault(Name faultCode,
                          java.lang.String faultString,
                          java.util.Locale locale)
                          throws SOAPException
Creates a new SOAPFault object and adds it to this SOAPBody object. The new SOAPFault will have a faultcode element that is set to the faultCode parameter and a faultstring set to faultString and localized to locale.

A SOAPBody may contain at most one SOAPFault child element



Parameters:
faultCode - a Name object giving the fault code to be set; must be one of the fault codes defined in the SOAP 1.1 specification and of type QName
faultString - a String giving an explanation of the fault
locale - a Locale object indicating the native language of the faultString
Returns:
the new SOAPFault object
Throws:
SOAPException - if there is a SOAP error
Since:
SAAJ 1.2
See Also:
SOAPFault.setFaultCode(javax.xml.soap.Name), SOAPFault.setFaultString(java.lang.String)

addFault 

public SOAPFault addFault(Name faultCode,
                          java.lang.String faultString)
                   throws SOAPException
Creates a new SOAPFault object and adds it to this SOAPBody object. The new SOAPFault will have a faultcode element that is set to the faultCode parameter and a faultstring set to faultString.

A SOAPBody may contain at most one SOAPFault child element



Parameters:
faultCode - a Name object giving the fault code to be set; must be one of the fault codes defined in the SOAP 1.1 specification and of type QName
faultString - a String giving an explanation of the fault
Returns:
the new SOAPFault object
Throws:
SOAPException - if there is a SOAP error
Since:
SAAJ 1.2
See Also:
SOAPFault.setFaultCode(javax.xml.soap.Name), SOAPFault.setFaultString(java.lang.String)

Rationale: Use of these methods would let developers create faults that contain all of the necessary sub-elements, properly initialized, with a single call.



C017

Add method:

javax.xml.soap
Interface SOAPElement


Method Detail




removeContents 

public void removeContents()

Detaches all children of this SOAPElement.

This method is useful for rolling back the construction of partially completed SOAPHeaders and SOAPBodys in preparation for sending a fault when an error condition is detected. It is also useful for recycling portions of a document within a SOAP message.

Since:
SAAJ 1.2

Rationale: This method supports a common use case where elements in a partially assembled body are replaced with a fault in response to an error condition. It originated in the SOAPBody interface and was pulled up into SOAPElement because of its general utility.

C018

Add method:

javax.xml.soap
Interface SOAPElement


Method Detail



getVisibleNamespacePrefixes 

public java.util.Iterator getVisibleNamespacePrefixes()
Returns an Iterator over the namespace prefix Strings visible to this element. The prefixes returned by this iterator can be passed to the method getNamespaceURI to retrieve the URI of each namespace.
Returns:
an iterator over the namespace prefixes that are within scope of this SOAPElement object
Since:
SAAJ 1.2
Rationale: This is a common operation. It is likely that vendors can provide an implementation that is more efficient than what can be obtained directly from the other SAAJ or DOM APIs.

Add methods:

javax.xml.soap
Interface SOAPHeader

Method Summary
java.util.Iterator examineAllHeaderElements()
Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object.
java.util.Iterator examineMustUnderstandHeaderElements(java.lang.String actor)
Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object that have the specified actor and that have a MustUnderstand attribute whose value is equivalent to true.
java.util.Iterator extractAllHeaderElements()
Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object and detaches them from this SOAPHeader object.

C019

examineAllHeaderElements 

public java.util.Iterator examineAllHeaderElements()
Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object.



Returns:
an Iterator object over all the SOAPHeaderElement objects contained by this SOAPHeader
Since:
SAAJ 1.2
See Also:
extractAllHeaderElements()

C020

examineMustUnderstandHeaderElements 

public java.util.Iterator examineMustUnderstandHeaderElements(java.lang.String actor)
Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object that have the specified actor and that have a MustUnderstand attribute whose value is equivalent to true.



Parameters:
actor - a String giving the URI of the actor for which to search
Returns:
an Iterator object over all the SOAPHeaderElement objects that contain the specified actor and are marked as MustUnderstand
Since:
SAAJ 1.2
See Also:
examineHeaderElements(java.lang.String), extractHeaderElements(java.lang.String), SOAPConstants.URI_SOAP_ACTOR_NEXT

C021

extractAllHeaderElements 

public java.util.Iterator extractAllHeaderElements()
Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object and detaches them from this SOAPHeader object.



Returns:
an Iterator object over all the SOAPHeaderElement objects contained by this SOAPHeader
Since:
SAAJ 1.2
See Also:
examineAllHeaderElements()

Rationale: The ability to examine or extract all header elements gives an application flexibility to implement its own processing model. Applications implementing SOAP processing will need to be able to examine all of the header elements marked must understand in order to correctly fulfill the must understand contract. The examineMustUnderstandHeaderElements(String) method provides easy and correct access to this piece of necessary and routine processing.

Add methods:

javax.xml.soap
Class SOAPMessage

Method Summary
abstract SOAPBody getSOAPBody()
Gets the SOAP Body contained in this SOAPMessage object.
abstract SOAPHeader getSOAPHeader()
Gets the SOAP Header contained in this SOAPMessage object.

Method Detail

C022

getSOAPBody 

public abstract SOAPBody getSOAPBody()
Gets the SOAP Body contained in this SOAPMessage object.




Returns:
the SOAPBody object contained by this SOAPMessage object

Throws:
SOAPException - if the SOAP Body does not exist or cannot be retrieved
Since:
SAAJ 1.2

C023

getSOAPHeader 

public abstract SOAPHeader getSOAPHeader()
Gets the SOAP Header contained in this SOAPMessage object.




Returns:
the SOAPHeader object contained by this SOAPMessage object

Throws:
SOAPException - if the SOAP Header does not exist or cannot be retrieved
Since:
SAAJ 1.2

Rationale: These methods make writing SAAJ clients easier by eliminating the getSOAPPart().getEnvelope() call sequence for gaining access to the header and body elements of the message. This allows developers to focus on their application needs rather than the details of the structure of SOAP messages.


 

9) Corrections
The following JavaDoc changes will correct ambiguities and errors from earlier versions.

javax.xml.soap
Interface Detail

Method Detail

C024

getDetailEntries 

public java.util.Iterator getDetailEntries()
Gets a list of detail entries Gets an Iterator over all of the DetailEntrys in this Detail object.



Returns:
an Iterator object over the DetailEntry objects in this Detail object
Rationale:The actual return type is an Iterator, not a List.

javax.xml.soap
Class MessageFactory

C025

public abstract class MessageFactory
extends java.lang.Object

A factory for creating SOAPMessage objects. A JAXM client performs the following steps to create a message.

  • Creates a MessageFactory object from a ProviderConnection object (con in the following line of code). The String passed to the createMessageFactory method is the name of a messaging profile, which must be the URL for the schema. 
    MessageFactory mf = con.createMessageFactory(schemaURL);
  • Calls the method createMessage on the MessageFactory object. All messages produced by this MessageFactory object will have the header information appropriate for the messaging profile that was specified when the MessageFactory object was created. 
    SOAPMessage m = mf.createMessage();
It is also possible to create a MessageFactory object

A SAAJ client can create a MessageFactory object using the method newInstance, as shown in the following line of code.

[...] If a MessageFactory object was created using a ProviderConnection object, which means that it was initialized with a specified profile, it MessageFactory objects can be initialized with a JAXM profile. In such a case it will produce messages that also come prepopulated with additional entries in the SOAPHeader object and the SOAPBody object.
[...]

Rationale: SAAJ is independent of JAXM. While it is appropriate to mention the available interactions between the two, it is misleading to suggest that JAXM APIs are the endorsed mechanism for accessing the SAAJ factory classes.

javax.xml.soap
Class MimeHeaders

C026

Method Summary
java.util.Iterator getAllHeaders()
Returns all the headers MimeHeader objects in this MimeHeaders object.

Rationale:The method summaries for methods that return Iterators should indicate the types of the objects contained by the iterated collections. Otherwise clients will be unable to use the objects returned by the iteration process.

javax.xml.soap
Interface Name

Method Detail

C027

getPrefix 

public java.lang.String getPrefix()
Returns the prefix associated with the namespace for the XML Returns the prefix that was specified when this Name object was initialized. This prefix is associated with the namespace for the XML name that this Name object represents.


Returns:
the prefix as a string

Rationale:The phrase "the prefix" was ambiguous since there may be zero or many prefixes associated with a given namespace within a given context. This change helps to clarify that a Name is a simple value, unassociated with any context and providing no claims with respect to the validity of its prefix. The TCK already enforces this interpretation of the original wording. This is simply a clarification of the original intent. It is also consistent with the thinking that is driving the evolution of the QName class.

javax.xml.soap
Interface Node

Method Detail

C028

getValue 

public java.lang.String getValue()
Returns the value of the immediate child of this Node object if a child exists and its value is text.
Returns the value of this node if this is a Text node or the value of the immediate child of this node otherwise. If there is an immediate child of this Node that it is a Text node then it's value will be returned. If there is more than one Text node then the value of the first Text Node will be returned. Otherwise null is returned.



Returns:
a String with the text of the immediate child of this Node object if (1) there is a child and (2) the child is a Text object; null otherwise
a String with the text of this node if this is a Text node or the text contained by the first immediate child of this Node object that is a Text object if such a child exists; null otherwise.

Rationale:This reflects the actual behavior of the Reference Implementation, the original intent of the specification, the equivalent behavior of DOM, and what we believe the end user will expect. It does represent a new behavior rather than a new restriction which raises the possibility of broken backward compatibility, however, in light of the facts listed above coupled with the fact that the TCK already allows this behavior (or else the Reference Implementation would not have passed) we believe that it is both safe and desirable to make this change.

javax.xml.soap
Interface SOAPBody

Method Detail

C029

addFault 

public SOAPException
Creates a new SOAPFault object and adds it to this SOAPBody object. The new SOAPFault will have default values set for the mandatory child elements faultcode and faultstring.

A SOAPBody may contain at most oneSOAPFault child element.




Returns:
the new SOAPFault object
Throws:
SOAPException - if there is a SOAP error

Rationale:This reflects restrictions present in the SOAP 1.1 specification.

javax.xml.soap
Class SOAPConnection

C030

public abstract class SOAPConnection
extends java.lang.Object

A point-to-point connection that a client can use for sending messages directly to a remote party (represented by a URL, for instance).

A client can obtain a SOAPConnection object simply by calling the following static method. 

SOAPConnection con = SOAPConnection.newInstance();


A client can obtain a SOAPConnection object using a SOAPConnectionFactory object as in the following example: 

      SOAPConnectionFactory factory = SOAPConnectionFactory.newInstance();
      SOAPConnection con = factory.createConnection();
A SOAPConnection object can be used to send messages directly to a URL following the request/response paradigm. That is, messages are sent using the method call, which sends the message and then waits until it gets a reply.

Rationale:The original JavaDoc was wrong.

javax.xml.soap
Class SOAPConnectionFactory

C031

public abstract class SOAPConnectionFactory
extends java.lang.Object

A factory for creating SOAPConnection objects. Implementation of this class is optional. If SOAPConnectionFactory.newInstance() throws an UnsupportedOperationException then the implementation does not support the SAAJ communication infrastructure. Otherwise SOAPConnection objects can be created by calling createConnection() on the newly created SOAPConnectionFactory object.

Rationale:There was no JavaDoc class comment for this class before. This comment clearly states the optional nature of the SAAJ communication artifacts and exposes the mechanism that allows them to be optional.

javax.xml.soap
Interface SOAPConstants

Field Detail

C032

URI_NS_SOAP_ENVELOPE 

public static final java.lang.String URI_NS_SOAP_ENVELOPE
The namespace identifier for the SOAP 1.1 envelope. All SOAPElements in this namespace are defined by the SOAP 1.1 specification.


See Also:
Constant Field Values

C033

URI_NS_SOAP_ENCODING 

public static final java.lang.String URI_NS_SOAP_ENCODING
The namespace identifier for the SOAP 1.1 encoding. An attribute named encodingStyle in the URI_NS_SOAP_ENVELOPE namespace and set to the value URI_NS_SOAP_ENCODING can be added to an element to indicate that it is encoded using the rules in section 5 of the SOAP 1.1 specification.

See Also:
Constant Field Values

C034

URI_SOAP_ACTOR_NEXT 

public static final java.lang.String URI_SOAP_ACTOR_NEXT
The URI identifying the first next application processing a SOAP request as the intended actor for a SOAP 1.1 header entry (see section 4.2.2 of the SOAP 1.1 specification).

This value can be passed to SOAPHeader.examineMustUnderstandHeaderElements(String), SOAPHeader.examineHeaderElements(String) and SOAPHeader.extractHeaderElements(String)


See Also:
Constant Field Values

Rationale:These are just informational changes. They do not change the meaning of the specification at all.

javax.xml.soap
Interface SOAPElement

public interface SOAPElement
extends Node, org.w3c.dom.Element

Method Summary
SOAPElement

C035

addChildElement(java.lang.String localName)
Creates a new SOAPElement object initialized with the given String specified local name and adds the new element to this SOAPElement object.
java.util.Iterator

C036

getAllAttributes()
Returns an iterator over all of the attribute names Iterator over all of the attribute Name objects in this SOAPElement object.
java.util.Iterator

C037

getChildElements()
Returns an iterator over all the immediate content of this element.
Returns an Iterator over all the immediate child Nodes of this element. This includes Text objects as well as SOAPElement objects.

Calling this method may cause child Element, SOAPElement and org.w3c.dom.Text nodes to be replaced by SOAPElement, SOAPHeaderElement, SOAPBodyElement or javax.xml.soap.Text nodes as appropriate for the type of this parent node. As a result the calling application must treat any existing references to these child nodes that have been obtained through DOM APIs as invalid and either discard them or refresh them with the values returned by this Iterator. This behavior can be avoided by calling the equivalent DOM APIs. See javax.xml.soapfor more details.


java.util.Iterator

C038

getChildElements( Name name)
Returns an iterator over all the child elements with the specified name. Returns an Iterator over all the immediate child Nodes of this element with the specified name. All of these children will be SOAPElement nodes.

Calling this method may cause child Element, SOAPElement and org.w3c.dom.Text nodes to be replaced by SOAPElement, SOAPHeaderElement, SOAPBodyElement or javax.xml.soap.Text nodes as appropriate for the type of this parent node. As a result the calling application must treat any existing references to these child nodes that have been obtained through DOM APIs as invalid and either discard them or refresh them with the values returned by this Iterator. This behavior can be avoided by calling the equivalent DOM APIs. See javax.xml.soapfor more details.


java.util.Iterator

C039

getNamespacePrefixes()
Returns an iterator of namespace prefixes Iterator over the namespace prefix Strings declared by this element. The prefixes returned by this iterator can be passed to the method getNamespaceURI to retrieve the URI of each namespace.

Rationale: Clarifies that the String parameter of addChildElement is intended to be the name of the new element -- not its value, and specifies the types to expect to be able to extract from Iterator return values. C037 and C038 clarify the consequences of moving nodes around in the SAAJ tree and the option of avoiding these consequences via DOM interfaces.

javax.xml.soap
Class SOAPException

Method Detail

initCause 

public java.lang.Throwable initCause(java.lang.Throwable cause)
[...]



C040


Throws:
[...]
java.lang.IllegalStateException - if this SOAPException object was created with SOAPException(Throwable) or SOAPException(String,Throwable), or this method has already been called on this SOAPException object
if the cause for this SOAPException object has already been initialized

Rationale:Tightens up the language.

javax.xml.soap
Interface SOAPHeader

Method Summary
java.util.Iterator

C041

examineHeaderElements(java.lang.String actor)
Returns a list of all the SOAPHeaderElement objects Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object that have the specified actor.
java.util.Iterator

C042

extractHeaderElements(java.lang.String actor)
Returns a list of all the SOAPHeaderElement objects Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object that have the specified actor and detaches them from this SOAPHeader object.

Rationale:These methods return iterators, not lists.

javax.xml.soap
Class SOAPMessage

saveRequired 

public abstract boolean saveRequired()

C043

Indicates whether this SOAPMessage object has had the method saveChanges called on it. Indicates whether this SOAPMessage object needs to have the method saveChanges called on it.


Returns:
true if saveChanges has been called on this message at least once; true if saveChanges needs to be called; false otherwise.

Rationale:Original wording was almost the exact opposite of the intent.

javax.xml.soap
Class AttachmentPart 

java.lang.Object
  |
  +--javax.xml.soap.AttachmentPart
Method Detail

getContent

public abstract java.lang.Object getContent() throws SOAPException
[...]

C044

A JAXMSAAJ-compliant implementation must, as a minimum, return a java.lang.String object corresponding to any content stream with a Content-Type value of text/plain, a javax.xml.transform.stream.StreamSource object corresponding to a content stream with a Content-Type value of text/xml, a java.awt.Image object corresponding to a content stream with a Content-Type value of image/gif or image/jpeg. For those content types that an installed DataContentHandler object does not understand, the DataContentHandler object is required to return a java.io.InputStream object with the raw bytes.



Returns:
a Java object with the content of this AttachmentPart object
Throws:
SOAPException - if there is no content set into this AttachmentPart object or if there was a data transformation error

Rationale: This is the SAAJ API not JAXM. The package name was wrong.

javax.xml.soap
Class SOAPPart 

java.lang.Object
  |
  +--javax.xml.soap.SOAPPart

Method Detail

setContent 

public abstract void setContent(javax.xml.transform.Source source)
                         throws SOAPException

C045


Sets the content of the SOAPEnvelope object with the data from the given Source object. This Source must contain a valid SOAP document.


Throws:
SOAPException - if there is a problem in setting the source
See Also:
getContent()

Rationale: It was not clear that the SOAPPart could contain only a SOAP document.

10) Deferred Changes

  1. Deprecating the Name interface in favor of the QName class.
    Rationale: The QName class is currently in the process of being upgraded and moved into a more appropriate package. While it would be appropriate for SAAJ to adopt QName as it's preferred representation of XML qualified names, it makes sense for us to defer this move until the changes to QName are complete. Since the adoption of QName will have no impact on WS-I compatibility it is not urgent that we make this change at this time.