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 SOAPException
Sets this SOAPFault object with the given fault code. It is preferable to use this method over setFaultCode(Name).


Parameters:
faultCodeQName - a QName 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.3
See Also:
getFaultCodeAsQName(), setFaultCode(Name), getFaultCodeAsQName()

Rationale: QName support




C014


javax.xml.soap
Class SOAPFactory

java.lang.Object
extended by javax.xml.soap.SOAPFactory
Method Summary
  SOAPElement createElement(javax.xml.namespace.QName qname)
          Creates a SOAPElement object initialized with the given QName object.
 

Method Detail

createElement

public  SOAPElement createElement(javax.xml.namespace.QName qname) throws SOAPException
Creates a SOAPElement object initialized with the given QName object. The concrete type of the return value will depend on the name given to the new SOAPElement. For instance, a new SOAPElement with the name "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a SOAPEnvelope that supports SOAP 1.2 behavior to be created.
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:
createElement(Name)


Rationale : QName support


C015


javax.xml.soap
Interface SOAPHeader

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

Method Summary
 SOAPHeaderElement addHeaderElement(javax.xml.namespace.QName qname)
          Creates a new SOAPHeaderElement object initialized with the specified qname and adds it to this SOAPHeader object.
Method Detail

addHeaderElement

SOAPHeaderElement addHeaderElement(javax.xml.namespace.QName qname)
throws SOAPException
Creates a new SOAPHeaderElement object initialized with the specified qname and adds it to this SOAPHeader object.

Parameters:
qname - a QName object with the qname of the new SOAPHeaderElement object
Returns:
the new SOAPHeaderElement object that was inserted into this SOAPHeader object
Throws:
SOAPException - if a SOAP error occurs
Since:
SAAJ 1.3
See Also:
addHeaderElement(Name)

Rationale: QName support


10) Proposed Changes to Clarify and Correct the Wording of JavaDocs and Specification


C016

javax.xml.soap
Class MessageFactory

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

public abstract class MessageFactory
extends java.lang.Object

A factory for creating SOAPMessage objects.

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

       MessageFactory mf = MessageFactory.newInstance();
MessageFactory mf12 = MessageFactory.newInstance(SOAPConstants.SOAP_1_2_PROTOCOL);
A standalone client (a client that is not running in a container) can use the newInstance method to create a MessageFactory object.

All MessageFactory objects, regardless of how they are created, will produce SOAPMessage objects that have the following elements by default:

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.
In some cases, specialized MessageFactory objects may be obtained that produce messages prepopulated with additional entries in the SOAPHeader object and the SOAPBody object. The content of a new SOAPMessage object depends on which of the two MessageFactory methods is used to create it.




C017

javax.xml.soap
Class MessageFactory

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

newInstance

public static MessageFactory newInstance()
throws SOAPException

Creates a new MessageFactory object that is an instance of the default implementation (SOAP 1.1), This method uses the following ordered lookup procedure to determine the MessageFactory implementation class to load:
  • Use the javax.xml.soap.MessageFactory system property.
  • Use the properties file "lib/jaxm.properties" in the JRE directory. This configuration file is in standard java.util.Properties format and contains the fully qualified name of the implementation class with the key being the system property defined above.
  • Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API will look for a classname in the file META-INF/services/javax.xml.soap.MessageFactory in jars available to the runtime.
  • Use the SAAJMetaFactory instance to locate the MessageFactory implementation class.




Returns:
a new instance of a MessageFactory
Throws:
SOAPException - if there was an error in creating the default implementation of the MessageFactory.
See Also:
SAAJMetaFactory

createMessage

public abstract SOAPMessage createMessage()
throws SOAPException
Creates a new SOAPMessage object with the default SOAPPart, SOAPEnvelope, SOAPBody, and SOAPHeader objects. Profile-specific message factories can choose to prepopulate the SOAPMessage object with profile-specific headers.

Content can be added to this message's SOAPPart object, and the message can be sent "as is" when a message containing only a SOAP part is sufficient. Otherwise, the SOAPMessage object needs to create one or more AttachmentPart objects and add them to itself. Any content that is not in XML format must be in an AttachmentPart object.

Returns:
a new SOAPMessage object
Throws:
SOAPException - if a SOAP error occurs
java.lang.UnsupportedOperationException - if the protocol of this MessageFactory instance is DYNAMIC_SOAP_PROTOCOL.

createMessage

public abstract SOAPMessage createMessage(MimeHeaders headers,
java.io.InputStream in)
throws java.io.IOException,
SOAPException
Internalizes the contents of the given InputStream object into a new SOAPMessage object and returns the SOAPMessage object.
Parameters:
in - the InputStream object that contains the data for a message
headers - the transport-specific headers passed to the message in a transport-independent fashion for creation of the message
Returns:
a new SOAPMessage object containing the data from the given InputStream object
Throws:
java.io.IOException - if there is a problem in reading data from the input stream
SOAPException - may be thrown if the message is invalid
java.lang.IllegalArgumentException - if the MessageFactory requires one or more MIME headers to be present in the headers parameter and they are missing. MessageFactory implementations for SOAP_1_1_PROTOCOL or SOAP_1_2_PROTOCOL must not throw IllegalArgumentException for this reason.




C018

javax.xml.soap
Interface SOAPBody

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

addFault

SOAPFault addFault()throws 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. 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.

A SOAPBody may contain at most one SOAPFault child element.


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

addFault

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

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 version of  SOAP 1.1   specification in use 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

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 set to the faultcode parameter and a faultstring set to faultstring. 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 Name object giving the fault code to be set; must be one of the fault codes defined in  the version of  SOAP
        1.1 specification in use 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)


getFault

SOAPFault getFault()
Returns the SOAPFault object in this SOAPBody object.


Returns:
the SOAPFault object in this SOAPBody object if present, null otherwise.



C019


javax.xml.soap
Class SOAPFactory

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

Method Detail

createElement

public abstract SOAPElement createElement(Name name) throws SOAPException
Creates a SOAPElement object initialized with the given Name object. The concrete type of the return value will depend on the name given to the new SOAPElement. For instance, a new SOAPElement with the name "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a SOAPEnvelope that supports SOAP 1.2 behavior to be created.
Parameters:
name - a Name 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
See Also:
createElement(javax.xml.namespace.QName)

createElement

public abstract SOAPElement createElement(java.lang.String localName,
java.lang.String prefix,
java.lang.String uri)
throws SOAPException
Creates a new SOAPElement object with the given local name, prefix and uri. The concrete type of the return value will depend on the name given to the new SOAPElement. For instance, a new SOAPElement with the name "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a SOAPEnvelope that supports SOAP 1.2 behavior to be created.
Parameters:
localName - a String giving the local name for the new element
prefix - the prefix for this SOAPElement
uri - a String giving the URI of the namespace to which the new element belongs
Throws:
SOAPException - if there is an error in creating the SOAPElement object

newInstance

public static SOAPFactory newInstance() throws SOAPException

Creates a new instance of SOAPFactory object that is an instance of the default implementation (SOAP 1.1),This method uses the following ordered lookup procedure to determine the SOAPFactory implementation class to load:


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



createDetail

public abstract Detail createDetail()
throws SOAPException
Creates a new Detail object which serves as a container for DetailEntry objects.

This factory method creates Detail objects for use in situations where it is not practical to use the SOAPFault abstraction.

Returns:
a Detail object
Throws:
SOAPException - if there is a SOAP error
java.lang.UnsupportedOperationException - if the protocol specified for the SOAPFactory was DYNAMIC_SOAP_PROTOCOL


C020

javax.xml.soap
Interface SOAPFault

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


public interface SOAPFault
extends SOAPBodyElement

An element in the SOAPBody object that contains error and/or status information. This information may relate to errors in the SOAPMessage object or to problems that are not related to the content in the message itself. Problems not related to the message itself are generally errors in processing, such as the inability to communicate with an upstream server.

The SOAPFault interface provides methods for retrieving the information contained in a SOAPFault object and for setting the fault code, the fault actor, and a string describing the fault. A fault code is one of the codes defined in the SOAP 1.1 specification that describe the fault. An actor is an intermediate recipient to whom a message was routed. The message path may include one or more actors, or, if no actors are specified, the message goes only to the default actor, which is the final intended recipient.  Depending on the protocol specified while creating the MessageFactory instance, a SOAPFault has sub-elements as defined in the SOAP 1.1/SOAP 1.2 specification.




Method Detail

getFaultString

public java.lang.String getFaultString()
Gets the fault string for this SOAPFault object.

If this SOAPFault is part of a message that supports SOAP 1.2 then this call is equivalent to:

    String reason = null;
try {
reason = (String) getFaultReasonTexts().next();
} catch (SOAPException e) {}
return reason;


Returns:
a String giving an explanation of the fault
See Also:
setFaultString(String), setFaultString(String, Locale)



getFaultActor

java.lang.String getFaultActor()
Gets the fault actor for this SOAPFault object.

If this SOAPFault supports SOAP 1.2 then this call is equivalent to getFaultRole()


Returns:
a String giving the actor in the message path that caused this SOAPFault object
See Also:
setFaultActor(java.lang.String)


setFaultActor

void setFaultActor(java.lang.String faultActor) throws SOAPException
Sets this SOAPFault object with the given fault actor.

The fault actor is the recipient in the message path who caused the fault to happen.

If this SOAPFault supports SOAP 1.2 then this call is equivalent to setFaultRole(String)


Parameters:
faultActor - a String identifying the actor that caused this SOAPFault object
Throws:
SOAPException - if there was an error in adding the faultActor to the underlying XML tree.
See Also:
getFaultActor()


getDetail

Detail getDetail()
Returns the optional detail element for this SOAPFault object.

A Detail object carries application-specific error information related to SOAPBodyElement objects, the scope of the error information is restricted to faults in the SOAPBodyElement objects if this is a SOAP 1.1 Fault.


Returns:
a Detail object with application-specific error information if present, null otherwise.



setFaultString

void setFaultString(java.lang.String faultString)
throws SOAPException
Sets the fault string for this SOAPFault object to the given string.

If this SOAPFault is part of a message that supports SOAP 1.2 then this call is equivalent to:

      addFaultReasonText(faultString, Locale.getDefault());


Parameters:
faultString - a String giving an explanation of the fault
Throws:
SOAPException - if there was an error in adding the faultString to the underlying XML tree.
See Also:
getFaultString()

setFaultString

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.

If this SOAPFault is part of a message that supports SOAP 1.2 then this call is equivalent to:

      addFaultReasonText(faultString, 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()



getFaultStringLocale

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

If this SOAPFault is part of a message that supports SOAP 1.2 then this call is equivalent to:

    Locale locale = null;
try {
locale = (Locale) getFaultReasonLocales().next();
} catch (SOAPException e) {}
return locale;


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)


C021


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 Detail

addTextNode

SOAPElement addTextNode(java.lang.String text)
throws SOAPException
Creates a new Text object initialized with the given String and adds it to this SOAPElement object.


Parameters:
text - a String object with the textual content to be added
Returns:
the SOAPElement object into which the new Text object was inserted
Throws:
SOAPException - if there is an error in creating the new Text object or if it is not legal to attach it as a child to this SOAPElement




setEncodingStyle

void setEncodingStyle(java.lang.String encodingStyle)
throws SOAPException
Sets the encoding style for this SOAPElement object to one specified.


Parameters:
encodingStyle - a String giving the encoding style
Throws:
java.lang.IllegalArgumentException - if there was a problem in the encoding style being set.
SOAPException - if setting the encodingStyle is invalid for this SOAPElement.
See Also:
getEncodingStyle()

Rationale : If this SOAPElement is a SOAP 1.2 element  then there are restrictions in SOAP 1.2 as to which elements in SOAP 1.2 may contain this attribute.

getAttributeValue

java.lang.String getAttributeValue(Name name)
Returns the value of the attribute with the specified name.

Parameters:
name - a Name object with the name of the attribute
Returns:
a String giving the value of the specified attribute, Null if there is no such attribute
See Also:
getAttributeValue(javax.xml.namespace.QName)



addAttribute

SOAPElement addAttribute(Name name,
java.lang.String value)
throws SOAPException
Adds an attribute with the specified name and value to this SOAPElement object.


Parameters:
name - a Name 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 Name name on this SOAPElement.
See Also:
addAttribute(javax.xml.namespace.QName, String)


Rationale : For example, If this SOAPElement is a SOAP 1.2 element and the attribute has the qualified name env:encodingStyle, then there are restrictions in SOAP 1.2 as to which elements in SOAP 1.2 may contain this attribute.


addChildElement

SOAPElement addChildElement(Name name)
throws SOAPException
 Creates a new SOAPElement object initialized with the given Name object and adds the new element to this SOAPElement object. 
This method may be deprecated in a future release of SAAJ in favor of addChildElement(javax.xml.namespace.QName)


Parameters:
name - a Name 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
See Also:
addChildElement(javax.xml.namespace.QName)


Rationale : The semantics of this method was underspecified in the boundary case when the Namespace URI  of the Name is empty ("").

addChildElement

SOAPElement addChildElement(java.lang.String localName)
throws SOAPException
Creates a new SOAPElement object initialized with the specified local name and adds the new element to this SOAPElement object.  The new  SOAPElement  inherits any in-scope default namespace.

Parameters:
localName - a String giving the local name for the element
Returns:
the new SOAPElement object that was created
Throws:
SOAPException - if there is an error in creating the SOAPElement object


Rationale : The semantics of this method was unclear on the  namespace of the new child element.

addChildElement

SOAPElement addChildElement(java.lang.String localName,
java.lang.String prefix)
throws SOAPException
Creates a new SOAPElement object initialized with the specified local name and prefix and adds the new element to this SOAPElement object. 


Parameters:
localName - a String giving the local name for the new element
prefix - a String giving the namespace prefix for the new element
Returns:
the new SOAPElement object that was created
Throws:
SOAPExceptionIf the prefix is not valid in the context of this  SOAPElement or  if there is an error in creating the SOAPElelement object.




addChildElement

public SOAPElement addChildElement(SOAPElement element)
throws SOAPException
Add a SOAPElement as a child of this SOAPElement instance. The SOAPElement is expected to be created by a SOAPElementFactory. Callers should not rely on the element instance being added as is into the XML tree. Implementations could end up copying the content of the SOAPElement passed into an instance of a different SOAPElement implementation. For instance if addChildElement() is called on a SOAPHeader, element will be copied into an instance of a SOAPHeaderElement.

The fragment rooted in element is either added as a whole or not at all, if there was an error.

The fragment rooted in element cannot contain elements named "Envelope", "Header" or "Body" and in the SOAP namespace. Any namespace prefixes present in the fragment should be fully resolved using appropriate namespace declarations within the fragment itself.


Parameters:
element - the SOAPElement to be added as a new child
Returns:
an instance representing the new SOAP element that was actually added to the tree.
Throws:
SOAPException - if there was an error in adding this element as a child


Rationale : SOAPElementFactory has been deprecated


C022

javax.xml.soap
Interface SOAPConstants

public interface SOAPConstants
The definition of constants pertaining to the SOAP 1.1 protocol.


C023


javax.xml.soap
Interface Name



public interface Name

A representation of an XML name. This interface provides methods for getting the local and namespace-qualified names and also for getting the prefix associated with the namespace for the name. It is also possible to get the URI of the namespace.

The following is an example of a namespace declaration in an element.

   <wombat:GetLastTradePrice xmlns:wombat="http://www.wombat.org/trader">
("xmlns" stands for "XML namespace".) The following shows what the methods in the Name interface will return.

XML namespaces are used to disambiguate SOAP identifiers from application-specific identifiers.

Name objects are created using the method SOAPEnvelope.createName, which has two versions. One method creates Name objects with a local name, a namespace prefix, and a namespace URI. and the second creates Name objects with just a local name. The following line of code, in which se is a SOAPEnvelope object, creates a new Name object with all three.

     Name name = se.createName("GetLastTradePrice", "WOMBAT",
"http://www.wombat.org/trader");
The following line of code gives an example of how a Name object can be used. The variable element is a SOAPElement object. This code creates a new SOAPElement object with the given name and adds it to element.
     element.addChildElement(name);

The Name interface may be deprecated in a future release of SAAJ in favor of javax.xml.namespace.QName

See Also:
SOAPEnvelope.createName, SOAPFactory.createName
   

Rationale:  QName is the preferred representation of XML qualified names


C024

javax.xml.soap
Interface SOAPHeader

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


Method Detail


examineMustUnderstandHeaderElements

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.

In SOAP 1.2 the env:actor attribute is replaced by the env:role attribute, but with essentially the same semantics.


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

examineHeaderElements

java.util.Iterator examineHeaderElements(java.lang.String actor)
Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object that have the specified actor. An actor is a global attribute that indicates the intermediate parties that should process a message before it reaches its ultimate receiver. An actor receives the message and processes it before sending it on to the next actor. The default actor is the ultimate intended recipient for the message, so if no actor attribute is included in a SOAPHeader object, it is sent to the ultimate receiver along with the message body.

In SOAP 1.2 the env:actor attribute is replaced by the env:role attribute, but with essentially the same semantics.


Parameters:
actor - a String giving the URI of the actor/role for which to search
Returns:
an Iterator object over all the SOAPHeaderElement objects that contain the specified actor/role
See Also:
extractHeaderElements(java.lang.String), SOAPConstants.URI_SOAP_ACTOR_NEXT

extractHeaderElements

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

This method allows an actor to process the parts of the SOAPHeader object that apply to it and to remove them before passing the message on to the next actor.

In SOAP 1.2 the env:actor attribute is replaced by the env:role attribute, but with essentially the same semantics.


Parameters:
actor - a String giving the URI of the actor/role for which to search
Returns:
an Iterator object over all the SOAPHeaderElement objects that contain the specified actor/role
See Also:
examineHeaderElements(java.lang.String), SOAPConstants.URI_SOAP_ACTOR_NEXT





C025


javax.xml.soap
Interface SOAPHeaderElement

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

Method Detail

getActor

java.lang.String getActor()
Returns the uri of the actor attribute of this SOAPHeaderElement.

If this SOAPHeaderElement supports SOAP 1.2 then this call is equivalent to getRole()


Returns:
a String giving the URI of the actor
See Also:
setActor(java.lang.String)


setActor

void setActor(java.lang.String actorURI)
Sets the actor associated with this SOAPHeaderElement object to the specified actor. The default value of an actor is: SOAPConstants.URI_SOAP_ACTOR_NEXT

If this SOAPHeaderElement supports SOAP 1.2 then this call is equivalent to setRole(String)


Parameters:
actorURI - a String giving the URI of the actor to set
Throws:
java.lang.IllegalArgumentException - if there is a problem in setting the actor.
See Also:
getActor()


C026

javax.xml.soap
Class SOAPMessage

java.lang.Object
extended by javax.xml.soap.SOAPMessage
Method Detail

writeTo

public abstract void writeTo(java.io.OutputStream out)
throws SOAPException,
java.io.IOException
Writes this SOAPMessage object to the given output stream. The externalization format is as defined by the SOAP 1.1 with Attachments specification.

If there are no attachments, just an XML stream is written out. For those messages that have attachments, writeTo writes a MIME-encoded byte stream.

Note that this method does not write the transport-specific MIME Headers of the Message

Parameters:
out - the OutputStream object to which this SOAPMessage object will be written
Throws:
java.io.IOException - if an I/O error occurs
SOAPException - if there was a problem in externalizing this SOAP message
         

createAttachmentPart

public AttachmentPart createAttachmentPart(java.lang.Object content,
java.lang.String contentType)
Creates an AttachmentPart object and populates it with the specified data of the specified content type. The type of the Object should correspond to the value given for the Content-Type.

Parameters:
content - an Object containing the content for this SOAPMessage  the AttachmentPart object  to be created
contentType - a String object giving the type of content; examples are "text/xml", "text/plain", and "image/jpeg"
Returns:
a new AttachmentPart object that contains the given data
Throws:
java.lang.IllegalArgumentException - may be thrown if the contentType does not match the type of the content object, or if there was no DataContentHandler object for the given content object
See Also:
DataHandler, DataContentHandler

C027

javax.xml.soap
Class AttachmentPart

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

 
Method Detail


setContent

public abstract void setContent(java.lang.Object object,
java.lang.String contentType)
Sets the content of this attachment part to that of the given Object and sets the value of the Content-Type header to the given type. The type of the Object should correspond to the value given for the Content-Type. This depends on the particular set of DataContentHandler objects in use.

Parameters:
object - the Java object that makes up the content for this attachment part
contentType - the MIME string that specifies the type of the content
Throws:
java.lang.IllegalArgumentException - may be thrown if the contentType does not match the type of the content object, or if there was no DataContentHandler object for this content object
See Also:
getContent()

11) Proposed Changes Supporting Addition of  New Methods in Certain APIs


C028

javax.xml.soap
Class SOAPMessage



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

Method Summary
abstract  AttachmentPart getAttachment(SOAPElement element)
          Returns an AttachmentPart object that is associated with an attachment that is referenced by this SOAPElement or null if no such attachment exists.
abstract  void removeAttachments(MimeHeaders headers)
          Removes all the AttachmentPart objects that have header entries that match the specified headers.


Method Detail

getAttachment


public abstract AttachmentPart getAttachment(SOAPElement element)
throws SOAPException
Returns an AttachmentPart object that is associated with an attachment that is referenced by this SOAPElement or null if no such attachment exists. References can be made via an href attribute as described in SOAP Messages with Attachments, or via a single Text child node containing a URI as described in the WS-I Attachments Profile 1.0 for elements of schema type ref:swaRef. These two mechanisms must be supported. The support for references via href attribute also implies that this method should also be supported on an element that is an xop:Include element ( XOP). other reference mechanisms may be supported by individual implementations of this standard. Contact your vendor for details.

Parameters:
element - The SOAPElement containing the reference to an Attachment
Returns:
the referenced AttachmentPart or null if no such AttachmentPart exists or no reference can be found in this SOAPElement.
Throws:
SOAPException - if there is an error in the attempt to access the attachment
Since:
SAAJ 1.3




Rationale : see javadoc explanation above.

removeAttachments

public abstract void removeAttachments(MimeHeaders headers)
Removes all the AttachmentPart objects that have header entries that match the specified headers. Note that the removed attachment could have headers in addition to those specified.

Parameters:
headers - a MimeHeaders object containing the MIME headers for which to search
Since:
SAAJ 1.3



Rationale : There was no API in SAAJ 1.2  to remove a particular Attachment


               

C029


javax.xml.soap
Class SOAPFactory

java.lang.Object
extended by javax.xml.soap.SOAPFactory
Method Summary
 SOAPElement createElement(org.w3c.dom.Element domElement)
          Creates a SOAPElement object from an existing DOM Element.
 abstract  SOAPFault
createFault()
          Creates a new default SOAPFault object
 abstract  SOAPFault
createFault(java.lang.String reasonText, javax.xml.namespace.QName faultCode)
          Creates a new SOAPFault object initialized with the given reasonText and faultCode
 
 
Method Detail

createElement

public SOAPElement createElement(org.w3c.dom.Element domElement)throws SOAPException
Creates a SOAPElement object from an existing DOM Element. If the DOM Element that is passed in as an argument is already a SOAPElement then this method must return it unmodified without any further work. Otherwise, a new SOAPElement is created and a deep copy is made of the domElement argument. The concrete type of the return value will depend on the name of the domElement argument. If any part of the tree rooted in domElement violates SOAP rules, a SOAPException will be thrown.
Parameters:
domElement - - the Element to be copied.
Returns:
a new SOAPElement that is a copy of domElement.
Throws:
SOAPException - if there is an error in creating the SOAPElement object
Since:
SAAJ 1.3

Rationale: Useful when one wants to obtain a SAAJ Tree out of a DOM Tree


createFault

public abstract SOAPFault createFault()
throws SOAPException
Creates a new default SOAPFault object

Returns:
a SOAPFault object
Throws:
SOAPException - if there is a SOAP error
Since:
SAAJ 1.3



createFault

public abstract SOAPFault createFault(java.lang.String reasonText,
javax.xml.namespace.QName faultCode)
throws SOAPException
Creates a new SOAPFault object initialized with the given reasonText and faultCode

Parameters:
reasonText - the ReasonText/FaultString for the fault
faultCode - the FaultCode for the fault
Returns:
a SOAPFault object
Throws:
SOAPException - if there is a SOAP error
Since:
SAAJ 1.3

Rationale: Provides a simple way of getting a SOAPFault  instance that can be used to create a SOAPFaultException




C030

javax.xml.soap
Interface SOAPBody

All Superinterfaces:
org.w3c.dom.Element, org.w3c.dom.Node, SOAPElement
 
Method Summary
 org.w3c.dom.Document extractContentAsDocument()
          Creates a new DOM Document and sets the first child of this SOAPBody as it's document element.


Method Detail

extractContentAsDocument

org.w3c.dom.Document extractContentAsDocument()throws SOAPException
Creates a new DOM Document and sets the first child of this SOAPBody as it's document element. The child SOAPElement is removed as part of the process.

Returns:
the Document representation of the SOAPBody content.
Throws:
SOAPException - if there is not exactly one child SOAPElement of the SOAPBody.
Since:
SAAJ 1.3


Rationale : Useful when it is required to extract the content of SOAP Body as org.w3c.dom.Document. It is also the missing counterpart for SAAJ 1.2 addDocument(org.w3c.dom.Document).

C031


javax.xml.soap
Class SOAPConnection

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

Method Summary
 SOAPMessage get(java.lang.Object to)
          Gets a message from a specific endpoint and blocks until it receives,

Method Detail

get

public SOAPMessage get(java.lang.Object to)
throws SOAPException
Gets a message from a specific endpoint and blocks until it receives,
Parameters:
to - an Object that identifies where the request should be sent. Objects of type java.lang.String and java.net.URL must be supported.
Returns:
the SOAPMessage object that is the response to the get message request
Throws:
SOAPException - if there is a SOAP error
Since:
SAAJ 1.3



Rationale : Support for HTTP GET on SOAPConnection



C032


javax.xml.soap
Class AttachmentPart

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

Method Summary
abstract  java.io.InputStream getBase64Content()
          Returns an InputStream which can be used to obtain the content of AttachmentPart as Base64 encoded character data, this method would base64 encode the raw bytes of the attachment and return.
abstract  java.io.InputStream getRawContent()
          Gets the content of this AttachmentPart object as an InputStream as if a call had been made to getContent and no DataContentHandler had been registered for the content-type of this AttachmentPart.
abstract  void setBase64Content(java.io.InputStream content, java.lang.String contentType)
          Sets the content of this attachment part from the Base64 source InputStream and sets the value of the Content-Type header to the value contained in contentType, This method would first decode the base64 input and write the resulting raw bytes to the attachment.
abstract  void setRawContent(java.io.InputStream content, java.lang.String contentType)
          Sets the content of this attachment part to that contained by the InputStream content and sets the value of the Content-Type header to the value contained in contentType.
    abstract  byte[] getRawContentBytes()
          Gets the content of this AttachmentPart object as a byte[] array as if a call had been made to getContent and no DataContentHandler had been registered for the content-type of this AttachmentPart.
      abstract  void setRawContentBytes(byte[] content,int offset, int len, java.lang.String contentType)
          Sets the content of this attachment part to that contained by the byte[] array content and sets the value of the Content-Type header to the value contained in contentType.
 
Method Detail

getBase64Content

public abstract java.io.InputStream getBase64Content()
throws SOAPException
Returns an InputStream which can be used to obtain the content of AttachmentPart as Base64 encoded character data, this method would base64 encode the raw bytes of the attachment and return.
Returns:
an InputStream from which the Base64 encoded AttachmentPart can be read.
Throws:
SOAPException - if there is no content set into this AttachmentPart object or if there was a data transformation error.
Since:
SAAJ 1.3



getRawContent

public abstract java.io.InputStream getRawContent()
throws SOAPException
Gets the content of this AttachmentPart object as an InputStream as if a call had been made to getContent and no DataContentHandler had been registered for the content-type of this AttachmentPart.

Note that reading from the returned InputStream would result in consuming the data in the stream. It is the responsibility of the caller to reset the InputStream appropriately before calling a Subsequent API. If a copy of the raw attachment content is required then the getRawContentBytes() API should be used instead.

Returns:
an InputStream from which the raw data contained by the AttachmentPart can be accessed.
Throws:
SOAPException - if there is no content set into this AttachmentPart object or if there was a data transformation error.
Since:
SAAJ 1.3
See Also:
getRawContentBytes()


setRawContent

public abstract void setRawContent(java.io.InputStream content,
java.lang.String contentType) throws SOAPException
Sets the content of this attachment part to that contained by the InputStream content and sets the value of the Content-Type header to the value contained in contentType.

         A subsequent call to getSize() may not be an exact measure of the content size.


Parameters:
content - the raw data to add to the attachment part
contentType - the value to set into the Content-Type header
Throws:
SOAPException - if there is an error in setting the content
java.lang.NullPointerException - if content is null
Since:
SAAJ 1.3



setBase64Content

public abstract void setBase64Content(java.io.InputStream content,
java.lang.String contentType) throws SOAPException
Sets the content of this attachment part from the Base64 source InputStream content and sets the value of the Content-Type header to the value contained in contentType, This method would first decode the base64 input and write the resulting raw bytes to the attachment.
         
         A subsequent call to getSize() may not be an exact measure of the content size.

Parameters:
content - the base64 encoded data to add to the attachment part
contentType - the value to set into the Content-Type header
Throws:
SOAPException - if there is an  error in setting the content
java.lang.NullPointerException - if content is null
Since:
SAAJ 1.3



getRawContentBytes

public abstract byte[] getRawContentBytes()
throws SOAPException
Gets the content of this AttachmentPart object as a byte[] array as if a call had been made to getContent and no DataContentHandler had been registered for the content-type of this AttachmentPart.

Returns:
a byte[] array containing the raw data of the AttachmentPart.
Throws:
SOAPException - if there is no content set into this AttachmentPart object or if there was a data transformation error.
Since:
SAAJ 1.3



setRawContentBytes

public abstract void setRawContentBytes(byte[] content,
int offset,
int len,
java.lang.String contentType)
throws SOAPException
Sets the content of this attachment part to that contained by the byte[] array content and sets the value of the Content-Type header to the value contained in contentType.

Parameters:
content - the raw data to add to the attachment part
contentType - the value to set into the Content-Type header
offset - the offset in the byte array of the content
len - the number of bytes that form the content
Throws:
SOAPException - if an there is an error in setting the content or content is null
Since:
SAAJ 1.3

Rationale : Following Methods have been added new in SAAJ 1.3.

These methods would allow  retrieval of the  contents of an attachment as base64/raw  data and write an attachment from a base64 source. getBase64Content would base64 encode the raw bytes of the attachment, setBase64Content would decode the base64 input and write the resulting raw bytes to the attachment.

The XOP specification allows attachments to either be serialized inside the message as base64 or as raw bytes in an attachment, these  methods would be convenient when switching between these two representations.



12) Proposed Change  Making SOAPPart  a javax.xml.soap.Node

C033

javax.xml.soap
Class SOAPPart

java.lang.Object
 extended by 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, Node

The container for the SOAP-specific portion of a SOAPMessage object. All messages are required to have a SOAP part, so when a SOAPMessage object is created, it will automatically have a SOAPPart object.

A SOAPPart object is a MIME part and has the MIME headers Content-Id, Content-Location, and Content-Type. Because the value of Content-Type must be "text/xml", a SOAPPart object automatically has a MIME header of Content-Type with its value set to "text/xml". The value must be "text/xml" because content in the SOAP part of a message must be in XML format. Content that is not of type "text/xml" must be in an AttachmentPart object rather than in the SOAPPart object.

When a message is sent, its SOAP part must have the MIME header Content-Type set to "text/xml". Or, from the other perspective, the SOAP part of any message that is received must have the MIME header Content-Type with a value of "text/xml".

A client can access the SOAPPart object of a SOAPMessage object by calling the method SOAPMessage.getSOAPPart. The following line of code, in which message is a SOAPMessage object, retrieves the SOAP part of a message.

   SOAPPart soapPart = message.getSOAPPart();

A SOAPPart object contains a SOAPEnvelope object, which in turn contains a SOAPBody object and a SOAPHeader object. The SOAPPart method getEnvelope can be used to retrieve the SOAPEnvelope object.

  


Rationale : In SAAJ 1.2 SOAPPart was implementing org.w3c.dom.Document  only. 


13) Deferred Changes

    1. Deprecating the Name interface in favor of the QName class.

14) Constant Field Values


C034



Constant Field Values


Contents
javax.xml.*

javax.xml.soap.SOAPConstants
public static final java.lang.String DEFAULT_SOAP_PROTOCOL "SOAP 1.1 Protocol"
public static final java.lang.String DYNAMIC_SOAP_PROTOCOL "Dynamic Protocol"
public static final java.lang.String SOAP_1_1_CONTENT_TYPE "text/xml"
public static final java.lang.String SOAP_1_1_PROTOCOL "SOAP 1.1 Protocol"
public static final java.lang.String SOAP_1_2_CONTENT_TYPE "application/soap+xml"
public static final java.lang.String SOAP_1_2_PROTOCOL "SOAP 1.2 Protocol"
public static final java.lang.String SOAP_ENV_PREFIX "env"
public static final java.lang.String URI_NS_SOAP_1_1_ENVELOPE "http://schemas.xmlsoap.org/soap/envelope/"
public static final java.lang.String URI_NS_SOAP_1_2_ENCODING "http://www.w3.org/2003/05/soap-encoding"
public static final java.lang.String URI_NS_SOAP_1_2_ENVELOPE "http://www.w3.org/2003/05/soap-envelope"
public static final java.lang.String URI_NS_SOAP_ENCODING "http://schemas.xmlsoap.org/soap/encoding/"
public static final java.lang.String URI_NS_SOAP_ENVELOPE "http://schemas.xmlsoap.org/soap/envelope/"
public static final java.lang.String URI_SOAP_1_2_ROLE_NEXT "http://www.w3.org/2003/05/soap-envelope/role/next"
public static final java.lang.String URI_SOAP_1_2_ROLE_NONE "http://www.w3.org/2003/05/soap-envelope/role/none"
public static final java.lang.String URI_SOAP_1_2_ROLE_ULTIMATE_RECEIVER "http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver"
public static final java.lang.String URI_SOAP_ACTOR_NEXT "http://schemas.xmlsoap.org/soap/actor/next"