com.ibm.websphere.webservices.soap

Interface IBMSOAPElement

All Superinterfaces:

org.w3c.dom.Element, IBMNode, org.w3c.dom.Node, javax.xml.soap.SOAPElement

All Known Subinterfaces:

IBMDetail, IBMDetailEntry, IBMSOAPBody, IBMSOAPBodyElement, IBMSOAPEnvelope, IBMSOAPFault, IBMSOAPFaultElement, IBMSOAPHeader, IBMSOAPHeaderElement

public interface IBMSOAPElement
extends javax.xml.soap.SOAPElement, IBMNode

This interface exposes IBM-value add methods.

See Also:

SOAPElement

Field Summary

Fields inherited from interface org.w3c.dom.Node

ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE

Method Summary

Methods

Modifier and Type	Method and Description
javax.xml.soap.SOAPElement	addComment(java.lang.String text) Creates a new Comment object initialized with the given String and adds it to this javax.xml.soap.SOAPElement object.
javax.xml.soap.SOAPElement	addSwaRefTextNode(java.lang.String mimeType, java.lang.Object attachment) Add an swaRef text node to this SOAPElement.
java.util.List	getAttributes(boolean above, boolean on, boolean below) Returns a list of Attr objects.
org.w3c.dom.NodeList	getChildNodes() Returns the list of child nodes for this SOAPElement.
IBMSOAPFactory	getIBMSOAPFactory() Returns the SOAPFactory
javax.xml.soap.Name	getNameFromText(java.lang.String text) A javax.xml.soap.Name is constructed from the input text and the namespace/prefix information defined by the SOAPElement.
java.util.List	getNamespaceDeclarations(boolean above, boolean on, boolean below) Returns a list of Attr objects for xmlns attributes.
java.lang.Object	getSwaRefAttachment() Get the attachment referred to by this swaRef.
java.lang.Object	getSwaRefAttachment(javax.xml.soap.SOAPMessage message) Get the attachment referred to by this swaRef.
java.lang.String	getTextFromName(javax.xml.soap.Name name, boolean autoGenPrefix) This is the reverse of the utility above.
boolean	hasAlternateContent() Returns true if some or all of the SOAPElement's data content is stored in a non-SAAJ format.
boolean	isSwaRef() Deterimine if this SOAPElement is an swaRef.
org.xml.sax.InputSource	toInputSource(boolean includeNSDecls) Get an InputSource representing this SOAPElement There are actually two representations of a SOAPElement.
java.lang.String	toXMLString(boolean includeNSDecls) Get a string of xml representing this SOAPElement There are actually two representations of a SOAPElement as a string: The first representation contains all of the data in the SOAPElement and its descendents.

Methods inherited from interface javax.xml.soap.SOAPElement

addAttribute, addAttribute, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addNamespaceDeclaration, addTextNode, createQName, getAllAttributes, getAllAttributesAsQNames, getAttributeValue, getAttributeValue, getChildElements, getChildElements, getChildElements, getElementName, getElementQName, getEncodingStyle, getNamespacePrefixes, getNamespaceURI, getVisibleNamespacePrefixes, removeAttribute, removeAttribute, removeContents, removeNamespaceDeclaration, setElementQName, setEncodingStyle

Methods inherited from interface org.w3c.dom.Element

getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getElementsByTagName, getElementsByTagNameNS, getSchemaTypeInfo, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS, setIdAttribute, setIdAttributeNode, setIdAttributeNS

Methods inherited from interface javax.xml.soap.Node

detachNode, getParentElement, getValue, recycleNode, setParentElement, setValue

Methods inherited from interface org.w3c.dom.Node

appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Method Detail

toXMLString

java.lang.String toXMLString(boolean includeNSDecls)

Get a string of xml representing this SOAPElement

There are actually two representations of a SOAPElement as a string:

• The first representation contains all of the data in the SOAPElement and its descendents. The xml will exactly represent the SOAPElement, but the xml may not be usable because the SOAPElement may depend on namespaces defined in the parent elements.
• The second representation containst all of the data in the SOAPElement and its descendents AND includes all namespace declarations from the ancestor elements.

If includeNSDecls is false, the first representation is used.

If includeNSDecls is true, the second representation is used.

Parameters:

includeNSDecls - boolean

Returns:

String

toInputSource

org.xml.sax.InputSource toInputSource(boolean includeNSDecls)
                                      throws org.xml.sax.SAXException

Get an InputSource representing this SOAPElement

There are actually two representations of a SOAPElement.

• The first representation contains all of the data in the SOAPElement and its descendents. The xml will exactly represent the SOAPElement, but the xml may not be usable because the SOAPElement may depend on namespaces defined in the parent elements.
• The second representation contains all of the data in the SOAPElement and its descendents AND includes all namespace declarations from the ancestor elements.

If includeNSDecls is false, the first representation is used.

If includeNSDecls is true, the second representation is used.

Parameters:

includeNSDecls - boolean

Returns:

InputSource

Throws:

org.xml.sax.SAXException

hasAlternateContent

boolean hasAlternateContent()

Returns true if some or all of the SOAPElement's data content is stored in a non-SAAJ format. For example, the internal representation of the data content may be a String containing unparsed xml text. In such cases, this method will return true.

When an DOM or SAAJ method is invoked, the alternative content is automatically transformed into a full SAAJ tree. In such cases, this method will return true.

Returns:

boolean true or false

getNamespaceDeclarations

java.util.List getNamespaceDeclarations(boolean above,
                                      boolean on,
                                      boolean below)

Returns a list of Attr objects for xmlns attributes. Use the input parameters to designate if you want the namespace declarations above, on and/or below this element. The order of the attributes in the returned list are as follows:

• 1) The "above" Attrs occur first on the list and are ordered according to the ancestory. The Attrs for the oldest ancestor are first.
• 2) The "on" Attrs occur after the "above" Attrs.
• 3) The "below" Attrs occur after the "on" Attrs. For any given "below" Attr you can assume that all its ancestor xmlns declarations preceed it on the list.

Parameters:

above - boolean

on - boolean

below - boolean

Returns:

List of org.w3c.dom.Attr objects.

getAttributes

java.util.List getAttributes(boolean above,
                           boolean on,
                           boolean below)

Returns a list of Attr objects. Use the input parameters to designate if you want the attributes above, on and/or below this element. The order of the attributes in the returned list are as follows:

• 1) The "above" Attrs occur first on the list and are ordered according to the ancestory. The Attrs for the oldest ancestor are first.
• 2) The "on" Attrs occur after the "above" Attrs.
• 3) The "below" Attrs occur after the "on" Attrs. For any given "below" Attr you can assume that all its ancestor attributes preceed it on the list.

Parameters:

above - boolean

on - boolean

below - boolean

Returns:

List of org.w3c.dom.Attr objects.

getNameFromText

javax.xml.soap.Name getNameFromText(java.lang.String text)

A javax.xml.soap.Name is constructed from the input text and the namespace/prefix information defined by the SOAPElement.

 Example:
 
 Input:
 text = "pre:foo" 
 SOAPElement = 

 Output:
 Name with the following information:
    prefix    = "pre"
    localName = "foo"
    uri       = "http://namespace"
    qualified name = "pre:foo"
 

Intended Use: A SOAPElement may contain a text value or an attribute value that represents a QName. This utility method is useful for obtaining the Name from the text.

Parameters:

text - String representing a QName.

Returns:

Name representing the text or null

getTextFromName

java.lang.String getTextFromName(javax.xml.soap.Name name,
                               boolean autoGenPrefix)

This is the reverse of the utility above. A text String is created that represents the Name.

The SOAPElement is changed to add any necessary namespace/prefix information.

 Example:
 Input
 SOAPElement = 
 Name has the following information:  
    prefix    = "pre"
    localName = "foo"
    uri       = "http://namespace"
    qualified name = "pre:foo"
 
 Output:
 SOAPElement = 
 text = "pre:foo"
 

Intended Use: A SOAPElement may contain a text value or an attribute value that represents a QName. This utility method is useful for setting the value from a Name object.

Parameters:

name -

autoGenPrefix - boolean if set to true, the prefix in the Name is ignored and a new prefix is automatically generated.

Returns:

Text representing name or null. Side effect: SOAPElement updated with namespace information

addSwaRefTextNode

javax.xml.soap.SOAPElement addSwaRefTextNode(java.lang.String mimeType,
                                           java.lang.Object attachment)
                                             throws javax.xml.soap.SOAPException

Add an swaRef text node to this SOAPElement.

This method is an addition to the standard SAAJ functionality. However, this functionality may be added to SAAJ in the future, in which case it will then become deprecated.

Parameters:

mimeType - MIME data type of the swaRef

attachment - The attachment object. The class of this object must match the mimeType.

Throws:

SOAPException - if the attachment could not be added, or the attachment object doesn't match the mimeType:

 image/gif, image/jpeg     ==> java.awt.Image
 text/plain                ==> java.lang.String
 multipart/*               ==> javax.mail.internet.MimeMultipart
 text/xml, application/xml ==> javax.xml.transform.Source
 all others                ==> javax.activation.DataHandler
 

javax.xml.soap.SOAPException

isSwaRef

boolean isSwaRef()

Deterimine if this SOAPElement is an swaRef.

This is an addition to the standard SAAJ functionality. However, this functionality may be added to SAAJ in the future, in which case it will then become deprecated.

Returns:

true if this SOAPElement is an swaRef.

getSwaRefAttachment

java.lang.Object getSwaRefAttachment()
                                     throws javax.xml.soap.SOAPException

Get the attachment referred to by this swaRef. Note that there are two versions to this method: one takes no parameters; the other takes a SOAPMessage.

SOAPMessage has methods to get attachments. The no-parameter version is slightly less efficient since it has to find the SOAPMessage associated with this SOAPElement.

This method is an addition to the standard SAAJ functionality. However, this functionality may be added to SAAJ in the future, in which case it will then become deprecated.

Throws:

SOAPException - if this SOAPElement is not an swaRef.

javax.xml.soap.SOAPException

getSwaRefAttachment

java.lang.Object getSwaRefAttachment(javax.xml.soap.SOAPMessage message)
                                     throws javax.xml.soap.SOAPException

Get the attachment referred to by this swaRef.

Note that there are two versions to this method: one takes no parameters; the other takes a SOAPMessage. SOAPMessage has methods to get attachments. The no-parameter version is slightly less efficient since it has to find the

SOAPMessage associated with this SOAPElement.

This method is an addition to the standard SAAJ functionality. However, this functionality may be added to SAAJ in the future, in which case it will then become deprecated.

Parameters:

message - If you have the SOAPMessage associated with this SOAPElement, give it to this method so it doesn't have to look for it itself.

Throws:

SOAPException - if this SOAPElement is not an swaRef.

javax.xml.soap.SOAPException

getChildNodes

org.w3c.dom.NodeList getChildNodes()

Returns the list of child nodes for this SOAPElement.

Note: The returned NodeList is not thread-safe. In a multi-threaded environment, use the DOM getFirstChild()/getNextSibling() methods to traverse the children.

For example, the following code may fail in a multi-threaded environment:

   NodeList nl = el.getChildNodes();       
   for (int i=0; i<.getLength(); i++) {  
      Node child = nl.item(i);             
      ...                                  
   }                                       
 

Here is the same logic using the getFirstChild()/getNextSibling() methods:

   for (Node child = el.getFirstChild();   
        child != null;                     
        child = child.getNextSibling()) {  
      ...                                  
   }                                       
 

Specified by:

getChildNodes in interface org.w3c.dom.Node

Returns:

NodeList the list of child nodes for this SOAPElement

addComment

javax.xml.soap.SOAPElement addComment(java.lang.String text)
                                      throws javax.xml.soap.SOAPException

Creates a new Comment object initialized with the given String and adds it to this javax.xml.soap.SOAPElement object.

Parameters:

text - a String object with the textual content to be added

Returns:

the javax.xml.soap.SOAPElement object into which the new Comment object was inserted

Throws:

SOAPException - if there is an error in creating the new Comment object

javax.xml.soap.SOAPException

getIBMSOAPFactory

IBMSOAPFactory getIBMSOAPFactory()

Returns the SOAPFactory

Returns:

the SOAPFactory that created a SOAPElement