SOAP with Attachments API for JavaTM (SAAJ) 1.3

October 14 2004

 

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

1) Description

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

2) Specification Leads

   V B Kumar Jayanti and  Marc Hadley 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 primarily to provide support for SOAP version 1.2 Message Constructs. In addition, we would like to take the opportunity to make a few corrections and clarifications to the specification and JavaDocs.

SOAP version 1.2 has a number of changes in syntax and provides additional (or clarified) semantics from those described in SOAP 1.1. This maintenance release is concerned with the following areas:

  1. Support for SOAP version 1.2 message constructs in the API.

  2. Factoring out the  creation of all SAAJ Factory classes into a single SPI that allows creation of SOAP version aware Factories.

  3. Addition of a few new classes and  new methods in certain existing classes and interfaces.

  4. Support for overloaded QName based methods in certain classes and interfaces.

  5. Clarification of semantics and correction of wording of JavaDocs and specification.

4.1)  SAAJ 1.3 is Backward Compatible with SAAJ 1.2

       The proposed API changes in SAAJ 1.3 are backward compatible with SAAJ 1.2 APIs.

5) Summary of Proposed Changes

  1. Support for SOAP Version 1.2 Message Constructs
    Rationale:   SOAP Version 1.2 has a number of changes in syntax  and introduces several new Message Constructs.  SAAJ 1.3 will support SOAP Version 1.2 Message Constructs.

  2. SPI for Creation of Factory Instances
    Rationale: SAAJ 1.3 will support SOAP Version 1.2 Message Constructs, while at the same time being backward compatible  in its support for  SOAP Version 1.1.  We would like to define an SPI (SAAJMetaFactory) for factoring out the creation of SOAP Version aware Factory classes into a single place. Changing out the SAAJMetaFactory has the effect of changing out the entire SAAJ implementation.  Backward compatibility is maintained by ensuring that the default protocol is set to SOAP Version 1.1.

  3. Definition of new Class SAAJResult
    Rationale:  A SAAJResult object acts as a holder for the results of a JAXP transformation or a JAXB marshalling, in the form of a SAAJ tree. This class will  make it easier for the end user  when dealing with transformations in situations where the result is expected to be a valid SAAJ tree.

  4. Addition of  overloaded methods which accept a QName instead of a Name
    Rationale:  QName is the preferred representation of XML qualified names, and hence we would like to introduce overloaded methods in all APIs where a corresponding method was accepting a javax.xml.soap.Name as argument. The Name interface may be deprecated in a future release of SAAJ in favor of QName.

  5. Clarify and correct the wording of JavaDocs and specification
    Scope: None of these changes will break backward compatibility for SOAP 1.1 users.
    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. Addition of  new methods in certain Interfaces and Classes
    Rationale:  A few new methods have been introduced in AttachmentPart, SOAPBody, and SOAPElement. These new methods are intended for ease of use and to assist SAAJ users when dealing with some of the newer  SOAP features.

  7. Make SOAPPart  a javax.xml.soap.Node
    Rationale:  The SOAPPart is also a SOAP Node.

  8. Deferred Changes

5.1) Notational Convention Followed in this Document

Everything that is in normal text in all the sections below (with the exception of  section 10) is added new in SAAJ 1.3. In section 10, normal text indicates what was present in SAAJ 1.2,  text that is underlined (underline) indicates what has been added new in SAAJ 1.3, and text in red color with a strikethrough (strikethrough) text-style indicates text that was present in SAAJ 1.2 but has been deleted  in SAAJ 1.3.

5.2)  SAAJ 1.3   Support for  DOM Level 3

           Implementations of SAAJ 1.3 MUST provide support for DOM Level 3 APIs.

6) Proposed Changes Supporting  Additional or Changed Syntax in SOAP Version 1.2


C001

javax.xml.soap
Interface SOAPHeader

All Superinterfaces:
org.w3c.dom.Element, org.w3c.dom.Node, SOAPElement
Method Summary
 SOAPHeaderElement addNotUnderstoodHeaderElement(javax.xml.namespace.QName name)
          Creates a new NotUnderstood SOAPHeaderElement object initialized with the specified name and adds it to this SOAPHeader object.
 SOAPHeaderElement addUpgradeHeaderElement(java.util.Iterator supportedSOAPURIs)
          Creates a new Upgrade SOAPHeaderElement object initialized with the specified List of supported SOAP URIs and adds it to this SOAPHeader object.
 SOAPHeaderElement addUpgradeHeaderElement(java.lang.String supportedSoapUri)
          Creates a new Upgrade SOAPHeaderElement object initialized with the specified supported SOAP URI and adds it to this SOAPHeader object.
 SOAPHeaderElement addUpgradeHeaderElement(java.lang.String[] supportedSoapUris)
          Creates a new Upgrade SOAPHeaderElement object initialized with the specified array of supported SOAP URIs and adds it to this SOAPHeader object.
 
Method Detail

addNotUnderstoodHeaderElement

SOAPHeaderElement addNotUnderstoodHeaderElement(javax.xml.namespace.QName name)
                                                throws SOAPException

Creates a new NotUnderstood SOAPHeaderElement object initialized with the specified name and adds it to this SOAPHeader object. This operation is supported only by SOAP 1.2.


Parameters:
name - a QName object with the name of the SOAPHeaderElement object that was not understood.
Returns:
the new SOAPHeaderElement object that was inserted into this SOAPHeader object
Throws:
SOAPException - if a SOAP error occurs.
java.lang.UnsupportedOperationException - if this is a SOAP 1.1 Header.
Since:
SAAJ 1.3

addUpgradeHeaderElement

SOAPHeaderElement addUpgradeHeaderElement(java.util.Iterator supportedSOAPURIs)
                                          throws SOAPException
Creates a new Upgrade SOAPHeaderElement object initialized with the specified List of supported SOAP URIs and adds it to this SOAPHeader object. This operation is supported on both SOAP 1.1 and SOAP 1.2 header.

Parameters:
supportedSOAPURIs - an Iterator object with the URIs of SOAP versions supported.
Returns:
the new SOAPHeaderElement object that was inserted into this SOAPHeader object
Throws:
SOAPException - if a SOAP error occurs.

Since:
SAAJ 1.3

addUpgradeHeaderElement

SOAPHeaderElement addUpgradeHeaderElement(java.lang.String[] supportedSoapUris)
                                          throws SOAPException


Creates a new Upgrade SOAPHeaderElement object initialized with the specified array of supported SOAP URIs and adds it to this SOAPHeader object. This operation is supported on both SOAP 1.1 and SOAP 1.2 header.


Parameters:
supportedSoapUris - an array of the URIs of SOAP versions supported.
Returns:
the new SOAPHeaderElement object that was inserted into this SOAPHeader object
Throws:
SOAPException - if a SOAP error occurs.

Since:
SAAJ 1.3


addUpgradeHeaderElement

SOAPHeaderElement addUpgradeHeaderElement(java.lang.String supportedSoapUri)
                                          throws SOAPException

Creates a new Upgrade SOAPHeaderElement object initialized with the specified supported SOAP URI and adds it to this SOAPHeader object. This operation is supported on both SOAP 1.1 and SOAP 1.2 header.


Parameters:
supportedSoapUri - the URI of SOAP the version that is supported.
Returns:
the new SOAPHeaderElement object that was inserted into this SOAPHeader object
Throws:
SOAPException - if a SOAP error occurs.

Since:
SAAJ 1.3
Rationale: New methods added to SOAPHeader to support SOAP 1.2 Message Constructs


  C002

javax.xml.soap
Interface SOAPHeaderElement

All Superinterfaces:
org.w3c.dom.Element, org.w3c.dom.Node, SOAPElement

Method Summary
 boolean getRelay()
          Returns the boolean value of the relay attribute for this SOAPHeaderElement
 java.lang.String getRole()
          Returns the value of the Role attribute of this SOAPHeaderElement.
 void setRelay(boolean relay)
          Sets the relay attribute for this SOAPHeaderElement to be either true or false.
 void setRole(java.lang.String uri)
          Sets the Role associated with this SOAPHeaderElement object to the specified Role.


Method Detail


setRole

void setRole(java.lang.String uri)
             throws SOAPException
Sets the Role associated with this SOAPHeaderElement object to the specified Role.

Parameters:
uri - - the URI of the Role
Throws:
SOAPException - if there is an error in setting the role
java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Role.
Since:
SAAJ 1.3

getRole

java.lang.String getRole()
Returns the value of the Role attribute of this SOAPHeaderElement.


Returns:
a String giving the URI of the Role
Throws:
java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Role.
Since:
SAAJ 1.3

setRelay


void setRelay(boolean relay) throws SOAPException
Sets the relay attribute for this SOAPHeaderElement to be either true or false.

The SOAP relay attribute is set to true to indicate that the SOAP header block must be relayed by any node that is targeted by the header block but not actually process it. This attribute is ignored on header blocks whose mustUnderstand attribute is set to true or that are targeted at the ultimate receiver (which is the default). The default value of this attribute is false.


Parameters:
relay - the new value of the relay attribute
Throws:
SOAPException  - if there is a problem setting the relay attribute.
java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Relay attribute.
Since:
SAAJ 1.3
See Also:
setMustUnderstand(boolean), getRelay()

getRelay


boolean getRelay()
Returns the boolean value of the relay attribute for this SOAPHeaderElement


Returns:
true if the relay attribute is turned on; false otherwise
Throws:
java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of  Relay attribute.
Since:
SAAJ 1.3
See Also:
getMustUnderstand(), setRelay(boolean)
Rationale :  New methods added to SOAPHeaderElement to support SOAP 1.2 Message Constructs


C003

javax.xml.soap
Interface SOAPConstants

Field Summary
static java.lang.String DEFAULT_SOAP_PROTOCOL
          The default protocol: SOAP 1.1 for backwards compatibility.
static java.lang.String DYNAMIC_SOAP_PROTOCOL
          Used to create MessageFactory instances that create SOAPMessages whose concrete type is based on the Content-Type MIME header passed to the createMessage method.
static java.lang.String SOAP_ENV_PREFIX
          The default namespace prefix for http://www.w3.org/2003/05/soap-envelope
static java.lang.String SOAP_1_1_CONTENT_TYPE
          The media type of the Content-Type MIME header in SOAP 1.1.
static java.lang.String SOAP_1_1_PROTOCOL
          Used to create MessageFactory instances that create SOAPMessages whose behavior supports the SOAP 1.1 specification.
static java.lang.String SOAP_1_2_CONTENT_TYPE
          The media type of the Content-Type MIME header in SOAP 1.2.
static java.lang.String SOAP_1_2_PROTOCOL
          Used to create MessageFactory instances that create SOAPMessages whose behavior supports the SOAP 1.2 specification
static java.lang.String URI_NS_SOAP_1_1_ENVELOPE
          The namespace identifier for the SOAP 1.1 envelope.
static java.lang.String URI_NS_SOAP_1_2_ENCODING
          The namespace identifier for the SOAP 1.2 encoding.
static java.lang.String URI_NS_SOAP_1_2_ENVELOPE
          The namespace identifier for the SOAP 1.2 envelope.
static java.lang.String URI_SOAP_1_2_ROLE_NEXT
          The URI identifying the next application processing a SOAP request as the intended role for a SOAP 1.2 header entry (see section 2.2 of part 1 of the SOAP 1.2 specification).
static java.lang.String URI_SOAP_1_2_ROLE_NONE
          The URI specifying the role None in SOAP 1.2.
static java.lang.String URI_SOAP_1_2_ROLE_ULTIMATE_RECEIVER
          The URI identifying the ultimate receiver of the SOAP 1.2 message.
 
Field Detail

DYNAMIC_SOAP_PROTOCOL

static final java.lang.String DYNAMIC_SOAP_PROTOCOL
Used to create MessageFactory instances that create SOAPMessages whose concrete type is based on the content-type MIME header passed to the createMessage method. If no content-type header is passed then the createMessage may throw an IllegalArgumentException or, in the case of the no argument version of createMessage, an UnsupportedOperationException.
Since:
SAAJ 1.3
See Also:
Constant Field Values

SOAP_1_1_PROTOCOL

static final java.lang.String SOAP_1_1_PROTOCOL
Used to create MessageFactory instances that create SOAPMessages whose behavior supports the SOAP 1.1 specification.
Since:
SAAJ 1.3
See Also:
Constant Field Values

SOAP_1_2_PROTOCOL

static final java.lang.String SOAP_1_2_PROTOCOL
Used to create MessageFactory instances that create SOAPMessages whose behavior supports the SOAP 1.2 specification
Since:
SAAJ 1.3
See Also:
Constant Field Values

DEFAULT_SOAP_PROTOCOL

static final java.lang.String DEFAULT_SOAP_PROTOCOL
The default protocol: SOAP 1.1 for backwards compatibility.
Since:
SAAJ 1.3
See Also:
Constant Field Values

URI_NS_SOAP_1_1_ENVELOPE

static final java.lang.String URI_NS_SOAP_1_1_ENVELOPE
The namespace identifier for the SOAP 1.1 envelope.
Since:
SAAJ 1.3
See Also:
Constant Field Values


URI_NS_SOAP_1_2_ENVELOPE

static final java.lang.String URI_NS_SOAP_1_2_ENVELOPE
The namespace identifier for the SOAP 1.2 envelope.
Since:
SAAJ 1.3
See Also:
Constant Field Values


URI_NS_SOAP_1_2_ENCODING

static final java.lang.String URI_NS_SOAP_1_2_ENCODING
The namespace identifier for the SOAP 1.2 encoding.
Since:
SAAJ 1.3
See Also:
Constant Field Values

SOAP_1_1_CONTENT_TYPE

static final java.lang.String SOAP_1_1_CONTENT_TYPE
The media type of the Content-Type MIME header in SOAP 1.1.
Since:
SAAJ 1.3
See Also:
Constant Field Values

SOAP_1_2_CONTENT_TYPE

static final java.lang.String SOAP_1_2_CONTENT_TYPE
The media type of the Content-Type MIME header in SOAP 1.2.
Since:
SAAJ 1.3
See Also:
Constant Field Values

URI_SOAP_1_2_ROLE_NEXT

static final java.lang.String URI_SOAP_1_2_ROLE_NEXT
The URI identifying the next application processing a SOAP request as the intended role for a SOAP 1.2 header entry (see section 2.2 of part 1 of the SOAP 1.2 specification).
Since:
SAAJ 1.3
See Also:
Constant Field Values

URI_SOAP_1_2_ROLE_NONE

static final java.lang.String URI_SOAP_1_2_ROLE_NONE
The URI specifying the role None in SOAP 1.2.
Since:
SAAJ 1.3
See Also:
Constant Field Values

URI_SOAP_1_2_ROLE_ULTIMATE_RECEIVER

static final java.lang.String URI_SOAP_1_2_ROLE_ULTIMATE_RECEIVER
The URI identifying the ultimate receiver of the SOAP 1.2 message.
Since:
SAAJ 1.3
See Also:
Constant Field Values

SOAP_ENV_PREFIX

static final java.lang.String SOAP_ENV_PREFIX
The default namespace prefix for http://www.w3.org/2003/05/soap-envelope
Since:
SAAJ 1.3
See Also:
Constant Field Values


Rationale: All these fields are added new in SOAPConstants as part of providing support for SOAP Version 1.2, and for providing a facility to create SOAP Version aware Factory instances.

URI_NS_SOAP_1_1_ENVELOPE   is the same as the SAAJ 1.2 constant  URI_NS_SOAP_ENVELOPE

 

C004

javax.xml.soap
Interface SOAPFault

All Superinterfaces:
org.w3c.dom.Element, org.w3c.dom.Node, SOAPBodyElement, SOAPElement

Method Summary
 void addFaultReasonText(java.lang.String text, java.util.Locale locale)
          Appends or replaces a Reason Text item containing the specified text message and an xml:lang derived from locale.
 void appendFaultSubcode(javax.xml.namespace.QName subcode)
          Adds a Subcode to the end of the sequence of Subcodes contained by this SOAPFault.
 java.lang.String getFaultNode()
          Returns the optional Node element value for this SOAPFault object.
 java.util.Iterator getFaultReasonLocales()
          Returns an Iterator over a distinct sequence of Locales for which there are associated Reason Text items.
 java.lang.String getFaultReasonText(java.util.Locale locale)
          Returns the Reason Text associated with the given Locale.
 java.util.Iterator getFaultReasonTexts()
          Returns an Iterator over a sequence of String objects containing all of the Reason Text items for this SOAPFault.
 java.lang.String getFaultRole()
          Returns the optional Role element value for this SOAPFault object.
 java.util.Iterator getFaultSubcodes()
          Gets the Subcodes for this SOAPFault as an iterator over QNames.
 void removeAllFaultSubcodes()
          Removes any Subcodes that may be contained by this SOAPFault.
 void setFaultNode(java.lang.String uri)
          Creates or replaces any existing Node element value for this SOAPFault object.
 void setFaultRole(java.lang.String uri)
          Creates or replaces any existing Role element value for this SOAPFault object.
boolean
 hasDetail()
          Returns true if this SOAPFault has a Detail subelement and false otherwise.
 
Method Detail

getFaultSubcodes

java.util.Iterator getFaultSubcodes()
Gets the Subcodes for this SOAPFault as an iterator over QNames.

Returns:
an Iterator that accesses a sequence of QNames. This Iterator should not support the optional remove method. The order in which the Subcodes are returned reflects the hierarchy of Subcodes present in the fault from top to bottom.
Throws:
java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Subcode.
Since:
SAAJ 1.3

removeAllFaultSubcodes

void removeAllFaultSubcodes()
Removes any Subcodes that may be contained by this SOAPFault. Subsequent calls to getFaultSubcodes will return an empty iterator until a call to appendFaultSubcode is made.

Throws:
java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Subcode.
Since:
SAAJ 1.3

appendFaultSubcode

public void appendFaultSubcode(javax.xml.namespace.QName subcode)
                        throws SOAPException
Adds a Subcode to the end of the sequence of Subcodes contained by this SOAPFault. Subcodes, which were introduced in SOAP 1.2, are represented by a recursive sequence of subelements rooted in the mandatory Code subelement of a SOAP Fault.


Parameters:
subcode - a QName containing the Value of the Subcode.
Throws:
SOAPException - if there was an error in setting the Subcode
java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Subcode.
Since:
SAAJ 1.3

getFaultReasonLocales

public java.util.Iterator getFaultReasonLocales()
                                         throws SOAPException
Returns an Iterator over a distinct sequence of Locales for which there are associated Reason Text items. Any of these Locales can be used in a call to getFaultReasonText in order to obtain a localized version of the Reason Text string.


Returns:
an Iterator over a sequence of Locale objects for which there are associated Reason Text items.
Throws:
SOAPException - if there was an error in retrieving the fault Reason locales.
java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Reason.
Since:
SAAJ 1.3

getFaultReasonTexts

public java.util.Iterator getFaultReasonTexts()
                                       throws SOAPException
Returns an Iterator over a sequence of String objects containing all of the Reason Text items for this SOAPFault.


Returns:
an Iterator over env:Fault/env:Reason/env:Text items.
Throws:
SOAPException - if there was an error in retrieving the fault Reason texts.
java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Reason.
Since:
SAAJ 1.3

getFaultReasonText

public java.lang.String getFaultReasonText(java.util.Locale locale)
                                    throws SOAPException
Returns the Reason Text associated with the given Locale. If more than one such Reason Text exists the first matching Text is returned


Parameters:
locale - -- the Locale for which a localized Reason Text is desired
Returns:
the Reason Text associated with locale
Throws:
SOAPException - if there was an error in retrieving the fault Reason text for the specified locale .
java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Reason.
Since:
SAAJ 1.3
See Also:
getFaultString()


addFaultReasonText

public void addFaultReasonText(java.lang.String text,
                               java.util.Locale locale)
                        throws SOAPException
Appends or replaces a Reason Text item containing the specified text message and an xml:lang derived from locale. If a Reason Text item with this xml:lang already exists its text value will be replaced with text. The locale parameter should not be null

Code sample: 

 SOAPFault fault = ...;
 fault.addFaultReasonText("Version Mismatch", Locale.ENGLISH);


Parameters:
text - -- reason message string
locale - -- Locale object representing the locale of the message
Throws:
SOAPException - if there was an error in adding the Reason text or the locale passed was null.
java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Reason.
Since:
SAAJ 1.3

getFaultNode

java.lang.String getFaultNode()
Returns the optional Node element value for this SOAPFault object. The Node element is optional in SOAP 1.2.

Returns:
Content of the env:Fault/env:Node element as a String or null if none
Throws:
java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Node.
Since:
SAAJ 1.3

setFaultNode

public void setFaultNode(java.lang.String uri)
                  throws SOAPException
Creates or replaces any existing Node element value for this SOAPFault object. The Node element is optional in SOAP 1.2.


Throws:
SOAPException - if there was an error in setting the Node for this SOAPFault object.
java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Node.
Since:
SAAJ 1.3

getFaultRole

public java.lang.String getFaultRole()
Returns the optional Role element value for this SOAPFault object. The Role element is optional in SOAP 1.2.


Returns:
Content of the env:Fault/env:Role element as a String or null if none
Throws:
java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Role.
Since:
SAAJ 1.3

setFaultRole

public void setFaultRole(java.lang.String uri)
                  throws SOAPException
Creates or replaces any existing Role element value for this SOAPFault object. The Role element is optional in SOAP 1.2.


Parameters:
uri - - the URI of the Role
Throws:
SOAPException - if there was an error in setting the Role for this SOAPFault object.
java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Role.
Since:
SAAJ 1.3


hasDetail

boolean hasDetail()
Returns true if this SOAPFault has a Detail subelement and false otherwise. Equivalent to (getDetail()!=null).


Returns:
true if this SOAPFault has a Detail subelement and false otherwise.
Since:
SAAJ 1.3

Rationale: New methods added to SOAPFault to support SOAP 1.2 Message Constructs


C005

javax.xml.soap
Class MessageFactory

java.lang.Object
  extended by javax.xml.soap.MessageFactory

Method Summary
static MessageFactory newInstance(java.lang.String protocol)
          Creates a new MessageFactory object that is an instance of the specified implementation.


Method Detail

newInstance

public static MessageFactory newInstance(java.lang.String protocol)
                                  throws SOAPException
Creates a new MessageFactory object that is an instance of the specified implementation. May be a dynamic message factory, a SOAP 1.1 message factory, or a SOAP 1.2 message factory. A dynamic message factory creates messages based on the MIME headers specified as arguments to the createMessage method.   This method uses the  SAAJMetaFactory to locate the implementation class and create the MessageFactory instance.


Parameters:
protocol - a string constant representing the class of the specified message factory implementation. May be either DYNAMIC_SOAP_PROTOCOL, DEFAULT_SOAP_PROTOCOL (which is the same as) SOAP_1_1_PROTOCOL, or SOAP_1_2_PROTOCOL.
Returns:
a new instance of a MessageFactory
Throws:
SOAPException - if there was an error in creating the specified implementation of MessageFactory.
See Also:
SAAJMetaFactory
Since:
SAAJ 1.3
Rationale : Facilitate creation of SOAP Version aware MessageFactory



C006

javax.xml.soap
Class SOAPFactory

java.lang.Object
  extended by javax.xml.soap.SOAPFactory

Method Summary
static SOAPFactory newInstance(java.lang.String protocol)
          Creates a new SOAPFactory object that is an instance of the specified implementation.

Method Detail

newInstance

public static SOAPFactory newInstance(java.lang.String protocol) throws SOAPException
Creates a new SOAPFactory object that is an instance of the specified implementation,  this method  uses the SAAJMetaFactory to locate the implementation class and create the SOAPFactory instance.


Parameters:
protocol - a string constant representing the protocol of the specified SOAP factory implementation. May be either  DYNAMIC_SOAP_PROTOCOL, DEFAULT_SOAP_PROTOCOL (which is the same as) SOAP_1_1_PROTOCOL, or SOAP_1_2_PROTOCOL.

Returns:
a new instance of a SOAPFactory
Throws:
SOAPException - if there was an error creating the specified SOAPFactory
See Also:
SAAJMetaFactory
Since:
SAAJ 1.3


Rationale : Facilitate creation of SOAP Version aware SOAPFactory



C007

javax.xml.soap
Interface SOAPConstants




Field Summary
static javax.xml.namespace.QName SOAP_DATAENCODINGUNKNOWN_FAULT
          SOAP 1.2 DataEncodingUnknown Fault
static javax.xml.namespace.QName SOAP_MUSTUNDERSTAND_FAULT
          SOAP 1.2 MustUnderstand Fault
static javax.xml.namespace.QName SOAP_RECEIVER_FAULT
          SOAP 1.2 Receiver Fault
static javax.xml.namespace.QName SOAP_SENDER_FAULT
          SOAP 1.2 Sender Fault
static javax.xml.namespace.QName SOAP_VERSIONMISMATCH_FAULT
          SOAP 1.2 VersionMismatch Fault


Field Detail

SOAP_VERSIONMISMATCH_FAULT

static final javax.xml.namespace.QName SOAP_VERSIONMISMATCH_FAULT
SOAP 1.2 VersionMismatch Fault

Since:
SAAJ 1.3

SOAP_MUSTUNDERSTAND_FAULT

static final javax.xml.namespace.QName SOAP_MUSTUNDERSTAND_FAULT
SOAP 1.2 MustUnderstand Fault

Since:
SAAJ 1.3

SOAP_DATAENCODINGUNKNOWN_FAULT

static final javax.xml.namespace.QName SOAP_DATAENCODINGUNKNOWN_FAULT
SOAP 1.2 DataEncodingUnknown Fault

Since:
SAAJ 1.3

SOAP_SENDER_FAULT

static final javax.xml.namespace.QName SOAP_SENDER_FAULT
SOAP 1.2 Sender Fault

Since:
SAAJ 1.3

SOAP_RECEIVER_FAULT

static final javax.xml.namespace.QName SOAP_RECEIVER_FAULT
SOAP 1.2 Receiver Fault

Since:
SAAJ 1.3


Rationale:  QName constants for the SOAP 1.2 fault codes defined in env:faultCodeEnum




7) Proposed Changes for Adding SPI for creation of Factory instances

C008

javax.xml.soap
Class SAAJMetaFactory

java.lang.Object
  extended by javax.xml.soap.SAAJMetaFactory
public abstract class SAAJMetaFactory
extends java.lang.Object


The access point for the implementation classes of the factories defined in the SAAJ API. All of the newInstance methods defined on factories in SAAJ 1.3 defer to instances of this class to do the actual object creation. The implement ions of newInstance() methods (in SOAPFactory and MessageFactory) that existed in SAAJ 1.2 have been updated to also delegate to the SAAJMetaFactory when the SAAJ 1.2 defined lookup fails to locate the Factory implementation class name.

 SAAJMetaFactory is a service provider interface. There are no public methods on this class.

Since:
SAAJ 1.3

Constructor Summary
protected SAAJMetaFactory()
           
 
Method Summary
(package private) static SAAJMetaFactory getInstance()
          Creates a new instance of a concrete SAAJMetaFactory object.
protected abstract  MessageFactory newMessageFactory(java.lang.String protocol)
          Creates a MessageFactory object for the given String protocol.
protected abstract  SOAPFactory newSOAPFactory(java.lang.String protocol)
          Creates a SOAPFactory object for the given String protocol.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SAAJMetaFactory

protected SAAJMetaFactory()
Method Detail

getInstance

static synchronized SAAJMetaFactory getInstance() throws SOAPException

Creates a new instance of a concrete SAAJMetaFactory object. The SAAJMetaFactory is an SPI, it pulls the creation of the other factories together into a single place. Changing out the SAAJMetaFactory has the effect of changing out the entire SAAJ implementation. Service providers provide the name of their SAAJMetaFactory implementation. This method uses the following ordered lookup procedure to determine the SAAJMetaFactory implementation class to load:


Returns:
a concrete SAAJMetaFactory object
Throws:
SOAPException - if there is an error in creating the SAAJMetaFactory

newMessageFactory

protected abstract MessageFactory newMessageFactory(java.lang.String protocol)
                                             throws SOAPException
Creates a MessageFactory object for the given String protocol.
Parameters:
protocol - a String indicating the protocol
Throws:
SOAPException - if there is an error in creating the MessageFactory
See Also:
SOAPConstants.SOAP_1_1_PROTOCOL, SOAPConstants.SOAP_1_2_PROTOCOL, SOAPConstants.DYNAMIC_SOAP_PROTOCOL

newSOAPFactory

protected abstract SOAPFactory newSOAPFactory(java.lang.String protocol)
                                       throws SOAPException
Creates a SOAPFactory object for the given String protocol. 
Parameters:
protocol - a String indicating the protocol
Throws:
SOAPException - if there is an error in creating the SOAPFactory
See Also:
SOAPConstants.SOAP_1_1_PROTOCOL, SOAPConstants.SOAP_1_2_PROTOCOL, SOAPConstants.DYNAMIC_SOAP_PROTOCOL
Rationale : This is the proposed new SPI  in SAAJ 1.3 for factoring out Factory creation into a single place.Changing out the SAAJMetaFactory has the effect of changing out the entire SAAJ implementation


8) Proposed  Addition of SAAJResult


C009

javax.xml.soap
Class SAAJResult

java.lang.Object
  extended by javax.xml.transform.dom.DOMResult
      extended by javax.xml.soap.SAAJResult
All Implemented Interfaces:
javax.xml.transform.Result
public class SAAJResult
extends javax.xml.transform.dom.DOMResult

Acts as a holder for the results of a JAXP transformation or a JAXB marshalling, in the form of a SAAJ tree. These results should be accessed by using the getResult() method. The DOMResult.getNode() method should be avoided in almost all cases.

Since:
SAAJ 1.3

Field Summary
 
Fields inherited from class javax.xml.transform.dom.DOMResult
FEATURE
 
Fields inherited from interface javax.xml.transform.Result
PI_DISABLE_OUTPUT_ESCAPING, PI_ENABLE_OUTPUT_ESCAPING
 
Constructor Summary
SAAJResult()
          Creates a SAAJResult that will present results in the form of a SAAJ tree that supports the default (SOAP 1.1) protocol.
SAAJResult(SOAPElement rootNode)
          Creates a SAAJResult that will write the results as a child node of the SOAPElement specified.
SAAJResult(SOAPMessage message)
           Creates a SAAJResult that will write the results into the SOAPPart of the supplied  SOAPMessage.
SAAJResult(java.lang.String protocol)
          Creates a SAAJResult that will present results in the form of a SAAJ tree that supports the specified protocol.
 
Method Summary
 Node getResult()
           
 
Methods inherited from class javax.xml.transform.dom.DOMResult
getNextSibling, getNode, getSystemId, setNextSibling, setNode, setSystemId
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SAAJResult

public SAAJResult()
           throws SOAPException
Creates a SAAJResult that will present results in the form of a SAAJ tree that supports the default (SOAP 1.1) protocol.

This kind of SAAJResult is meant for use in situations where the results will be used as a parameter to a method that takes a parameter whose type, such as SOAPElement, is drawn from the SAAJ API. When used in a transformation, the results are populated into the SOAPPart of a SOAPMessage that is created internally. The  SOAPPart returned by DOMResult.getNode() is not guaranteed to be well-formed.

Throws:
SOAPException - if there is a problem creating a SOAPMessage
Since:
SAAJ 1.3

SAAJResult

public SAAJResult(java.lang.String protocol)
           throws SOAPException
Creates a SAAJResult that will present results in the form of a SAAJ tree that supports the specified protocol. The DYNAMIC_SOAP_PROTOCOL is ambiguous in this context and will cause this constructor to throw an UnsupportedOperationException.

This kind of SAAJResult is meant for use in situations where the results will be used as a parameter to a method that takes a parameter whose type, such as SOAPElement, is drawn from the SAAJ API. When used in a transformation the results are populated into the SOAPPart of a SOAPMessage that is created internally. The  SOAPPart returned by DOMResult.getNode() is not guaranteed to be well-formed.

Parameters:
protocol - - the name of the SOAP protocol that the resulting SAAJ tree should support
Throws:
SOAPException - if a SOAPMessage supporting the specified protocol cannot be created
Since:
SAAJ 1.3

SAAJResult

public SAAJResult(SOAPMessage message)
Creates a SAAJResult that will write the results into an existing SOAPMessage. In the normal case these results will be written using DOM APIs and, as a result, the finished SOAPPart will not be guaranteed to be well-formed unless the data used to create it is also well formed.  When used in a transformation the validity of the SOAPMessage after transformation can be guaranteed only be means outside the SAAJ specification.
Parameters:
message - - the message whose SOAPPart will be populated as a result of some transformation or marshalling operation
Since:
SAAJ 1.3

SAAJResult

public SAAJResult(SOAPElement rootNode)
Creates a SAAJResult that will write the results as a child node of the SOAPElement specified. In the normal case these results will be written using DOM APIs and as a result may invalidate the structure of the SAAJ tree. This kind of SAAJResult should only be used when the validity of the incoming data can be guaranteed by means outside of the SAAJ specification.
Parameters:
rootNode - - the root to which the results will be appended
Since:
SAAJ 1.3
Method Detail

getResult

public Node getResult()
Returns:
the resulting Tree that was created under the specified root Node.
Since:
SAAJ 1.3
Rationale : Acts as a holder for the results of a JAXP transformation or a JAXB marshalling, in the form of a SAAJ tree. Introduction of this class provides ease of use for the SAAJ developer since he need not  deal with the usual DOM results.


9) Proposed  Addition of  Overloaded Methods which Accept QName Instead of Name


C010

javax.xml.soap
Interface Detail

All Superinterfaces:
org.w3c.dom.Element, org.w3c.dom.Node, SOAPElement, SOAPFaultElement

Method Summary
 DetailEntry addDetailEntry(javax.xml.namespace.QName qname)
          Creates a new DetailEntry object with the given QName and adds it to this Detail object.
 
Method Detail

addDetailEntry

DetailEntry addDetailEntry(javax.xml.namespace.QName qname)
                           throws SOAPException
Creates a new DetailEntry object with the given QName and adds it to this Detail object. This method is the preferred over the one using Name.

Parameters:
qname - a QName object identifying the new DetailEntry object
Throws:
SOAPException - thrown when there is a problem in adding a DetailEntry object to this Detail object.
Since:
SAAJ 1.3
See Also:
addDetailEntry(Name name)

Rationale : QName support



C011


javax.xml.soap
Interface SOAPBody

All Superinterfaces:
org.w3c.dom.Element, org.w3c.dom.Node, SOAPElement
 
Method Summary
 SOAPBodyElement addBodyElement(javax.xml.namespace.QName qname)
          Creates a new SOAPBodyElement object with the specified QName and adds it to this SOAPBody object.
 SOAPFault addFault(javax.xml.namespace.QName faultCode, java.lang.String faultString)
          Creates a new SOAPFault object and adds it to this SOAPBody object.
 SOAPFault addFault(javax.xml.namespace.QName faultCode, java.lang.String faultString, java.util.Locale locale)
          Creates a new SOAPFault object and adds it to this SOAPBody object.


Method Detail


addFault

SOAPFault addFault(javax.xml.namespace.QName faultCode,
                   java.lang.String faultString,
                   java.util.Locale locale)
                   throws SOAPException
Creates a new SOAPFault object and adds it to this SOAPBody object. The type of the SOAPFault will be a SOAP 1.1 or a SOAP 1.2 SOAPFault depending on the protocol specified while creating the MessageFactory instance.

For SOAP 1.2 the faultCode parameter is the value of the Fault/Code/Value element and the faultString parameter is the value of the Fault/Reason element. For SOAP 1.1 the faultCode parameter is the value of the faultcode element and the faultString parameter is the value of the faultstring element.

A SOAPBody may contain at most one SOAPFault child element.


Parameters:
faultCode - a QName object giving the fault code to be set; must be one of the fault codes defined in a SOAP 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.3
See Also:
SOAPFault.setFaultCode(javax.xml.soap.Name), SOAPFault.setFaultString(java.lang.String), addFault(Name faultCode, String faultString, Locale locale)

addFault

SOAPFault addFault(javax.xml.namespace.QName faultCode,
                   java.lang.String faultString)
                   throws SOAPException
Creates a new SOAPFault object and adds it to this SOAPBody object. The type of the SOAPFault will be a SOAP 1.1 or a SOAP 1.2 SOAPFault depending on the protocol specified while creating the MessageFactory instance.

For SOAP 1.2 the faultCode parameter is the value of the Fault/Code/Value element and the faultString parameter is the value of the Fault/Reason/Text element. For SOAP 1.1 the faultCode parameter is the value of the faultcode element and the faultString parameter is the value of the faultstring element.

In case of a SOAP 1.2 fault, the default value for the mandatory xml:lang attribute on the Fault/Reason/Text element will be set to java.util.Locale.getDefault()

A SOAPBody may contain at most one SOAPFault child element


Parameters:
faultCode - a QName object giving the fault code to be set; must be one of the fault codes defined in a SOAP 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.3
See Also:
SOAPFault.setFaultCode(javax.xml.soap.Name), SOAPFault.setFaultString(java.lang.String), addFault(Name faultCode, String faultString)

addBodyElement

SOAPBodyElement addBodyElement(javax.xml.namespace.QName qname)
                               throws SOAPException
Creates a new SOAPBodyElement object with the specified QName and adds it to this SOAPBody object.

Parameters:
qname - a QName object with the qname for the new SOAPBodyElement object
Returns:
the new SOAPBodyElement object
Throws:
SOAPException - if a SOAP error occurs
Since:
SAAJ 1.3
See Also:
addBodyElement(Name)

Rationale : QName support


C012

javax.xml.soap
Interface SOAPElement

All Superinterfaces:
org.w3c.dom.Element, org.w3c.dom.Node
All Known Subinterfaces:
Detail, DetailEntry, SOAPBody, SOAPBodyElement, SOAPEnvelope, SOAPFault, SOAPFaultElement, SOAPHeader, SOAPHeaderElement
Method Summary
 SOAPElement addAttribute(javax.xml.namespace.QName qname, java.lang.String value)
          Adds an attribute with the specified name and value to this SOAPElement object.
 SOAPElement addChildElement(javax.xml.namespace.QName qname)
          Creates a new SOAPElement object initialized with the given QName object and adds the new element to this SOAPElement object.
 javax.xml.namespace.QName createQName(java.lang.String localName, java.lang.String prefix)
          Creates a QName whose namespace URI is the one associated with the parameter, prefix, in the context of this SOAPElement.
 java.lang.String getAttributeValue(javax.xml.namespace.QName qname)
          Returns the value of the attribute with the specified qname.
 java.util.Iterator getChildElements(javax.xml.namespace.QName qname)
          Returns an Iterator over all the immediate child Nodes of this element with the specified qname.
 javax.xml.namespace.QName getElementQName()
          Returns the qname of this SOAPElement object.
 boolean removeAttribute(javax.xml.namespace.QName qname)
          Removes the attribute with the specified qname.
 void setElementQName(javax.xml.namespace.QName newName)
          Changes the name of this Element to newName if possible.
  java.util.Iterator  getAllAttributesAsQNames()
          Returns an Iterator over all of the attributes in this SOAPElement as QName objects.
 

Method Detail

addChildElement

public SOAPElement addChildElement(javax.xml.namespace.QName qname)
                            throws SOAPException
Creates a new SOAPElement object initialized with the given QName object and adds the new element to this SOAPElement object. The namespace, localname and prefix of the new SOAPElement are all taken from the qname argument.


Parameters:
qname - a QName object with the XML name for the new element
Returns:
the new SOAPElement object that was created
Throws:
SOAPException - if there is an error in creating the SOAPElement object
Since:
SAAJ 1.3
See Also:
addChildElement(Name)

addAttribute

SOAPElement addAttribute(javax.xml.namespace.QName qname,
                         java.lang.String value)
                         throws SOAPException
Adds an attribute with the specified name and value to this SOAPElement object.

Parameters:
qname - a QName object with the name of the attribute
value - a String giving the value of the attribute
Returns:
the SOAPElement object into which the attribute was inserted
Throws:
SOAPException - if there is an error in creating the Attribute, or it is invalid to set an attribute with QName qname on this SOAPElement.
Since:
SAAJ 1.3
See Also:
addAttribute(Name, String)

getAttributeValue

java.lang.String getAttributeValue(javax.xml.namespace.QName qname)
Returns the value of the attribute with the specified qname.

Parameters:
qname - a QName object with the qname of the attribute
Returns:
a String giving the value of the specified attribute, Null if there is no such attribute
Since:
SAAJ 1.3
See Also:
getAttributeValue(Name)

createQName

javax.xml.namespace.QName createQName(java.lang.String localName,
                                      java.lang.String prefix)
                                      throws SOAPException
Creates a QName whose namespace URI is the one associated with the parameter, prefix, in the context of this SOAPElement. The remaining elements of the new QName are taken directly from the parameters, localName and prefix.


Parameters:
localName - a String containing the local part of the name.
prefix - a String containing the prefix for the name.
Returns:
a QName with the specified localName and prefix, and with a namespace that is associated with the prefix in the context of this SOAPElement. This namespace will be the same as the one that would be returned by getNamespaceURI(String) if it were given prefix as it's parameter.
Throws:
SOAPException - if the QName cannot be created.
Since:
SAAJ 1.3

getElementQName

javax.xml.namespace.QName getElementQName()
Returns the qname of this SOAPElement object.

Returns:
a QName object with the qname of this SOAPElement object
Since:
SAAJ 1.3
See Also:
getElementName()

setElementQName

public SOAPElement setElementQName(javax.xml.namespace.QName newName)
                            throws SOAPException
Changes the name of this Element to newName if possible. SOAP Defined elements such as SOAPEnvelope, SOAPHeader, SOAPBody etc. cannot have their names changed using this method. Any attempt to do so will result in a SOAPException being thrown.

Callers should not rely on the element instance being renamed as is. Implementations could end up copying the content of the SOAPElement to a renamed instance.


Parameters:
newName - the new name for the Element.
Returns:
The renamed Node
Throws:
SOAPException - if changing the name of this Element is not allowed.
Since:
SAAJ 1.3

removeAttribute

boolean removeAttribute(javax.xml.namespace.QName qname)
Removes the attribute with the specified qname.

Parameters:
qname - the QName object with the qname of the attribute to be removed
Returns:
true if the attribute was removed successfully; false if it was not
Since:
SAAJ 1.3
See Also:
removeAttribute(Name)

getAllAttributesAsQNames

java.util.Iterator getAllAttributesAsQNames()
Returns an Iterator over all of the attributes in this SOAPElement as QName objects. The iterator can be used to get the attribute QName, which can then be passed to the method getAttributeValue to retrieve the value of each attribute.

Returns:
an iterator over the QNames of the attributes
Since:
SAAJ 1.3
See Also:
getAllAttributes()


getChildElements

java.util.Iterator getChildElements(javax.xml.namespace.QName qname)
Returns an Iterator over all the immediate child Nodes of this element with the specified qname. 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.soap for more details.


Parameters:
qname - a QName object with the qname of the child elements to be returned
Returns:
an Iterator object over all the elements in this SOAPElement object with the specified qname
Since:
SAAJ 1.3
See Also:

getChildElements(Name)

Rationale : QName support



C013


javax.xml.soap
Interface SOAPFault

All Superinterfaces:
org.w3c.dom.Element, org.w3c.dom.Node, SOAPBodyElement, SOAPElement
Method Summary
 javax.xml.namespace.QName getFaultCodeAsQName()
          Gets the fault code for this SOAPFault object as a QName object.
 void setFaultCode(javax.xml.namespace.QName faultCodeQName)
          Sets this SOAPFault object with the given fault code.

Method Detail

getFaultCodeAsQName

javax.xml.namespace.QName getFaultCodeAsQName()
Gets the fault code for this SOAPFault object as a QName object.

Returns:
a QName representing the faultcode
Since:
SAAJ 1.3
See Also:
setFaultCode(QName)


setFaultCode

void setFaultCode(javax.xml.namespace.QName faultCodeQName)
                  throws