Mercurial > jdk8-mips64-public > jaxws / annotate
src/share/jaxws_classes/javax/xml/soap/SOAPEnvelope.java@9c07ef4934dd (annotated)
src/share/jaxws_classes/javax/xml/soap/SOAPEnvelope.java
Thu, 31 Aug 2017 15:18:52 +0800
- author
- aoqi
- date
- Thu, 31 Aug 2017 15:18:52 +0800
- changeset 637
- 9c07ef4934dd
- parent 368
- 0989ad8c0860
- parent 0
- 373ffda63c9a
- permissions
- -rw-r--r--
merge
| aoqi@0 | 1 | /* |
| aoqi@0 | 2 | * Copyright (c) 2004, 2012, Oracle and/or its affiliates. All rights reserved. |
| aoqi@0 | 3 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| aoqi@0 | 4 | * |
| aoqi@0 | 5 | * This code is free software; you can redistribute it and/or modify it |
| aoqi@0 | 6 | * under the terms of the GNU General Public License version 2 only, as |
| aoqi@0 | 7 | * published by the Free Software Foundation. Oracle designates this |
| aoqi@0 | 8 | * particular file as subject to the "Classpath" exception as provided |
| aoqi@0 | 9 | * by Oracle in the LICENSE file that accompanied this code. |
| aoqi@0 | 10 | * |
| aoqi@0 | 11 | * This code is distributed in the hope that it will be useful, but WITHOUT |
| aoqi@0 | 12 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| aoqi@0 | 13 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| aoqi@0 | 14 | * version 2 for more details (a copy is included in the LICENSE file that |
| aoqi@0 | 15 | * accompanied this code). |
| aoqi@0 | 16 | * |
| aoqi@0 | 17 | * You should have received a copy of the GNU General Public License version |
| aoqi@0 | 18 | * 2 along with this work; if not, write to the Free Software Foundation, |
| aoqi@0 | 19 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| aoqi@0 | 20 | * |
| aoqi@0 | 21 | * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| aoqi@0 | 22 | * or visit www.oracle.com if you need additional information or have any |
| aoqi@0 | 23 | * questions. |
| aoqi@0 | 24 | */ |
| aoqi@0 | 25 | |
| aoqi@0 | 26 | package javax.xml.soap; |
| aoqi@0 | 27 | |
| aoqi@0 | 28 | |
| aoqi@0 | 29 | /** |
| aoqi@0 | 30 | * The container for the SOAPHeader and SOAPBody portions of a |
| aoqi@0 | 31 | * <code>SOAPPart</code> object. By default, a <code>SOAPMessage</code> |
| aoqi@0 | 32 | * object is created with a <code>SOAPPart</code> object that has a |
| aoqi@0 | 33 | * <code>SOAPEnvelope</code> object. The <code>SOAPEnvelope</code> object |
| aoqi@0 | 34 | * by default has an empty <code>SOAPBody</code> object and an empty |
| aoqi@0 | 35 | * <code>SOAPHeader</code> object. The <code>SOAPBody</code> object is |
| aoqi@0 | 36 | * required, and the <code>SOAPHeader</code> object, though |
| aoqi@0 | 37 | * optional, is used in the majority of cases. If the |
| aoqi@0 | 38 | * <code>SOAPHeader</code> object is not needed, it can be deleted, |
| aoqi@0 | 39 | * which is shown later. |
| aoqi@0 | 40 | * <P> |
| aoqi@0 | 41 | * A client can access the <code>SOAPHeader</code> and <code>SOAPBody</code> |
| aoqi@0 | 42 | * objects by calling the methods <code>SOAPEnvelope.getHeader</code> and |
| aoqi@0 | 43 | * <code>SOAPEnvelope.getBody</code>. The |
| aoqi@0 | 44 | * following lines of code use these two methods after starting with |
| aoqi@0 | 45 | * the <code>SOAPMessage</code> |
| aoqi@0 | 46 | * object <i>message</i> to get the <code>SOAPPart</code> object <i>sp</i>, |
| aoqi@0 | 47 | * which is then used to get the <code>SOAPEnvelope</code> object <i>se</i>. |
| aoqi@0 | 48 | * |
| aoqi@0 | 49 | * <PRE> |
| aoqi@0 | 50 | * SOAPPart sp = message.getSOAPPart(); |
| aoqi@0 | 51 | * SOAPEnvelope se = sp.getEnvelope(); |
| aoqi@0 | 52 | * SOAPHeader sh = se.getHeader(); |
| aoqi@0 | 53 | * SOAPBody sb = se.getBody(); |
| aoqi@0 | 54 | * </PRE> |
| aoqi@0 | 55 | * <P> |
| aoqi@0 | 56 | * It is possible to change the body or header of a <code>SOAPEnvelope</code> |
| aoqi@0 | 57 | * object by retrieving the current one, deleting it, and then adding |
| aoqi@0 | 58 | * a new body or header. The <code>javax.xml.soap.Node</code> method |
| aoqi@0 | 59 | * <code>deleteNode</code> deletes the XML element (node) on which it is |
| aoqi@0 | 60 | * called. For example, the following line of code deletes the |
| aoqi@0 | 61 | * <code>SOAPBody</code> object that is retrieved by the method <code>getBody</code>. |
| aoqi@0 | 62 | * <PRE> |
| aoqi@0 | 63 | * se.getBody().detachNode(); |
| aoqi@0 | 64 | * </PRE> |
| aoqi@0 | 65 | * To create a <code>SOAPHeader</code> object to replace the one that was removed, |
| aoqi@0 | 66 | * a client uses |
| aoqi@0 | 67 | * the method <code>SOAPEnvelope.addHeader</code>, which creates a new header and |
| aoqi@0 | 68 | * adds it to the <code>SOAPEnvelope</code> object. Similarly, the method |
| aoqi@0 | 69 | * <code>addBody</code> creates a new <code>SOAPBody</code> object and adds |
| aoqi@0 | 70 | * it to the <code>SOAPEnvelope</code> object. The following code fragment |
| aoqi@0 | 71 | * retrieves the current header, removes it, and adds a new one. Then |
| aoqi@0 | 72 | * it retrieves the current body, removes it, and adds a new one. |
| aoqi@0 | 73 | * |
| aoqi@0 | 74 | * <PRE> |
| aoqi@0 | 75 | * SOAPPart sp = message.getSOAPPart(); |
| aoqi@0 | 76 | * SOAPEnvelope se = sp.getEnvelope(); |
| aoqi@0 | 77 | * se.getHeader().detachNode(); |
| aoqi@0 | 78 | * SOAPHeader sh = se.addHeader(); |
| aoqi@0 | 79 | * se.getBody().detachNode(); |
| aoqi@0 | 80 | * SOAPBody sb = se.addBody(); |
| aoqi@0 | 81 | * </PRE> |
| aoqi@0 | 82 | * It is an error to add a <code>SOAPBody</code> or <code>SOAPHeader</code> |
| aoqi@0 | 83 | * object if one already exists. |
| aoqi@0 | 84 | * <P> |
| aoqi@0 | 85 | * The <code>SOAPEnvelope</code> interface provides three methods for creating |
| aoqi@0 | 86 | * <code>Name</code> objects. One method creates <code>Name</code> objects with |
| aoqi@0 | 87 | * a local name, a namespace prefix, and a namesapce URI. The second method creates |
| aoqi@0 | 88 | * <code>Name</code> objects with a local name and a namespace prefix, and the third |
| aoqi@0 | 89 | * creates <code>Name</code> objects with just a local name. The following line of |
| aoqi@0 | 90 | * code, in which <i>se</i> is a <code>SOAPEnvelope</code> object, creates a new |
| aoqi@0 | 91 | * <code>Name</code> object with all three. |
| aoqi@0 | 92 | * <PRE> |
| aoqi@0 | 93 | * Name name = se.createName("GetLastTradePrice", "WOMBAT", |
| aoqi@0 | 94 | * "http://www.wombat.org/trader"); |
| aoqi@0 | 95 | * </PRE> |
| aoqi@0 | 96 | */ |
| aoqi@0 | 97 | public interface SOAPEnvelope extends SOAPElement { |
| aoqi@0 | 98 | |
| aoqi@0 | 99 | /** |
| aoqi@0 | 100 | * Creates a new <code>Name</code> object initialized with the |
| aoqi@0 | 101 | * given local name, namespace prefix, and namespace URI. |
| aoqi@0 | 102 | * <P> |
| aoqi@0 | 103 | * This factory method creates <code>Name</code> objects for use in |
| aoqi@0 | 104 | * the SOAP/XML document. |
| aoqi@0 | 105 | * |
| aoqi@0 | 106 | * @param localName a <code>String</code> giving the local name |
| aoqi@0 | 107 | * @param prefix a <code>String</code> giving the prefix of the namespace |
| aoqi@0 | 108 | * @param uri a <code>String</code> giving the URI of the namespace |
| aoqi@0 | 109 | * @return a <code>Name</code> object initialized with the given |
| aoqi@0 | 110 | * local name, namespace prefix, and namespace URI |
| aoqi@0 | 111 | * @throws SOAPException if there is a SOAP error |
| aoqi@0 | 112 | */ |
| aoqi@0 | 113 | public abstract Name createName(String localName, String prefix, |
| aoqi@0 | 114 | String uri) |
| aoqi@0 | 115 | throws SOAPException; |
| aoqi@0 | 116 | |
| aoqi@0 | 117 | /** |
| aoqi@0 | 118 | * Creates a new <code>Name</code> object initialized with the |
| aoqi@0 | 119 | * given local name. |
| aoqi@0 | 120 | * <P> |
| aoqi@0 | 121 | * This factory method creates <code>Name</code> objects for use in |
| aoqi@0 | 122 | * the SOAP/XML document. |
| aoqi@0 | 123 | * |
| aoqi@0 | 124 | * @param localName a <code>String</code> giving the local name |
| aoqi@0 | 125 | * @return a <code>Name</code> object initialized with the given |
| aoqi@0 | 126 | * local name |
| aoqi@0 | 127 | * @throws SOAPException if there is a SOAP error |
| aoqi@0 | 128 | */ |
| aoqi@0 | 129 | public abstract Name createName(String localName) |
| aoqi@0 | 130 | throws SOAPException; |
| aoqi@0 | 131 | |
| aoqi@0 | 132 | /** |
| aoqi@0 | 133 | * Returns the <code>SOAPHeader</code> object for |
| aoqi@0 | 134 | * this <code>SOAPEnvelope</code> object. |
| aoqi@0 | 135 | * <P> |
| aoqi@0 | 136 | * A new <code>SOAPMessage</code> object is by default created with a |
| aoqi@0 | 137 | * <code>SOAPEnvelope</code> object that contains an empty |
| aoqi@0 | 138 | * <code>SOAPHeader</code> object. As a result, the method |
| aoqi@0 | 139 | * <code>getHeader</code> will always return a <code>SOAPHeader</code> |
| aoqi@0 | 140 | * object unless the header has been removed and a new one has not |
| aoqi@0 | 141 | * been added. |
| aoqi@0 | 142 | * |
| aoqi@0 | 143 | * @return the <code>SOAPHeader</code> object or <code>null</code> if |
| aoqi@0 | 144 | * there is none |
| aoqi@0 | 145 | * @exception SOAPException if there is a problem obtaining the |
| aoqi@0 | 146 | * <code>SOAPHeader</code> object |
| aoqi@0 | 147 | */ |
| aoqi@0 | 148 | public SOAPHeader getHeader() throws SOAPException; |
| aoqi@0 | 149 | |
| aoqi@0 | 150 | /** |
| aoqi@0 | 151 | * Returns the <code>SOAPBody</code> object associated with this |
| aoqi@0 | 152 | * <code>SOAPEnvelope</code> object. |
| aoqi@0 | 153 | * <P> |
| aoqi@0 | 154 | * A new <code>SOAPMessage</code> object is by default created with a |
| aoqi@0 | 155 | * <code>SOAPEnvelope</code> object that contains an empty |
| aoqi@0 | 156 | * <code>SOAPBody</code> object. As a result, the method |
| aoqi@0 | 157 | * <code>getBody</code> will always return a <code>SOAPBody</code> |
| aoqi@0 | 158 | * object unless the body has been removed and a new one has not |
| aoqi@0 | 159 | * been added. |
| aoqi@0 | 160 | * |
| aoqi@0 | 161 | * @return the <code>SOAPBody</code> object for this |
| aoqi@0 | 162 | * <code>SOAPEnvelope</code> object or <code>null</code> |
| aoqi@0 | 163 | * if there is none |
| aoqi@0 | 164 | * @exception SOAPException if there is a problem obtaining the |
| aoqi@0 | 165 | * <code>SOAPBody</code> object |
| aoqi@0 | 166 | */ |
| aoqi@0 | 167 | public SOAPBody getBody() throws SOAPException; |
| aoqi@0 | 168 | /** |
| aoqi@0 | 169 | * Creates a <code>SOAPHeader</code> object and sets it as the |
| aoqi@0 | 170 | * <code>SOAPHeader</code> object for this <code>SOAPEnvelope</code> |
| aoqi@0 | 171 | * object. |
| aoqi@0 | 172 | * <P> |
| aoqi@0 | 173 | * It is illegal to add a header when the envelope already |
| aoqi@0 | 174 | * contains a header. Therefore, this method should be called |
| aoqi@0 | 175 | * only after the existing header has been removed. |
| aoqi@0 | 176 | * |
| aoqi@0 | 177 | * @return the new <code>SOAPHeader</code> object |
| aoqi@0 | 178 | * |
| aoqi@0 | 179 | * @exception SOAPException if this |
| aoqi@0 | 180 | * <code>SOAPEnvelope</code> object already contains a |
| aoqi@0 | 181 | * valid <code>SOAPHeader</code> object |
| aoqi@0 | 182 | */ |
| aoqi@0 | 183 | public SOAPHeader addHeader() throws SOAPException; |
| aoqi@0 | 184 | /** |
| aoqi@0 | 185 | * Creates a <code>SOAPBody</code> object and sets it as the |
| aoqi@0 | 186 | * <code>SOAPBody</code> object for this <code>SOAPEnvelope</code> |
| aoqi@0 | 187 | * object. |
| aoqi@0 | 188 | * <P> |
| aoqi@0 | 189 | * It is illegal to add a body when the envelope already |
| aoqi@0 | 190 | * contains a body. Therefore, this method should be called |
| aoqi@0 | 191 | * only after the existing body has been removed. |
| aoqi@0 | 192 | * |
| aoqi@0 | 193 | * @return the new <code>SOAPBody</code> object |
| aoqi@0 | 194 | * |
| aoqi@0 | 195 | * @exception SOAPException if this |
| aoqi@0 | 196 | * <code>SOAPEnvelope</code> object already contains a |
| aoqi@0 | 197 | * valid <code>SOAPBody</code> object |
| aoqi@0 | 198 | */ |
| aoqi@0 | 199 | public SOAPBody addBody() throws SOAPException; |
| aoqi@0 | 200 | } |
