saaj3.html

j2eePDF格式的电子书

<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
Name attributeName = envelope.createName(&quot;id&quot;);
person.addAttribute(attributeName, &quot;Person7&quot;);<a name="wp75637"> </a>
</pre></div>
<a name="wp75638"> </a><p class="pBody">
These lines of code will generate the first line in the following XML fragment.
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
&lt;person id=&quot;Person7&quot;&gt;
  ...
&lt;/person&gt;<a name="wp75659"> </a>
</pre></div>
<a name="wp75565"> </a><p class="pBody">
The following line of code retrieves the value of the attribute whose name is <code class="cCode">id</code>.
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
String attributeValue = 
&nbsp;&nbsp;person.getAttributeValue(attributeName);<a name="wp75706"> </a>
</pre></div>
<a name="wp79768"> </a><p class="pBody">
If you had added two or more attributes to <code class="cCode">person</code>, the previous line of code would have returned only the value for the attribute named <code class="cCode">id</code>. If you wanted to retrieve the values for all of the attributes for <code class="cCode">person</code>, you would use the method <code class="cCode">getAllAttributes</code>, which returns an iterator over all of the values. The following lines of code retrieve and print out each value on a separate line until there are no more attribute values. Note that the method <code class="cCode">Iterator.next</code> returns a Java <code class="cCode">Object</code>, which is cast to a <code class="cCode">Name</code> object so that it can be assigned to the <code class="cCode">Name</code> object <code class="cCode">attributeName</code>. (The examples in <a  href="SAAJ4.html#wp88886">DOMExample.java and DomSrcExample.java</a> use code similar to this.)
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
Iterator iterator = person.getAllAttributes();
while (iterator.hasNext()){
&nbsp;&nbsp;Name attributeName = (Name) iterator.next();
&nbsp;&nbsp;System.out.println(&quot;Attribute name is &quot; + 
&nbsp;&nbsp;&nbsp;&nbsp;attributeName.getQualifiedName());
&nbsp;&nbsp;System.out.println(&quot;Attribute value is &quot; + 
&nbsp;&nbsp;&nbsp;&nbsp;element.getAttributeValue(attributeName));
}<a name="wp79774"> </a>
</pre></div>
<a name="wp79770"> </a><p class="pBody">
The following line of code removes the attribute named <code class="cCode">id</code> from <code class="cCode">person</code>. The variable <code class="cCode">successful</code> will be <code class="cCode">true</code> if the attribute was removed successfully.
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
boolean successful = person.removeAttribute(attributeName);<a name="wp75729"> </a>
</pre></div>
<a name="wp76002"> </a><p class="pBody">
In this section you saw how to add, retrieve, and remove attributes. This information is general in that it applies to any element. The next section discusses attributes that may be added only to header elements.
</p>
<a name="wp75707"> </a><h4 class="pHeading3">
Header Attributes
</h4>
<a name="wp75698"> </a><p class="pBody">
Attributes that appear in a <code class="cCode">SOAPHeaderElement</code> object determine how a recipient processes a message. You can think of header attributes as offering a way to extend a message, giving information about such things as authentication, transaction management, payment, and so on. A header attribute refines the meaning of the header, while the header refines the meaning of the message contained in the SOAP Body.
</p>
<a name="wp76021"> </a><p class="pBody">
The SOAP 1.1 specification defines two attributes that can appear only in <code class="cCode">SOAPHeaderElement</code> objects: <code class="cCode">actor</code> and <code class="cCode">mustUnderstand</code>. The next two sections discuss these attributes. 
</p>
<a name="wp87601"> </a><p class="pBody">
See <a  href="SAAJ4.html#wp71229">HeaderExample.java</a> for an example that uses the code shown in this section.
</p>
<a name="wp75563"> </a><h5 class="pHeading4">
The Actor Attribute
</h5>
<a name="wp75566"> </a><p class="pBody">
The attribute <code class="cCode">actor</code> is optional, but if it is used, it must appear in a <code class="cCode">SOAPHeaderElement</code> object. Its purpose is to indicate the recipient of a header element. The default actor is the message's ultimate recipient; that is, if no actor attribute is supplied, the message goes directly to the ultimate recipient. 
</p>
<a name="wp75944"> </a><p class="pBody">
An actor is an application that can both receive SOAP messages and forward them to the next actor. The ability to specify one or more actors as intermediate recipients makes it possible to route a message to multiple recipients and to supply header information that applies specifically to each of the recipients. 
</p>
<a name="wp75618"> </a><p class="pBody">
For example, suppose that a message is an incoming purchase order. Its <code class="cCode">SOAPHeader</code> object might have <code class="cCode">SOAPHeaderElement</code> objects with actor attributes that route the message to applications that function as the order desk, the shipping desk, the confirmation desk, and the billing department. Each of these applications will take the appropriate action, remove the <code class="cCode">SOAPHeaderElement</code> objects relevant to it, and send the message on to the next actor.
</p>
<hr>
<a name="wp75849"> </a><p class="pNote">
Note: Although the SAAJ API provides the API for adding these attributes, it does not supply the API for processing them. For example, the actor attribute requires that there be an implementation such as a messaging provider service to route the message from one actor to the next. 
</p>
<hr><a name="wp75752"> </a><p class="pBody">
An actor is identified by its URI. For example, the following line of code, in which <code class="cCode">orderHeader</code> is a <code class="cCode">SOAPHeaderElement</code> object, sets the actor to the given URI.
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
orderHeader.setActor(&quot;http://gizmos.com/orders&quot;);<a name="wp75753"> </a>
</pre></div>
<a name="wp75775"> </a><p class="pBody">
Additional actors may be set in their own <code class="cCode">SOAPHeaderElement</code> objects. The following code fragment first uses the <code class="cCode">SOAPMessage</code> object <code class="cCode">message</code> to get its <code class="cCode">SOAPHeader</code> object <code class="cCode">header</code>. Then <code class="cCode">header</code> creates four <code class="cCode">SOAPHeaderElement</code> objects, each of which sets its <code class="cCode">actor</code> attribute.
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
SOAPHeader header = message.getSOAPHeader();
SOAPFactory soapFactory = SOAPFactory.newInstance();

String nameSpace = &quot;ns&quot;;
String nameSpaceURI = &quot;http://gizmos.com/NSURI&quot;;

Name order = soapFactory.createName(&quot;orderDesk&quot;,
&nbsp;&nbsp;nameSpace, nameSpaceURI);
SOAPHeaderElement orderHeader =
&nbsp;&nbsp;header.addHeaderElement(order);
orderHeader.setActor(&quot;http://gizmos.com/orders&quot;);

Name shipping = 
&nbsp;&nbsp;soapFactory.createName(&quot;shippingDesk&quot;,
&nbsp;&nbsp;&nbsp;&nbsp;nameSpace, nameSpaceURI);
SOAPHeaderElement shippingHeader =
&nbsp;&nbsp;header.addHeaderElement(shipping);
shippingHeader.setActor(&quot;http://gizmos.com/shipping&quot;);

Name confirmation = 
&nbsp;&nbsp;soapFactory.createName(&quot;confirmationDesk&quot;,
&nbsp;&nbsp;&nbsp;&nbsp;nameSpace, nameSpaceURI);
SOAPHeaderElement confirmationHeader =
&nbsp;&nbsp;header.addHeaderElement(confirmation);
confirmationHeader.setActor(
&nbsp;&nbsp;&quot;http://gizmos.com/confirmations&quot;);

Name billing = soapFactory.createName(&quot;billingDesk&quot;,
&nbsp;&nbsp;nameSpace, nameSpaceURI);
SOAPHeaderElement billingHeader =
&nbsp;&nbsp;header.addHeaderElement(billing);
billingHeader.setActor(&quot;http://gizmos.com/billing&quot;);<a name="wp80125"> </a>
</pre></div>
<a name="wp75877"> </a><p class="pBody">
The <code class="cCode">SOAPHeader</code> interface provides two methods that return a <code class="cCode">java.util.Iterator</code> object over all of the <code class="cCode">SOAPHeaderElement</code> objects with an actor that matches the specified actor. The first method, <code class="cCode">examineHeaderElements</code>, returns an iterator over all of the elements with the specified actor.
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
java.util.Iterator headerElements =
&nbsp;&nbsp;header.examineHeaderElements(&quot;http://gizmos.com/orders&quot;);<a name="wp75886"> </a>
</pre></div>
<a name="wp75892"> </a><p class="pBody">
The second method, <code class="cCode">extractHeaderElements</code>, not only returns an iterator over all of the <code class="cCode">SOAPHeaderElement</code> objects with the specified actor attribute but also detaches them from the <code class="cCode">SOAPHeader</code> object. So, for example, after the order desk application has done its work, it would call <code class="cCode">extractHeaderElements</code> to remove all of the <code class="cCode">SOAPHeaderElement</code> objects that applied to it.
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
java.util.Iterator headerElements =
&nbsp;&nbsp;header.extractHeaderElements(&quot;http://gizmos.com/orders&quot;);<a name="wp75901"> </a>
</pre></div>
<a name="wp76035"> </a><p class="pBody">
Each <code class="cCode">SOAPHeaderElement</code> object may have only one actor attribute, but the same actor may be an attribute for multiple <code class="cCode">SOAPHeaderElement</code> objects.
</p>
<a name="wp79831"> </a><p class="pBody">
Two additional <code class="cCode">SOAPHeader</code> methods, <code class="cCode">examineAllHeaderElements</code> and <code class="cCode">extractAllHeaderElements</code>, allow you to examine or extract all the header elements, whether or not they have an actor attribute. For example, you could use the following code to display the values of all the header elements:
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
Iterator allHeaders = 
&nbsp;&nbsp;header.examineAllHeaderElements();
while (allHeaders.hasNext()) {
&nbsp;&nbsp;SOAPHeaderElement headerElement = 
&nbsp;&nbsp;&nbsp;&nbsp;(SOAPHeaderElement)allHeaders.next();
&nbsp;&nbsp;Name headerName = 
&nbsp;&nbsp;&nbsp;&nbsp;headerElement.getElementName();
&nbsp;&nbsp;System.out.println(&quot;\nHeader name is &quot; + 
&nbsp;&nbsp;&nbsp;&nbsp;headerName.getQualifiedName());
&nbsp;&nbsp;System.out.println(&quot;Actor is &quot; + 
&nbsp;&nbsp;&nbsp;&nbsp;headerElement.getActor());
}<a name="wp80152"> </a>
</pre></div>
<a name="wp75564"> </a><h5 class="pHeading4">
The mustUnderstand Attribute
</h5>
<a name="wp75910"> </a><p class="pBody">
The other attribute that must be added only to a <code class="cCode">SOAPHeaderElement</code> object is <code class="cCode">mustUnderstand</code>. This attribute says whether or not the recipient (indicated by the <code class="cCode">actor</code> attribute) is required to process a header entry. When the value of the <code class="cCode">mustUnderstand</code> attribute is <code class="cCode">true</code>, the actor must understand the semantics of the header entry and must process it correctly to those semantics. If the value is <code class="cCode">false</code>, processing the header entry is optional. A <code class="cCode">SOAPHeaderElement</code> object with no <code class="cCode">mustUnderstand</code> attribute is equivalent to one with a <code class="cCode">mustUnderstand</code> attribute whose value is <code class="cCode">false</code>.
</p>
<a name="wp76048"> </a><p class="pBody">
The <code class="cCode">mustUnderstand</code> attribute is used to call attention to the fact that the semantics in an element are different from the semantics in its parent or peer elements. This allows for robust evolution, ensuring that the change in semantics will not be silently ignored by those who may not fully understand it.
</p>
<a name="wp76637"> </a><p class="pBody">
If the actor for a header that has a <code class="cCode">mustUnderstand</code> attribute set to <code class="cCode">true</code> cannot process the header, it must send a SOAP fault back to the sender. (See the section <a