saaj3.html

j2eePDF格式的电子书

Adding Content to the Body
</h4>
<a name="wp64045"> </a><p class="pBody">
To add content to the body, you need to create a <code class="cCode">SOAPBodyElement</code> object to hold the content. When you create any new element, you also need to create an associated <code class="cCode">Name</code> object so that it is uniquely identified. 
</p>
<a name="wp78002"> </a><p class="pBody">
One way to create <code class="cCode">Name</code> objects is by using <code class="cCode">SOAPEnvelope</code> methods, so you can use the variable <code class="cCode">envelope</code> from the previous code fragment to create the <code class="cCode">Name</code> object for your new element. Another way to create <code class="cCode">Name</code> objects is to use <code class="cCode">SOAPFactory</code> methods, which are useful if you do not have access to the <code class="cCode">SOAPEnvelope</code>. 
</p>
<hr>
<a name="wp78022"> </a><p class="pNote">
Note: The <code class="cCode">SOAPFactory</code> class also lets you create XML elements when you are not creating an entire message or do not have access to a complete <code class="cCode">SOAPMessage</code> object. For example, JAX-RPC implementations often work with XML fragments rather than complete <code class="cCode">SOAPMessage</code> objects. Consequently, they do not have access to a <code class="cCode">SOAPEnvelope</code> object, which makes using a <code class="cCode">SOAPFactory</code> object to create <code class="cCode">Name</code> objects very useful. In addition to a method for creating <code class="cCode">Name</code> objects, the <code class="cCode">SOAPFactory</code> class provides methods for creating <code class="cCode">Detail</code> objects and SOAP fragments. You will find an explanation of <code class="cCode">Detail</code> objects in the SOAP Fault sections <a  href="SAAJ3.html#wp71082">Overview of SOAP Faults</a> and <a  href="SAAJ3.html#wp69922">Creating and Populating a SOAPFault Object</a>.
</p>
<hr><a name="wp64046"> </a><p class="pBody">
<code class="cCode">Name</code> objects associated with <code class="cCode">SOAPBodyElement</code> or <code class="cCode">SOAPHeaderElement</code> objects must be fully qualified; that is, they must be created with a local name, a prefix for the namespace being used, and a URI for the namespace. Specifying a namespace for an element makes clear which one is meant if there is more than one element with the same local name.
</p>
<a name="wp64047"> </a><p class="pBody">
The code fragment that follows retrieves the <code class="cCode">SOAPBody</code> object <code class="cCode">body</code> from <code class="cCode">message</code>, uses a <code class="cCode">SOAPFactory</code> to create a <code class="cCode">Name</code> object for the element to be added, and adds a new <code class="cCode">SOAPBodyElement</code> object to <code class="cCode">body</code>.
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
SOAPBody body = message.getSOAPBody();
SOAPFactory soapFactory = SOAPFactory.newInstance();
Name bodyName = soapFactory.createName(&quot;GetLastTradePrice&quot;,
&nbsp;&nbsp;&quot;m&quot;, &quot;http://wombat.ztrade.com&quot;);
SOAPBodyElement bodyElement = body.addBodyElement(bodyName);<a name="wp64048"> </a>
</pre></div>
<a name="wp64049"> </a><p class="pBody">
At this point, <code class="cCode">body</code> contains a <code class="cCode">SOAPBodyElement</code> object identified by the <code class="cCode">Name</code> object <code class="cCode">bodyName</code>, but there is still no content in <code class="cCode">bodyElement</code>. Assuming that you want to get a quote for the stock of Sun Microsystems, Inc., you need to create a child element for the symbol using the method <code class="cCode">addChildElement</code>. Then you need to give it the stock symbol using the method <code class="cCode">addTextNode</code>. The <code class="cCode">Name</code> object for the new <code class="cCode">SOAPElement</code> object <code class="cCode">symbol</code> is initialized with only a local name because child elements inherit the prefix and URI from the parent element.
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
Name name = soapFactory.createName(&quot;symbol&quot;);
SOAPElement symbol = bodyElement.addChildElement(name);
symbol.addTextNode(&quot;SUNW&quot;);<a name="wp64050"> </a>
</pre></div>
<a name="wp64051"> </a><p class="pBody">
You might recall that the headers and content in a <code class="cCode">SOAPPart</code> object must be in XML format. The SAAJ API takes care of this for you, building the appropriate XML constructs automatically when you call methods such as <code class="cCode">addBodyElement</code>, <code class="cCode">addChildElement</code>, and <code class="cCode">addTextNode</code>. Note that you can call the method <code class="cCode">addTextNode</code> only on an element such as <code class="cCode">bodyElement</code> or any child elements that are added to it. You cannot call <code class="cCode">addTextNode</code> on a <code class="cCode">SOAPHeader</code> or <code class="cCode">SOAPBody</code> object because they contain elements, not text.
</p>
<a name="wp64052"> </a><p class="pBody">
The content that you have just added to your <code class="cCode">SOAPBody</code> object will look like the following when it is sent over the wire: 
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
&lt;SOAP-ENV:Envelope
 xmlns:SOAP-ENV=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;&gt;
  &lt;SOAP-ENV:Body&gt;
    &lt;m:GetLastTradePrice xmlns:m=&quot;http://wombat.ztrade.com&quot;&gt;
      &lt;symbol&gt;SUNW&lt;/symbol&gt;
    &lt;/m:GetLastTradePrice&gt;
  &lt;/SOAP-ENV:Body&gt;
&lt;/SOAP-ENV:Envelope&gt;<a name="wp64053"> </a>
</pre></div>
<a name="wp64054"> </a><p class="pBody">
Let's examine this XML excerpt line by line to see how it relates to your SAAJ code. Note that an XML parser does not care about indentations, but they are generally used to indicate element levels and thereby make it easier for a human reader to understand.
</p>
<a name="wp64055"> </a><p class="pBody">
SAAJ code:
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
SOAPMessage message = messageFactory.createMessage();
SOAPHeader header = message.getSOAPHeader();
SOAPBody body = message.getSOAPBody();<a name="wp64056"> </a>
</pre></div>
<a name="wp64057"> </a><p class="pBody">
XML it produces:
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
&lt;SOAP-ENV:Envelope
 xmlns:SOAP-ENV=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;&gt;
  &lt;SOAP-ENV:Header/&gt;
  &lt;SOAP-ENV:Body&gt;
    . . .
  &lt;/SOAP-ENV:Body&gt;
&lt;/SOAP-ENV:Envelope&gt;<a name="wp78557"> </a>
</pre></div>
<a name="wp64059"> </a><p class="pBody">
The outermost element in this XML example is the SOAP envelope element, indicated by <code class="cCode">SOAP-ENV:Envelope</code>. <code class="cCode">Envelope</code> is the name of the element, and <code class="cCode">SOAP-ENV</code> is the namespace prefix. The interface <code class="cCode">SOAPEnvelope</code> represents a SOAP envelope. 
</p>
<a name="wp64060"> </a><p class="pBody">
The first line signals the beginning of the SOAP envelope element, and the last line signals the end of it; everything in between is part of the SOAP envelope. The second line is an example of an attribute for the SOAP envelope element. Because a SOAP Envelope element always contains this attribute with this value, a <code class="cCode">SOAPMessage</code> object comes with it automatically included. <code class="cCode">xmlns</code> stands for &quot;XML namespace,&quot; and its value is the URI of the namespace associated with <code class="cCode">Envelope</code>. 
</p>
<a name="wp78562"> </a><p class="pBody">
The next line is an empty SOAP header. We could remove it by calling <code class="cCode">header.detachNode</code> after the <code class="cCode">getSOAPHeader</code> call.
</p>
<a name="wp64065"> </a><p class="pBody">
The next two lines mark the beginning and end of the SOAP body, represented in SAAJ by a <code class="cCode">SOAPBody</code> object. The next step is to add content to the body.
</p>
<a name="wp64066"> </a><p class="pBody">
SAAJ code:
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
Name bodyName = soapFactory.createName(&quot;GetLastTradePrice&quot;,
&nbsp;&nbsp;&quot;m&quot;, &quot;http://wombat.ztrade.com&quot;);
SOAPBodyElement bodyElement = body.addBodyElement(bodyName);<a name="wp64067"> </a>
</pre></div>
<a name="wp64068"> </a><p class="pBody">
XML it produces:
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
&lt;m:GetLastTradePrice
 xmlns:m=&quot;http://wombat.ztrade.com&quot;&gt;
 . . . .
&lt;/m:GetLastTradePrice&gt;<a name="wp64070"> </a>
</pre></div>
<a name="wp64071"> </a><p class="pBody">
These lines are what the <code class="cCode">SOAPBodyElement</code> <code class="cCode">bodyElement</code> in your code represents. <code class="cCode">GetLastTradePrice</code>&quot;is its local name, <code class="cCode">m</code> is its namespace prefix, and <code class="cCode">http://wombat.ztrade.com</code> is its namespace URI.
</p>
<a name="wp64072"> </a><p class="pBody">
SAAJ code:
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
<code class="cCode">Name name = soapFactory.createName(&quot;symbol&quot;);
SOAPElement symbol = bodyElement.addChildElement(name);
symbol.addTextNode(&quot;SUNW&quot;)</code>;<a name="wp64073"> </a>
</pre></div>
<a name="wp64074"> </a><p class="pBody">
XML it produces:
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
&lt;symbol&gt;SUNW&lt;/symbol&gt;<a name="wp64075"> </a>
</pre></div>
<a name="wp64673"> </a><p class="pBody">
The <code class="cCode">String</code> <code class="cCode">&quot;SUNW&quot;</code> is the text node for the element <code class="cCode">&lt;symbol&gt;</code>. This <code class="cCode">String</code> object is the message content that your recipient, the stock quote service, receives.
</p>
<a name="wp78656"> </a><h4 class="pHeading3">
Getting a SOAPConnection Object
</h4>
<a name="wp78657"> </a><p class="pBody">
The SAAJ API is focused primarily on creating messages. Once you have a message, you can send it using various mechanisms (JMS or JAXM, for example). The SAAJ API does, however, provide a simple mechanism for request-response messaging. 
</p>
<a name="wp78692"> </a><p class="pBody">
To send a message, a SAAJ client may use a <code class="cCode">SOAPConnection</code> object. A <code class="cCode">SOAPConnection</code> object is a point-to-point connection, meaning that it goes directly from the sender to the destination (usually a URL) that the sender specifies.
</p>
<a name="wp78660"> </a><p class="pBody">
The first step is to obtain a <code class="cCode">SOAPConnectionFactory</code> object that you can use to create your connection. The SAAJ API makes this easy by providing the <code class="cCode">SOAPConnectionFactory</code> class with a default implementation. You can get an instance of this implementation with the following line of code.
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
SOAPConnectionFactory soapConnectionFactory = 
&nbsp;&nbsp;SOAPConnectionFactory.newInstance();<a name="wp78661"> </a>
</pre></div>
<a name="wp78662"> </a><p class="pBody">
Now you can use <code class="cCode">soapConnectionFactory</code> to create a <code class="cCode">SOAPConnection</code> object.
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
SOAPConnection connection = 
&nbsp;&nbsp;soapConnectionFactory.createConnection();<a name="wp78663"> </a>
</pre></div>
<a name="wp78664"> </a><p class="pBody">
You will use <code class="cCode">connection</code> to send the message that you created.
</p>
<a name="wp78665"> </a><h4 class="pHeading3">
Sending a Message
</h4>
<a name="wp78668"> </a><p class="pBody">
A SAAJ client calls the <code class="cCode">SOAPConnection</code> method <code class="cCode">call</code> on a <code class="cCode">SOAPConnection</code> object to send a message. The <code class="cCode">call</code> method takes two arguments, the message being sent and the destination to which the message should go. This message is going to the stock quote service indicated by the <code class="cCode">URL</code> object <code class="cCode">endpoint</code>.
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
java.net.URL endpoint = new URL(
&nbsp;&nbsp;&quot;http://wombat.ztrade.com/quotes&quot;);