1 /* 2 * Copyright (c) 2004, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.xml.soap; 27 28 import java.util.Locale; 29 30 import org.w3c.dom.Document; 31 32 import javax.xml.namespace.QName; 33 34 /** 35 * An object that represents the contents of the SOAP body 36 * element in a SOAP message. A SOAP body element consists of XML data 37 * that affects the way the application-specific content is processed. 38 * <P> 39 * A <code>SOAPBody</code> object contains <code>SOAPBodyElement</code> 40 * objects, which have the content for the SOAP body. 41 * A <code>SOAPFault</code> object, which carries status and/or 42 * error information, is an example of a <code>SOAPBodyElement</code> object. 43 * 44 * @see SOAPFault 45 */ 46 public interface SOAPBody extends SOAPElement { 47 48 /** 49 * Creates a new <code>SOAPFault</code> object and adds it to 50 * this <code>SOAPBody</code> object. The new <code>SOAPFault</code> will 51 * have default values set for the mandatory child elements. The type of 52 * the <code>SOAPFault</code> will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> 53 * depending on the <code>protocol</code> specified while creating the 54 * <code>MessageFactory</code> instance. 55 * <p> 56 * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code> 57 * child element. 58 * 59 * @return the new <code>SOAPFault</code> object 60 * @exception SOAPException if there is a SOAP error 61 */ 62 public SOAPFault addFault() throws SOAPException; 63 64 65 /** 66 * Creates a new <code>SOAPFault</code> object and adds it to 67 * this <code>SOAPBody</code> object. The type of the 68 * <code>SOAPFault</code> will be a SOAP 1.1 or a SOAP 1.2 69 * <code>SOAPFault</code> depending on the <code>protocol</code> 70 * specified while creating the <code>MessageFactory</code> instance. 71 * <p> 72 * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the 73 * <i>Fault/Code/Value</i> element and the <code>faultString</code> parameter 74 * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1 75 * the <code>faultCode</code> parameter is the value of the <code>faultcode</code> 76 * element and the <code>faultString</code> parameter is the value of the <code>faultstring</code> 77 * element. 78 * <p> 79 * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code> 80 * child element. 81 * 82 * @param faultCode a <code>Name</code> object giving the fault 83 * code to be set; must be one of the fault codes defined in the Version 84 * of SOAP specification in use 85 * @param faultString a <code>String</code> giving an explanation of 86 * the fault 87 * @param locale a {@link java.util.Locale} object indicating 88 * the native language of the <code>faultString</code> 89 * @return the new <code>SOAPFault</code> object 90 * @exception SOAPException if there is a SOAP error 91 * @see SOAPFault#setFaultCode 92 * @see SOAPFault#setFaultString 93 * @since SAAJ 1.2 94 */ 95 public SOAPFault addFault(Name faultCode, String faultString, Locale locale) throws SOAPException; 96 97 /** 98 * Creates a new <code>SOAPFault</code> object and adds it to this 99 * <code>SOAPBody</code> object. The type of the <code>SOAPFault</code> 100 * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on 101 * the <code>protocol</code> specified while creating the <code>MessageFactory</code> 102 * instance. 103 * <p> 104 * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the 105 * <i>Fault/Code/Value</i> element and the <code>faultString</code> parameter 106 * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1 107 * the <code>faultCode</code> parameter is the value of the <code>faultcode</code> 108 * element and the <code>faultString</code> parameter is the value of the <code>faultstring</code> 109 * element. 110 * <p> 111 * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code> 112 * child element. 113 * 114 * @param faultCode 115 * a <code>QName</code> object giving the fault code to be 116 * set; must be one of the fault codes defined in the version 117 * of SOAP specification in use. 118 * @param faultString 119 * a <code>String</code> giving an explanation of the fault 120 * @param locale 121 * a {@link java.util.Locale Locale} object indicating the 122 * native language of the <code>faultString</code> 123 * @return the new <code>SOAPFault</code> object 124 * @exception SOAPException 125 * if there is a SOAP error 126 * @see SOAPFault#setFaultCode 127 * @see SOAPFault#setFaultString 128 * @see SOAPBody#addFault(Name faultCode, String faultString, Locale locale) 129 * 130 * @since SAAJ 1.3 131 */ 132 public SOAPFault addFault(QName faultCode, String faultString, Locale locale) 133 throws SOAPException; 134 135 /** 136 * Creates a new <code>SOAPFault</code> object and adds it to this 137 * <code>SOAPBody</code> object. The type of the <code>SOAPFault</code> 138 * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on 139 * the <code>protocol</code> specified while creating the <code>MessageFactory</code> 140 * instance. 141 * <p> 142 * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the 143 * <i>Fault/Code/Value</i> element and the <code>faultString</code> parameter 144 * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1 145 * the <code>faultCode</code> parameter is the value of the <i>faultcode</i> 146 * element and the <code>faultString</code> parameter is the value of the <i>faultstring</i> 147 * element. 148 * <p> 149 * In case of a SOAP 1.2 fault, the default value for the mandatory <code>xml:lang</code> 150 * attribute on the <i>Fault/Reason/Text</i> element will be set to 151 * <code>java.util.Locale.getDefault()</code> 152 * <p> 153 * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code> 154 * child element. 155 * 156 * @param faultCode 157 * a <code>Name</code> object giving the fault code to be set; 158 * must be one of the fault codes defined in the version of SOAP 159 * specification in use 160 * @param faultString 161 * a <code>String</code> giving an explanation of the fault 162 * @return the new <code>SOAPFault</code> object 163 * @exception SOAPException 164 * if there is a SOAP error 165 * @see SOAPFault#setFaultCode 166 * @see SOAPFault#setFaultString 167 * @since SAAJ 1.2 168 */ 169 public SOAPFault addFault(Name faultCode, String faultString) 170 throws SOAPException; 171 172 /** 173 * Creates a new <code>SOAPFault</code> object and adds it to this <code>SOAPBody</code> 174 * object. The type of the <code>SOAPFault</code> 175 * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on 176 * the <code>protocol</code> specified while creating the <code>MessageFactory</code> 177 * instance. 178 * <p> 179 * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the 180 * <i>Fault/Code/Value</i> element and the <code>faultString</code> parameter 181 * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1 182 * the <code>faultCode</code> parameter is the value of the <i>faultcode</i> 183 * element and the <code>faultString</code> parameter is the value of the <i>faultstring</i> 184 * element. 185 * <p> 186 * In case of a SOAP 1.2 fault, the default value for the mandatory <code>xml:lang</code> 187 * attribute on the <i>Fault/Reason/Text</i> element will be set to 188 * <code>java.util.Locale.getDefault()</code> 189 * <p> 190 * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code> 191 * child element 192 * 193 * @param faultCode 194 * a <code>QName</code> object giving the fault code to be 195 * set; must be one of the fault codes defined in the version 196 * of SOAP specification in use 197 * @param faultString 198 * a <code>String</code> giving an explanation of the fault 199 * @return the new <code>SOAPFault</code> object 200 * @exception SOAPException 201 * if there is a SOAP error 202 * @see SOAPFault#setFaultCode 203 * @see SOAPFault#setFaultString 204 * @see SOAPBody#addFault(Name faultCode, String faultString) 205 * @since SAAJ 1.3 206 */ 207 public SOAPFault addFault(QName faultCode, String faultString) 208 throws SOAPException; 209 210 /** 211 * Indicates whether a <code>SOAPFault</code> object exists in this 212 * <code>SOAPBody</code> object. 213 * 214 * @return <code>true</code> if a <code>SOAPFault</code> object exists 215 * in this <code>SOAPBody</code> object; <code>false</code> 216 * otherwise 217 */ 218 public boolean hasFault(); 219 220 /** 221 * Returns the <code>SOAPFault</code> object in this <code>SOAPBody</code> 222 * object. 223 * 224 * @return the <code>SOAPFault</code> object in this <code>SOAPBody</code> 225 * object if present, null otherwise. 226 */ 227 public SOAPFault getFault(); 228 229 /** 230 * Creates a new <code>SOAPBodyElement</code> object with the specified 231 * name and adds it to this <code>SOAPBody</code> object. 232 * 233 * @param name 234 * a <code>Name</code> object with the name for the new <code>SOAPBodyElement</code> 235 * object 236 * @return the new <code>SOAPBodyElement</code> object 237 * @exception SOAPException 238 * if a SOAP error occurs 239 * @see SOAPBody#addBodyElement(javax.xml.namespace.QName) 240 */ 241 public SOAPBodyElement addBodyElement(Name name) throws SOAPException; 242 243 244 /** 245 * Creates a new <code>SOAPBodyElement</code> object with the specified 246 * QName and adds it to this <code>SOAPBody</code> object. 247 * 248 * @param qname 249 * a <code>QName</code> object with the qname for the new 250 * <code>SOAPBodyElement</code> object 251 * @return the new <code>SOAPBodyElement</code> object 252 * @exception SOAPException 253 * if a SOAP error occurs 254 * @see SOAPBody#addBodyElement(Name) 255 * @since SAAJ 1.3 256 */ 257 public SOAPBodyElement addBodyElement(QName qname) throws SOAPException; 258 259 /** 260 * Adds the root node of the DOM <code>{@link org.w3c.dom.Document}</code> 261 * to this <code>SOAPBody</code> object. 262 * <p> 263 * Calling this method invalidates the <code>document</code> parameter. 264 * The client application should discard all references to this <code>Document</code> 265 * and its contents upon calling <code>addDocument</code>. The behavior 266 * of an application that continues to use such references is undefined. 267 * 268 * @param document 269 * the <code>Document</code> object whose root node will be 270 * added to this <code>SOAPBody</code>. 271 * @return the <code>SOAPBodyElement</code> that represents the root node 272 * that was added. 273 * @exception SOAPException 274 * if the <code>Document</code> cannot be added 275 * @since SAAJ 1.2 276 */ 277 public SOAPBodyElement addDocument(org.w3c.dom.Document document) 278 throws SOAPException; 279 280 /** 281 * Creates a new DOM <code>{@link org.w3c.dom.Document}</code> and sets 282 * the first child of this <code>SOAPBody</code> as it's document 283 * element. The child <code>SOAPElement</code> is removed as part of the 284 * process. 285 * 286 * @return the <code>{@link org.w3c.dom.Document}</code> representation 287 * of the <code>SOAPBody</code> content. 288 * 289 * @exception SOAPException 290 * if there is not exactly one child <code>SOAPElement</code> of the <code> 291 * <code>SOAPBody</code>. 292 * 293 * @since SAAJ 1.3 294 */ 295 public org.w3c.dom.Document extractContentAsDocument() 296 throws SOAPException; 297 }