325N/A * Copyright (c) 2004, 2011, Oracle and/or its affiliates. All rights reserved. 325N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 325N/A * This code is free software; you can redistribute it and/or modify it 325N/A * under the terms of the GNU General Public License version 2 only, as 325N/A * published by the Free Software Foundation. Oracle designates this 325N/A * particular file as subject to the "Classpath" exception as provided 325N/A * by Oracle in the LICENSE file that accompanied this code. 325N/A * This code is distributed in the hope that it will be useful, but WITHOUT 325N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 325N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 325N/A * version 2 for more details (a copy is included in the LICENSE file that 325N/A * accompanied this code). 325N/A * You should have received a copy of the GNU General Public License version 325N/A * 2 along with this work; if not, write to the Free Software Foundation, 325N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 325N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 325N/A * or visit www.oracle.com if you need additional information or have any 325N/A * The container for the SOAPHeader and SOAPBody portions of a 325N/A * <code>SOAPPart</code> object. By default, a <code>SOAPMessage</code> 325N/A * object is created with a <code>SOAPPart</code> object that has a 325N/A * <code>SOAPEnvelope</code> object. The <code>SOAPEnvelope</code> object 325N/A * by default has an empty <code>SOAPBody</code> object and an empty 325N/A * <code>SOAPHeader</code> object. The <code>SOAPBody</code> object is 325N/A * required, and the <code>SOAPHeader</code> object, though 325N/A * optional, is used in the majority of cases. If the 325N/A * <code>SOAPHeader</code> object is not needed, it can be deleted, 325N/A * which is shown later. 325N/A * A client can access the <code>SOAPHeader</code> and <code>SOAPBody</code> 325N/A * objects by calling the methods <code>SOAPEnvelope.getHeader</code> and 325N/A * <code>SOAPEnvelope.getBody</code>. The 325N/A * following lines of code use these two methods after starting with 325N/A * the <code>SOAPMessage</code> 325N/A * object <i>message</i> to get the <code>SOAPPart</code> object <i>sp</i>, 325N/A * which is then used to get the <code>SOAPEnvelope</code> object <i>se</i>. 325N/A * SOAPPart sp = message.getSOAPPart(); 325N/A * SOAPEnvelope se = sp.getEnvelope(); 325N/A * SOAPHeader sh = se.getHeader(); 325N/A * SOAPBody sb = se.getBody(); 325N/A * It is possible to change the body or header of a <code>SOAPEnvelope</code> 325N/A * object by retrieving the current one, deleting it, and then adding 325N/A * <code>deleteNode</code> deletes the XML element (node) on which it is 325N/A * called. For example, the following line of code deletes the 325N/A * <code>SOAPBody</code> object that is retrieved by the method <code>getBody</code>. 325N/A * se.getBody().detachNode(); 325N/A * To create a <code>SOAPHeader</code> object to replace the one that was removed, 325N/A * the method <code>SOAPEnvelope.addHeader</code>, which creates a new header and 325N/A * adds it to the <code>SOAPEnvelope</code> object. Similarly, the method 325N/A * <code>addBody</code> creates a new <code>SOAPBody</code> object and adds 325N/A * it to the <code>SOAPEnvelope</code> object. The following code fragment 325N/A * retrieves the current header, removes it, and adds a new one. Then 325N/A * it retrieves the current body, removes it, and adds a new one. 325N/A * SOAPPart sp = message.getSOAPPart(); 325N/A * SOAPEnvelope se = sp.getEnvelope(); 325N/A * se.getHeader().detachNode(); 325N/A * SOAPHeader sh = se.addHeader(); 325N/A * se.getBody().detachNode(); 325N/A * SOAPBody sb = se.addBody(); 325N/A * It is an error to add a <code>SOAPBody</code> or <code>SOAPHeader</code> 325N/A * object if one already exists. 325N/A * The <code>SOAPEnvelope</code> interface provides three methods for creating 325N/A * <code>Name</code> objects. One method creates <code>Name</code> objects with 325N/A * a local name, a namespace prefix, and a namesapce URI. The second method creates 325N/A * <code>Name</code> objects with a local name and a namespace prefix, and the third 325N/A * creates <code>Name</code> objects with just a local name. The following line of 325N/A * code, in which <i>se</i> is a <code>SOAPEnvelope</code> object, creates a new 325N/A * <code>Name</code> object with all three. 325N/A * Name name = se.createName("GetLastTradePrice", "WOMBAT", 325N/A * Creates a new <code>Name</code> object initialized with the 325N/A * given local name, namespace prefix, and namespace URI. 325N/A * This factory method creates <code>Name</code> objects for use in 325N/A * @param localName a <code>String</code> giving the local name 325N/A * @param prefix a <code>String</code> giving the prefix of the namespace 325N/A * @param uri a <code>String</code> giving the URI of the namespace 325N/A * @return a <code>Name</code> object initialized with the given 325N/A * local name, namespace prefix, and namespace URI 325N/A * @throws SOAPException if there is a SOAP error 325N/A * Creates a new <code>Name</code> object initialized with the 325N/A * This factory method creates <code>Name</code> objects for use in 325N/A * @param localName a <code>String</code> giving the local name 325N/A * @return a <code>Name</code> object initialized with the given 325N/A * @throws SOAPException if there is a SOAP error 325N/A * Returns the <code>SOAPHeader</code> object for 325N/A * this <code>SOAPEnvelope</code> object. 325N/A * A new <code>SOAPMessage</code> object is by default created with a 325N/A * <code>SOAPEnvelope</code> object that contains an empty 325N/A * <code>SOAPHeader</code> object. As a result, the method 325N/A * <code>getHeader</code> will always return a <code>SOAPHeader</code> 325N/A * object unless the header has been removed and a new one has not 325N/A * @return the <code>SOAPHeader</code> object or <code>null</code> if 325N/A * @exception SOAPException if there is a problem obtaining the 325N/A * <code>SOAPHeader</code> object 325N/A * Returns the <code>SOAPBody</code> object associated with this 325N/A * <code>SOAPEnvelope</code> object. 325N/A * A new <code>SOAPMessage</code> object is by default created with a 325N/A * <code>SOAPEnvelope</code> object that contains an empty 325N/A * <code>SOAPBody</code> object. As a result, the method 325N/A * <code>getBody</code> will always return a <code>SOAPBody</code> 325N/A * object unless the body has been removed and a new one has not 325N/A * @return the <code>SOAPBody</code> object for this 325N/A * <code>SOAPEnvelope</code> object or <code>null</code> 325N/A * @exception SOAPException if there is a problem obtaining the 325N/A * <code>SOAPBody</code> object 325N/A * Creates a <code>SOAPHeader</code> object and sets it as the 325N/A * <code>SOAPHeader</code> object for this <code>SOAPEnvelope</code> 325N/A * It is illegal to add a header when the envelope already 325N/A * contains a header. Therefore, this method should be called 325N/A * only after the existing header has been removed. 325N/A * @return the new <code>SOAPHeader</code> object 325N/A * @exception SOAPException if this 325N/A * <code>SOAPEnvelope</code> object already contains a 325N/A * valid <code>SOAPHeader</code> object 325N/A * Creates a <code>SOAPBody</code> object and sets it as the 325N/A * <code>SOAPBody</code> object for this <code>SOAPEnvelope</code> 325N/A * It is illegal to add a body when the envelope already 325N/A * contains a body. Therefore, this method should be called 325N/A * only after the existing body has been removed. 325N/A * @return the new <code>SOAPBody</code> object 325N/A * @exception SOAPException if this 325N/A * <code>SOAPEnvelope</code> object already contains a 325N/A * valid <code>SOAPBody</code> object