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 * @since 1.6 46 */ 47 public interface SOAPBody extends SOAPElement { 48 49 /** 50 * Creates a new <code>SOAPFault</code> object and adds it to 51 * this <code>SOAPBody</code> object. The new <code>SOAPFault</code> will 52 * have default values set for the mandatory child elements. The type of 53 * the <code>SOAPFault</code> will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> 54 * depending on the <code>protocol</code> specified while creating the 55 * <code>MessageFactory</code> instance. 56 * <p> 57 * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code> 58 * child element. 59 * 60 * @return the new <code>SOAPFault</code> object 61 * @exception SOAPException if there is a SOAP error 62 */ 63 public SOAPFault addFault() throws SOAPException; 64 65 66 /** 67 * Creates a new <code>SOAPFault</code> object and adds it to 68 * this <code>SOAPBody</code> object. The type of the 69 * <code>SOAPFault</code> will be a SOAP 1.1 or a SOAP 1.2 70 * <code>SOAPFault</code> depending on the <code>protocol</code> 71 * specified while creating the <code>MessageFactory</code> instance. 72 * <p> 73 * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the 74 * <i>Fault/Code/Value</i> element and the <code>faultString</code> parameter 75 * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1 76 * the <code>faultCode</code> parameter is the value of the <code>faultcode</code> 77 * element and the <code>faultString</code> parameter is the value of the <code>faultstring</code> 78 * element. 79 * <p> 80 * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code> 81 * child element. 82 * 83 * @param faultCode a <code>Name</code> object giving the fault 84 * code to be set; must be one of the fault codes defined in the Version 85 * of SOAP specification in use 86 * @param faultString a <code>String</code> giving an explanation of 87 * the fault 88 * @param locale a {@link java.util.Locale} object indicating 89 * the native language of the <code>faultString</code> 90 * @return the new <code>SOAPFault</code> object 91 * @exception SOAPException if there is a SOAP error 92 * @see SOAPFault#setFaultCode 93 * @see SOAPFault#setFaultString 94 * @since 1.6, SAAJ 1.2 95 */ 96 public SOAPFault addFault(Name faultCode, String faultString, Locale locale) throws SOAPException; 97 98 /** 99 * Creates a new <code>SOAPFault</code> object and adds it to this 100 * <code>SOAPBody</code> object. The type of the <code>SOAPFault</code> 101 * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on 102 * the <code>protocol</code> specified while creating the <code>MessageFactory</code> 103 * instance. 104 * <p> 105 * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the 106 * <i>Fault/Code/Value</i> element and the <code>faultString</code> parameter 107 * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1 108 * the <code>faultCode</code> parameter is the value of the <code>faultcode</code> 109 * element and the <code>faultString</code> parameter is the value of the <code>faultstring</code> 110 * element. 111 * <p> 112 * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code> 113 * child element. 114 * 115 * @param faultCode 116 * a <code>QName</code> object giving the fault code to be 117 * set; must be one of the fault codes defined in the version 118 * of SOAP specification in use. 119 * @param faultString 120 * a <code>String</code> giving an explanation of the fault 121 * @param locale 122 * a {@link java.util.Locale Locale} object indicating the 123 * native language of the <code>faultString</code> 124 * @return the new <code>SOAPFault</code> object 125 * @exception SOAPException 126 * if there is a SOAP error 127 * @see SOAPFault#setFaultCode 128 * @see SOAPFault#setFaultString 129 * @see SOAPBody#addFault(Name faultCode, String faultString, Locale locale) 130 * 131 * @since 1.6, SAAJ 1.3 132 */ 133 public SOAPFault addFault(QName faultCode, String faultString, Locale locale) 134 throws SOAPException; 135 136 /** 137 * Creates a new <code>SOAPFault</code> object and adds it to this 138 * <code>SOAPBody</code> object. The type of the <code>SOAPFault</code> 139 * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on 140 * the <code>protocol</code> specified while creating the <code>MessageFactory</code> 141 * instance. 142 * <p> 143 * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the 144 * <i>Fault/Code/Value</i> element and the <code>faultString</code> parameter 145 * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1 146 * the <code>faultCode</code> parameter is the value of the <i>faultcode</i> 147 * element and the <code>faultString</code> parameter is the value of the <i>faultstring</i> 148 * element. 149 * <p> 150 * In case of a SOAP 1.2 fault, the default value for the mandatory <code>xml:lang</code> 151 * attribute on the <i>Fault/Reason/Text</i> element will be set to 152 * <code>java.util.Locale.getDefault()</code> 153 * <p> 154 * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code> 155 * child element. 156 * 157 * @param faultCode 158 * a <code>Name</code> object giving the fault code to be set; 159 * must be one of the fault codes defined in the version of SOAP 160 * specification in use 161 * @param faultString 162 * a <code>String</code> giving an explanation of the fault 163 * @return the new <code>SOAPFault</code> object 164 * @exception SOAPException 165 * if there is a SOAP error 166 * @see SOAPFault#setFaultCode 167 * @see SOAPFault#setFaultString 168 * @since 1.6, SAAJ 1.2 169 */ 170 public SOAPFault addFault(Name faultCode, String faultString) 171 throws SOAPException; 172 173 /** 174 * Creates a new <code>SOAPFault</code> object and adds it to this <code>SOAPBody</code> 175 * object. The type of the <code>SOAPFault</code> 176 * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on 177 * the <code>protocol</code> specified while creating the <code>MessageFactory</code> 178 * instance. 179 * <p> 180 * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the 181 * <i>Fault/Code/Value</i> element and the <code>faultString</code> parameter 182 * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1 183 * the <code>faultCode</code> parameter is the value of the <i>faultcode</i> 184 * element and the <code>faultString</code> parameter is the value of the <i>faultstring</i> 185 * element. 186 * <p> 187 * In case of a SOAP 1.2 fault, the default value for the mandatory <code>xml:lang</code> 188 * attribute on the <i>Fault/Reason/Text</i> element will be set to 189 * <code>java.util.Locale.getDefault()</code> 190 * <p> 191 * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code> 192 * child element 193 * 194 * @param faultCode 195 * a <code>QName</code> object giving the fault code to be 196 * set; must be one of the fault codes defined in the version 197 * of SOAP specification in use 198 * @param faultString 199 * a <code>String</code> giving an explanation of the fault 200 * @return the new <code>SOAPFault</code> object 201 * @exception SOAPException 202 * if there is a SOAP error 203 * @see SOAPFault#setFaultCode 204 * @see SOAPFault#setFaultString 205 * @see SOAPBody#addFault(Name faultCode, String faultString) 206 * @since 1.6, SAAJ 1.3 207 */ 208 public SOAPFault addFault(QName faultCode, String faultString) 209 throws SOAPException; 210 211 /** 212 * Indicates whether a <code>SOAPFault</code> object exists in this 213 * <code>SOAPBody</code> object. 214 * 215 * @return <code>true</code> if a <code>SOAPFault</code> object exists 216 * in this <code>SOAPBody</code> object; <code>false</code> 217 * otherwise 218 */ 219 public boolean hasFault(); 220 221 /** 222 * Returns the <code>SOAPFault</code> object in this <code>SOAPBody</code> 223 * object. 224 * 225 * @return the <code>SOAPFault</code> object in this <code>SOAPBody</code> 226 * object if present, null otherwise. 227 */ 228 public SOAPFault getFault(); 229 230 /** 231 * Creates a new <code>SOAPBodyElement</code> object with the specified 232 * name and adds it to this <code>SOAPBody</code> object. 233 * 234 * @param name 235 * a <code>Name</code> object with the name for the new <code>SOAPBodyElement</code> 236 * object 237 * @return the new <code>SOAPBodyElement</code> object 238 * @exception SOAPException 239 * if a SOAP error occurs 240 * @see SOAPBody#addBodyElement(javax.xml.namespace.QName) 241 */ 242 public SOAPBodyElement addBodyElement(Name name) throws SOAPException; 243 244 245 /** 246 * Creates a new <code>SOAPBodyElement</code> object with the specified 247 * QName and adds it to this <code>SOAPBody</code> object. 248 * 249 * @param qname 250 * a <code>QName</code> object with the qname for the new 251 * <code>SOAPBodyElement</code> object 252 * @return the new <code>SOAPBodyElement</code> object 253 * @exception SOAPException 254 * if a SOAP error occurs 255 * @see SOAPBody#addBodyElement(Name) 256 * @since 1.6, SAAJ 1.3 257 */ 258 public SOAPBodyElement addBodyElement(QName qname) throws SOAPException; 259 260 /** 261 * Adds the root node of the DOM <code>{@link org.w3c.dom.Document}</code> 262 * to this <code>SOAPBody</code> object. 263 * <p> 264 * Calling this method invalidates the <code>document</code> parameter. 265 * The client application should discard all references to this <code>Document</code> 266 * and its contents upon calling <code>addDocument</code>. The behavior 267 * of an application that continues to use such references is undefined. 268 * 269 * @param document 270 * the <code>Document</code> object whose root node will be 271 * added to this <code>SOAPBody</code>. 272 * @return the <code>SOAPBodyElement</code> that represents the root node 273 * that was added. 274 * @exception SOAPException 275 * if the <code>Document</code> cannot be added 276 * @since 1.6, SAAJ 1.2 277 */ 278 public SOAPBodyElement addDocument(org.w3c.dom.Document document) 279 throws SOAPException; 280 281 /** 282 * Creates a new DOM <code>{@link org.w3c.dom.Document}</code> and sets 283 * the first child of this <code>SOAPBody</code> as it's document 284 * element. The child <code>SOAPElement</code> is removed as part of the 285 * process. 286 * 287 * @return the <code>{@link org.w3c.dom.Document}</code> representation 288 * of the <code>SOAPBody</code> content. 289 * 290 * @exception SOAPException 291 * if there is not exactly one child <code>SOAPElement</code> of the <code> 292 * <code>SOAPBody</code>. 293 * 294 * @since 1.6, SAAJ 1.3 295 */ 296 public org.w3c.dom.Document extractContentAsDocument() 297 throws SOAPException; 298 }