SOAPElementFactory | Java Web Services in a Nutshell

SOAPElement

javax.xml.soap

SAAJ 1.1; JWSDP 1.0, J2EE 1.4

 public interface SOAPElement extends Node {  // Property Accessor Methods (by property name)  public abstract Iterator getAllAttributes(  );      public abstract Iterator getChildElements(  );      public abstract Iterator getChildElements( Name   name   );      public abstract Name getElementName(  );      public abstract String getEncodingStyle(  );      public abstract void setEncodingStyle(     String   encodingStyle   ) throws SOAPException;      public abstract Iterator getNamespacePrefixes(  );  // Public Instance Methods  public abstract SOAPElement addAttribute(Name   name   , String   value   )          throws SOAPException;      public abstract SOAPElement addChildElement(SOAPElement   element   ) throws SOAPException;      public abstract SOAPElement addChildElement(String   localName   )          throws SOAPException;      public abstract SOAPElement addChildElement(Name   name   )          throws SOAPException;      public abstract SOAPElement addChildElement(String   localName   ,          String   prefix   ) throws SOAPException;      public abstract SOAPElement addChildElement(String   localName   , String   prefix   ,          String   uri   ) throws SOAPException;      public abstract SOAPElement addNamespaceDeclaration(String   prefix   ,          String   uri   ) throws SOAPException      public abstract SOAPElement addTextNode(String   text   ) throws SOAPException;      public abstract String getAttributeValue( Name   name   );      public abstract String getNamespaceURI( String   prefix   );      public abstract boolean removeAttribute( Name   name   );      public abstract boolean removeNamespaceDeclaration(String   prefix   );  }

A SOAPElement represents an element within a SOAPMessage . SOAPElement is derived from Node and inherits its ability to be associated with a parent node, thus allowing the construction of a message as a tree of objects representing the elements and attributes that will eventually be serialized into XML tags. With the exception of Text , SOAPPart , and AttachmentPart , all of the nodes within a SOAPMessage are SOAPElement s. SOAPElement has a number of derived interfaces that are used to form particular parts of a SOAP message. For example, SOAPHeaderElement is a SOAPElement that appears only as a direct child of a SOAPHeader . Where these special interfaces exist, they are the only type of element that can be added to their particular parent. An attempt to add a SOAPElement where a more specialized type is required does not, however, result in an exception. Instead, the element and any child elements it might have are copied , and the root element is converted to the correct specialized type before being added to the parent. An attempt to add a SOAPElement to a SOAPHeader , for example, would result in an equivalent SOAPHeaderElement being added instead.

There are several ways to create a SOAPElement . The simplest way is to use one of the addChildElement( ) methods of an existing SOAPElement , such as SOAPBody , which both creates a new element and makes it a child of the original element. There are five variants of this method.

The addChildElement(Name name) method creates a new element whose name and namespace prefix are taken from the supplied Name object. A namespace declaration linking the namespace prefix to the namespace URI from the Name object is also added to the element. If the Name object does not have an explicit namespace, then neither the namespace prefix nor the namespace declaration appears on the element.
The addChildElement(String localName) method creates an element whose name is supplied by the localName argument and has no explicit namespace. The element is therefore in the default namespace declared by the nearest ancestor that has an xlmns : namespace declaration, or it is declared by itself if such a declaration is added using the addNamespaceDeclaration( ) method.
The addChildElement(String localName, String prefix, String uri) method creates an element in which the name, namespace prefix, and namespace URI are obtained from the method arguments. A namespace declaration linking the prefix and URI are included. For example, the method call addChildElement("BookQuery", "book", "urn:BookService") would create an element that would be serialized as book:BookQuery xmlns:book="urn:BookService ".
The addChildElement(String localName, String prefix) method creates an element with the given local name and namespace prefix. A mapping from the given prefix to a URI must have been provided by an ancestor of the newly created element, or a SOAPException is thrown.
The addChildElement(SOAPElement element) method adds either an existing element or a copy of that element (and any child elements it might have) as a child of the element on which it is invoked. The specification of this method warns that application code should not assume that the element itself is added, and a copy is actually added in the reference implementation.

All of the addChildElement( ) methods return a reference to the SOAPElement that was created and/or added. This can be useful if you want to create several nested elements in a single line of code:

 body.addChildElement("Level1").addChildElement("Level2"). addChildElement("Level3").addTextNode("Text");

This code adds three levels of nested elements. The addTextNode( ) adds the text passed to it below the SOAPElement on which it is called and returns a reference to that SOAPElement . The result of executing this code is the following:

 <Level1>        <Level2>            <Level3>Text</Level3>        </Level2> </Level1>

SOAPElement provides a group of methods that allow you to add and manipulate attributes. The addAttribute( ) method adds an attribute whose name and namespace prefix are given by the Name argument and equates it to the supplied attribute value. If the Name object does not have an associated namespace, then no namespace prefix appears in the serialized XML. The setEncodingStyle( ) method is a convenience method that allows you to set the attribute that represents the SOAP encoding style that applies to an element and its descendents without having to explicitly name the attribute. The following code extract sets the default SOAP encoding rules:

 element.setEncodingStyle(SOAPConstants.URI_NS_SOAP_ENCODING);

The getEncodingStyle( ) method returns the encoding style set for the element on which it is invoked. Note that this method does not search the ancestors of the element for an inherited encoding style if the element itself does not specify oneit simply returns null . The getAttributeValue( ) method can be used to obtain the value of an attribute given its Name . If the given attribute is not present, then null is returned. You can get an Iterator containing a Name object for each attribute attached to an element by calling the getAllAttributes( ) method, and you can remove an attribute with removeAttribute( ) .

The final group of SOAPElement methods handles namespaces. addNamespaceDeclaration( ) adds a namespace declaration to the element that links the given namespace prefix to its URI. For example, the following code links the namespace prefix book to the URI urn:BookService for the scope of the element referred to by the element variable and its child elements:

 element.addNamespaceDeclaration("book", "urn:BookService");

The serialized XML for this element looks like this, assuming the element is called BookName :

 <BookName xmlns:book="urn:BookService"/>

If the prefix is supplied as the empty string, then a declaration of the default namespace is being made (i.e., xmlns="urn:BookService "). The removeNamespaceDeclaration( ) method removes a namespace declaration from an element given its namespace prefix. The getNamespacePrefixes( ) method returns an Iterator in which each element is a string that represents the prefix of a namespace declaration attached to the element on which it is invoked. To get the namespace URI for a given prefix, use the getNamespaceURI( ) method.

Implementations

DetailEntry , SOAPBody , SOAPBodyElement , SOAPEnvelope , SOAPFaultElement , SOAPHeader , SOAPHeaderElement

Passed To

Node.setParentElement( ) , SOAPElement.addChildElement( )

Returned By

Node.getParentElement( ) , SOAPElement.{addAttribute( ) , addChildElement( ) , addNamespaceDeclaration( ) , addTextNode( )} , SOAPElementFactory.create( ) , SOAPFactory.createElement( )