OReilly Java Web Services In A Nutshell Jun 2003 ISBN 0596003994

SOAPElement

javax.xml.soap

SAAJ1.1;JWSDP1.0,J2EE1.4

publicinterfaceSOAPElementextendsNode{
//PropertyAccessorMethods(bypropertyname)
publicabstractIteratorgetAllAttributes();
publicabstractIteratorgetChildElements();
publicabstractIteratorgetChildElements(Namename);
publicabstractNamegetElementName();
publicabstractStringgetEncodingStyle();
publicabstractvoidsetEncodingStyle(
StringencodingStyle)throwsSOAPException;
publicabstractIteratorgetNamespacePrefixes();
//PublicInstanceMethods
publicabstractSOAPElementaddAttribute(Namename,Stringvalue
throwsSOAPException;
publicabstractSOAPElementaddChildElement(SOAPElementelement)throwsSOA
publicabstractSOAPElementaddChildElement(StringlocalName)
throwsSOAPException;
publicabstractSOAPElementaddChildElement(Namename)
throwsSOAPException;
publicabstractSOAPElementaddChildElement(StringlocalName,
Stringprefix)throwsSOAPException;
publicabstractSOAPElementaddChildElement(StringlocalName,String

Stringuri)throwsSOAPException;
publicabstractSOAPElementaddNamespaceDeclaration(Stringprefix
Stringuri)throwsSOAPException
publicabstractSOAPElementaddTextNode(Stringtext)throwsSOAPException;
publicabstractStringgetAttributeValue(Namename);
publicabstractStringgetNamespaceURI(Stringprefix);
publicabstractbooleanremoveAttribute(Namename);
publicabstractbooleanremoveNamespaceDeclaration(Stringprefix
}

ASOAPElementrepresentsanelementwithinaSOAPMessage.SOAPElementis
derivedfromNodeandinheritsitsabilitytobeassociatedwithaparentnode,
thusallowingtheconstructionofamessageasatreeofobjectsrepresentingthe
elementsandattributesthatwilleventuallybeserializedintoXMLtags.Withthe
exceptionofText,SOAPPart,andAttachmentPart,allofthenodeswithina
SOAPMessageareSOAPElements.SOAPElementhasanumberofderivedinterfaces
thatareusedtoformparticularpartsofaSOAPmessage.Forexample,
SOAPHeaderElementisaSOAPElementthatappearsonlyasadirectchildofa


SOAPHeader.Wherethesespecialinterfacesexist,theyaretheonlytypeof

elementthatcanbeaddedtotheirparticularparent.Anattempttoadda
SOAPElementwhereamorespecializedtypeisrequireddoesnot,however,result
inanexception.Instead,theelementandanychildelementsitmighthaveare
copied,andtherootelementisconvertedtothecorrectspecializedtypebefore
beingaddedtotheparent.AnattempttoaddaSOAPElementtoaSOAPHeader,for
example,wouldresultinanequivalentSOAPHeaderElementbeingaddedinstead.
ThereareseveralwaystocreateaSOAPElement.Thesimplestwayistouseone
oftheaddChildElement()methodsofanexistingSOAPElement,suchas

SOAPBody,whichbothcreatesanewelementandmakesitachildoftheoriginal
element.Therearefivevariantsofthismethod.
TheaddChildElement(Namename)methodcreatesanewelementwhose
nameandnamespaceprefixaretakenfromthesuppliedNameobject.A
namespacedeclarationlinkingthenamespaceprefixtothenamespaceURI
fromtheNameobjectisalsoaddedtotheelement.IftheNameobjectdoes
nothaveanexplicitnamespace,thenneitherthenamespaceprefixnorthe
namespacedeclarationappearsontheelement.
TheaddChildElement(StringlocalName)methodcreatesanelement
whosenameissuppliedbythelocalNameargumentandhasnoexplicit
namespace.Theelementisthereforeinthedefaultnamespacedeclaredby
thenearestancestorthathasanxlmns:namespacedeclaration,oritis
declaredbyitselfifsuchadeclarationisaddedusingthe
addNamespaceDeclaration()method.
TheaddChildElement(StringlocalName,Stringprefix,String
uri)methodcreatesanelementinwhichthename,namespaceprefix,and
namespaceURIareobtainedfromthemethodarguments.Anamespace
declarationlinkingtheprefixandURIareincluded.Forexample,the
methodcalladdChildElement("BookQuery","book",
"urn:BookService")wouldcreateanelementthatwouldbeserializedas
book:BookQueryxmlns:book="urn:BookService".
TheaddChildElement(StringlocalName,Stringprefix)method
createsanelementwiththegivenlocalnameandnamespaceprefix.A
mappingfromthegivenprefixtoaURImusthavebeenprovidedbyan
ancestorofthenewlycreatedelement,oraSOAPExceptionisthrown.


TheaddChildElement(SOAPElementelement)methodaddseitheran
existingelementoracopyofthatelement(andanychildelementsitmight
have)asachildoftheelementonwhichitisinvoked.Thespecificationof

thismethodwarnsthatapplicationcodeshouldnotassumethattheelement
itselfisadded,andacopyisactuallyaddedinthereference
implementation.
AlloftheaddChildElement()methodsreturnareferencetotheSOAPElement
thatwascreatedand/oradded.Thiscanbeusefulifyouwanttocreateseveral
nestedelementsinasinglelineofcode:
body.addChildElement("Level1").addChildElement("Level2").
addChildElement("Level3").addTextNode("Text");

Thiscodeaddsthreelevelsofnestedelements.TheaddTextNode()addsthe
textpassedtoitbelowtheSOAPElementonwhichitiscalledandreturnsa
referencetothatSOAPElement.Theresultofexecutingthiscodeisthefollowing:
<Level1>
<Level2>
<Level3>Text</Level3>
</Level2>
</Level1>
SOAPElementprovidesagroupofmethodsthatallowyoutoaddandmanipulate
attributes.TheaddAttribute()methodaddsanattributewhosenameand
namespaceprefixaregivenbytheNameargumentandequatesittothesupplied
attributevalue.IftheNameobjectdoesnothaveanassociatednamespace,then
nonamespaceprefixappearsintheserializedXML.ThesetEncodingStyle()

methodisaconveniencemethodthatallowsyoutosettheattributethat
representstheSOAPencodingstylethatappliestoanelementandits
descendentswithouthavingtoexplicitlynametheattribute.Thefollowingcode
extractsetsthedefaultSOAPencodingrules:
element.setEncodingStyle(SOAPConstants.URI_NS_SOAP_ENCODING);

ThegetEncodingStyle()methodreturnstheencodingstylesetfortheelement

onwhichitisinvoked.Notethatthismethoddoesnotsearchtheancestorsofthe
elementforaninheritedencodingstyleiftheelementitselfdoesnotspecifyone
—itsimplyreturnsnull.ThegetAttributeValue()methodcanbeusedto
obtainthevalueofanattributegivenitsName.Ifthegivenattributeisnot


present,thennullisreturned.YoucangetanIteratorcontainingaNameobject
foreachattributeattachedtoanelementbycallingthegetAllAttributes()
method,andyoucanremoveanattributewithremoveAttribute().
ThefinalgroupofSOAPElementmethodshandlesnamespaces.
addNamespaceDeclaration()addsanamespacedeclarationtotheelementthat
linksthegivennamespaceprefixtoitsURI.Forexample,thefollowingcode
linksthenamespaceprefixbooktotheURIurn:BookServiceforthescopeof
theelementreferredtobytheelementvariableanditschildelements:
element.addNamespaceDeclaration("book","urn:BookService");

TheserializedXMLforthiselementlookslikethis,assumingtheelementis
calledBookName:
<BookNamexmlns:book="urn:BookService"/>

Iftheprefixissuppliedastheemptystring,thenadeclarationofthedefault
namespaceisbeingmade(i.e.,xmlns="urn:BookService").The
removeNamespaceDeclaration()methodremovesanamespacedeclaration
fromanelementgivenitsnamespaceprefix.ThegetNamespacePrefixes()
methodreturnsanIteratorinwhicheachelementisastringthatrepresentsthe
prefixofanamespacedeclarationattachedtotheelementonwhichitisinvoked.
TogetthenamespaceURIforagivenprefix,usethegetNamespaceURI()
method.

Implementations

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

PassedTo
Node.setParentElement(),SOAPElement.addChildElement()

ReturnedBy
Node.getParentElement(),SOAPElement.{addAttribute(),


addChildElement(),addNamespaceDeclaration(),addTextNode()},
SOAPElementFactory.create(),SOAPFactory.createElement()