1/* 2 * Copyright (c) 2004, 2017, 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 26package javax.xml.soap; 27 28import java.util.Iterator; 29import java.util.Locale; 30 31import javax.xml.namespace.QName; 32 33/** 34 * An element in the {@code SOAPBody} object that contains 35 * error and/or status information. This information may relate to 36 * errors in the {@code SOAPMessage} object or to problems 37 * that are not related to the content in the message itself. Problems 38 * not related to the message itself are generally errors in 39 * processing, such as the inability to communicate with an upstream 40 * server. 41 * <P> 42 * Depending on the {@code protocol} specified while creating the 43 * {@code MessageFactory} instance, a {@code SOAPFault} has 44 * sub-elements as defined in the SOAP 1.1/SOAP 1.2 specification. 45 * 46 * @since 1.6 47 */ 48public interface SOAPFault extends SOAPBodyElement { 49 50 /** 51 * Sets this {@code SOAPFault} object with the given fault code. 52 * 53 * <P> Fault codes, which give information about the fault, are defined 54 * in the SOAP 1.1 specification. A fault code is mandatory and must 55 * be of type {@code Name}. This method provides a convenient 56 * way to set a fault code. For example, 57 * 58 * <pre>{@code 59 * SOAPEnvelope se = ...; 60 * // Create a qualified name in the SOAP namespace with a localName 61 * // of "Client". Note that prefix parameter is optional and is null 62 * // here which causes the implementation to use an appropriate prefix. 63 * Name qname = se.createName("Client", null, 64 * SOAPConstants.URI_NS_SOAP_ENVELOPE); 65 * SOAPFault fault = ...; 66 * fault.setFaultCode(qname); 67 * }</pre> 68 * It is preferable to use this method over {@link #setFaultCode(String)}. 69 * 70 * @param faultCodeQName a {@code Name} object giving the fault 71 * code to be set. It must be namespace qualified. 72 * @see #getFaultCodeAsName 73 * 74 * @exception SOAPException if there was an error in adding the 75 * <i>faultcode</i> element to the underlying XML tree. 76 * 77 * @since 1.6, SAAJ 1.2 78 */ 79 public void setFaultCode(Name faultCodeQName) throws SOAPException; 80 81 /** 82 * Sets this {@code SOAPFault} object with the given fault code. 83 * 84 * It is preferable to use this method over {@link #setFaultCode(Name)}. 85 * 86 * @param faultCodeQName a {@code QName} object giving the fault 87 * code to be set. It must be namespace qualified. 88 * @see #getFaultCodeAsQName 89 * 90 * @exception SOAPException if there was an error in adding the 91 * {@code faultcode} element to the underlying XML tree. 92 * 93 * @see #setFaultCode(Name) 94 * @see #getFaultCodeAsQName() 95 * 96 * @since 1.6, SAAJ 1.3 97 */ 98 public void setFaultCode(QName faultCodeQName) throws SOAPException; 99 100 /** 101 * Sets this {@code SOAPFault} object with the give fault code. 102 * <P> 103 * Fault codes, which given information about the fault, are defined in 104 * the SOAP 1.1 specification. This element is mandatory in SOAP 1.1. 105 * Because the fault code is required to be a QName it is preferable to 106 * use the {@link #setFaultCode(Name)} form of this method. 107 * 108 * @param faultCode a {@code String} giving the fault code to be set. 109 * It must be of the form "prefix:localName" where the prefix has 110 * been defined in a namespace declaration. 111 * @see #setFaultCode(Name) 112 * @see #getFaultCode 113 * @see SOAPElement#addNamespaceDeclaration 114 * 115 * @exception SOAPException if there was an error in adding the 116 * {@code faultCode} to the underlying XML tree. 117 */ 118 public void setFaultCode(String faultCode) throws SOAPException; 119 120 /** 121 * Gets the mandatory SOAP 1.1 fault code for this 122 * {@code SOAPFault} object as a SAAJ {@code Name} object. 123 * The SOAP 1.1 specification requires the value of the "faultcode" 124 * element to be of type QName. This method returns the content of the 125 * element as a QName in the form of a SAAJ Name object. This method 126 * should be used instead of the {@code getFaultCode} method since 127 * it allows applications to easily access the namespace name without 128 * additional parsing. 129 * 130 * @return a {@code Name} representing the faultcode 131 * @see #setFaultCode(Name) 132 * 133 * @since 1.6, SAAJ 1.2 134 */ 135 public Name getFaultCodeAsName(); 136 137 138 /** 139 * Gets the fault code for this 140 * {@code SOAPFault} object as a {@code QName} object. 141 * 142 * @return a {@code QName} representing the faultcode 143 * 144 * @see #setFaultCode(QName) 145 * 146 * @since 1.6, SAAJ 1.3 147 */ 148 public QName getFaultCodeAsQName(); 149 150 /** 151 * Gets the Subcodes for this {@code SOAPFault} as an iterator over 152 * {@code QNames}. 153 * 154 * @return an {@code Iterator} that accesses a sequence of 155 * {@code QNames}. This {@code Iterator} should not support 156 * the optional {@code remove} method. The order in which the 157 * Subcodes are returned reflects the hierarchy of Subcodes present 158 * in the fault from top to bottom. 159 * 160 * @exception UnsupportedOperationException if this message does not 161 * support the SOAP 1.2 concept of Subcode. 162 * 163 * @since 1.6, SAAJ 1.3 164 */ 165 public Iterator<QName> getFaultSubcodes(); 166 167 /** 168 * Removes any Subcodes that may be contained by this 169 * {@code SOAPFault}. Subsequent calls to 170 * {@code getFaultSubcodes} will return an empty iterator until a call 171 * to {@code appendFaultSubcode} is made. 172 * 173 * @exception UnsupportedOperationException if this message does not 174 * support the SOAP 1.2 concept of Subcode. 175 * 176 * @since 1.6, SAAJ 1.3 177 */ 178 public void removeAllFaultSubcodes(); 179 180 /** 181 * Adds a Subcode to the end of the sequence of Subcodes contained by this 182 * {@code SOAPFault}. Subcodes, which were introduced in SOAP 1.2, are 183 * represented by a recursive sequence of subelements rooted in the 184 * mandatory Code subelement of a SOAP Fault. 185 * 186 * @param subcode a QName containing the Value of the Subcode. 187 * 188 * @exception SOAPException if there was an error in setting the Subcode 189 * @exception UnsupportedOperationException if this message does not 190 * support the SOAP 1.2 concept of Subcode. 191 * 192 * @since 1.6, SAAJ 1.3 193 */ 194 public void appendFaultSubcode(QName subcode) throws SOAPException; 195 196 /** 197 * Gets the fault code for this {@code SOAPFault} object. 198 * 199 * @return a {@code String} with the fault code 200 * @see #getFaultCodeAsName 201 * @see #setFaultCode 202 */ 203 public String getFaultCode(); 204 205 /** 206 * Sets this {@code SOAPFault} object with the given fault actor. 207 * <P> 208 * The fault actor is the recipient in the message path who caused the 209 * fault to happen. 210 * <P> 211 * If this {@code SOAPFault} supports SOAP 1.2 then this call is 212 * equivalent to {@link #setFaultRole(String)} 213 * 214 * @param faultActor a {@code String} identifying the actor that 215 * caused this {@code SOAPFault} object 216 * @see #getFaultActor 217 * 218 * @exception SOAPException if there was an error in adding the 219 * {@code faultActor} to the underlying XML tree. 220 */ 221 public void setFaultActor(String faultActor) throws SOAPException; 222 223 /** 224 * Gets the fault actor for this {@code SOAPFault} object. 225 * <P> 226 * If this {@code SOAPFault} supports SOAP 1.2 then this call is 227 * equivalent to {@link #getFaultRole()} 228 * 229 * @return a {@code String} giving the actor in the message path 230 * that caused this {@code SOAPFault} object 231 * @see #setFaultActor 232 */ 233 public String getFaultActor(); 234 235 /** 236 * Sets the fault string for this {@code SOAPFault} object 237 * to the given string. 238 * <P> 239 * If this 240 * {@code SOAPFault} is part of a message that supports SOAP 1.2 then 241 * this call is equivalent to: 242 * <pre>{@code 243 * addFaultReasonText(faultString, Locale.getDefault()); 244 * }</pre> 245 * 246 * @param faultString a {@code String} giving an explanation of 247 * the fault 248 * @see #getFaultString 249 * 250 * @exception SOAPException if there was an error in adding the 251 * {@code faultString} to the underlying XML tree. 252 */ 253 public void setFaultString(String faultString) throws SOAPException; 254 255 /** 256 * Sets the fault string for this {@code SOAPFault} object 257 * to the given string and localized to the given locale. 258 * <P> 259 * If this 260 * {@code SOAPFault} is part of a message that supports SOAP 1.2 then 261 * this call is equivalent to: 262 * <pre>{@code 263 * addFaultReasonText(faultString, locale); 264 * }</pre> 265 * 266 * @param faultString a {@code String} giving an explanation of 267 * the fault 268 * @param locale a {@link java.util.Locale Locale} object indicating 269 * the native language of the {@code faultString} 270 * @see #getFaultString 271 * 272 * @exception SOAPException if there was an error in adding the 273 * {@code faultString} to the underlying XML tree. 274 * 275 * @since 1.6, SAAJ 1.2 276 */ 277 public void setFaultString(String faultString, Locale locale) 278 throws SOAPException; 279 280 /** 281 * Gets the fault string for this {@code SOAPFault} object. 282 * <P> 283 * If this 284 * {@code SOAPFault} is part of a message that supports SOAP 1.2 then 285 * this call is equivalent to: 286 * <pre>{@code 287 * String reason = null; 288 * try { 289 * reason = (String) getFaultReasonTexts().next(); 290 * } catch (SOAPException e) {} 291 * return reason; 292 * }</pre> 293 * 294 * @return a {@code String} giving an explanation of 295 * the fault 296 * @see #setFaultString(String) 297 * @see #setFaultString(String, Locale) 298 */ 299 public String getFaultString(); 300 301 /** 302 * Gets the locale of the fault string for this {@code SOAPFault} 303 * object. 304 * <P> 305 * If this 306 * {@code SOAPFault} is part of a message that supports SOAP 1.2 then 307 * this call is equivalent to: 308 * <pre>{@code 309 * Locale locale = null; 310 * try { 311 * locale = (Locale) getFaultReasonLocales().next(); 312 * } catch (SOAPException e) {} 313 * return locale; 314 * }</pre> 315 * 316 * @return a {@code Locale} object indicating the native language of 317 * the fault string or {@code null} if no locale was specified 318 * @see #setFaultString(String, Locale) 319 * 320 * @since 1.6, SAAJ 1.2 321 */ 322 public Locale getFaultStringLocale(); 323 324 /** 325 * Returns true if this {@code SOAPFault} has a {@code Detail} 326 * subelement and false otherwise. Equivalent to 327 * {@code (getDetail()!=null)}. 328 * 329 * @return true if this {@code SOAPFault} has a {@code Detail} 330 * subelement and false otherwise. 331 * 332 * @since 1.6, SAAJ 1.3 333 */ 334 public boolean hasDetail(); 335 336 /** 337 * Returns the optional detail element for this {@code SOAPFault} 338 * object. 339 * <P> 340 * A {@code Detail} object carries application-specific error 341 * information, the scope of the error information is restricted to 342 * faults in the {@code SOAPBodyElement} objects if this is a 343 * SOAP 1.1 Fault. 344 * 345 * @return a {@code Detail} object with application-specific 346 * error information if present, null otherwise 347 */ 348 public Detail getDetail(); 349 350 /** 351 * Creates an optional {@code Detail} object and sets it as the 352 * {@code Detail} object for this {@code SOAPFault} 353 * object. 354 * <P> 355 * It is illegal to add a detail when the fault already 356 * contains a detail. Therefore, this method should be called 357 * only after the existing detail has been removed. 358 * 359 * @return the new {@code Detail} object 360 * 361 * @exception SOAPException if this 362 * {@code SOAPFault} object already contains a 363 * valid {@code Detail} object 364 */ 365 public Detail addDetail() throws SOAPException; 366 367 /** 368 * Returns an {@code Iterator} over a distinct sequence of 369 * {@code Locale}s for which there are associated Reason Text items. 370 * Any of these {@code Locale}s can be used in a call to 371 * {@code getFaultReasonText} in order to obtain a localized version 372 * of the Reason Text string. 373 * 374 * @return an {@code Iterator} over a sequence of {@code Locale} 375 * objects for which there are associated Reason Text items. 376 * 377 * @exception SOAPException if there was an error in retrieving 378 * the fault Reason locales. 379 * @exception UnsupportedOperationException if this message does not 380 * support the SOAP 1.2 concept of Fault Reason. 381 * 382 * @since 1.6, SAAJ 1.3 383 */ 384 public Iterator<Locale> getFaultReasonLocales() throws SOAPException; 385 386 /** 387 * Returns an {@code Iterator} over a sequence of 388 * {@code String} objects containing all of the Reason Text items for 389 * this {@code SOAPFault}. 390 * 391 * @return an {@code Iterator} over env:Fault/env:Reason/env:Text items. 392 * 393 * @exception SOAPException if there was an error in retrieving 394 * the fault Reason texts. 395 * @exception UnsupportedOperationException if this message does not 396 * support the SOAP 1.2 concept of Fault Reason. 397 * 398 * @since 1.6, SAAJ 1.3 399 */ 400 public Iterator<String> getFaultReasonTexts() throws SOAPException; 401 402 /** 403 * Returns the Reason Text associated with the given {@code Locale}. 404 * If more than one such Reason Text exists the first matching Text is 405 * returned 406 * 407 * @param locale -- the {@code Locale} for which a localized 408 * Reason Text is desired 409 * 410 * @return the Reason Text associated with {@code locale} 411 * 412 * @see #getFaultString 413 * 414 * @exception SOAPException if there was an error in retrieving 415 * the fault Reason text for the specified locale . 416 * @exception UnsupportedOperationException if this message does not 417 * support the SOAP 1.2 concept of Fault Reason. 418 * 419 * @since 1.6, SAAJ 1.3 420 */ 421 public String getFaultReasonText(Locale locale) throws SOAPException; 422 423 /** 424 * Appends or replaces a Reason Text item containing the specified 425 * text message and an <i>xml:lang</i> derived from 426 * {@code locale}. If a Reason Text item with this 427 * <i>xml:lang</i> already exists its text value will be replaced 428 * with {@code text}. 429 * The {@code locale} parameter should not be {@code null} 430 * <P> 431 * Code sample: 432 * 433 * <pre>{@code 434 * SOAPFault fault = ...; 435 * fault.addFaultReasonText("Version Mismatch", Locale.ENGLISH); 436 * }</pre> 437 * 438 * @param text -- reason message string 439 * @param locale -- Locale object representing the locale of the message 440 * 441 * @exception SOAPException if there was an error in adding the Reason text 442 * or the {@code locale} passed was {@code null}. 443 * @exception UnsupportedOperationException if this message does not 444 * support the SOAP 1.2 concept of Fault Reason. 445 * 446 * @since 1.6, SAAJ 1.3 447 */ 448 public void addFaultReasonText(String text, java.util.Locale locale) 449 throws SOAPException; 450 451 /** 452 * Returns the optional Node element value for this 453 * {@code SOAPFault} object. The Node element is 454 * optional in SOAP 1.2. 455 * 456 * @return Content of the env:Fault/env:Node element as a String 457 * or {@code null} if none 458 * 459 * @exception UnsupportedOperationException if this message does not 460 * support the SOAP 1.2 concept of Fault Node. 461 * 462 * @since 1.6, SAAJ 1.3 463 */ 464 public String getFaultNode(); 465 466 /** 467 * Creates or replaces any existing Node element value for 468 * this {@code SOAPFault} object. The Node element 469 * is optional in SOAP 1.2. 470 * 471 * @param uri - the URI of the Node 472 * 473 * @exception SOAPException if there was an error in setting the 474 * Node for this {@code SOAPFault} object. 475 * @exception UnsupportedOperationException if this message does not 476 * support the SOAP 1.2 concept of Fault Node. 477 * 478 * 479 * @since 1.6, SAAJ 1.3 480 */ 481 public void setFaultNode(String uri) throws SOAPException; 482 483 /** 484 * Returns the optional Role element value for this 485 * {@code SOAPFault} object. The Role element is 486 * optional in SOAP 1.2. 487 * 488 * @return Content of the env:Fault/env:Role element as a String 489 * or {@code null} if none 490 * 491 * @exception UnsupportedOperationException if this message does not 492 * support the SOAP 1.2 concept of Fault Role. 493 * 494 * @since 1.6, SAAJ 1.3 495 */ 496 public String getFaultRole(); 497 498 /** 499 * Creates or replaces any existing Role element value for 500 * this {@code SOAPFault} object. The Role element 501 * is optional in SOAP 1.2. 502 * 503 * @param uri - the URI of the Role 504 * 505 * @exception SOAPException if there was an error in setting the 506 * Role for this {@code SOAPFault} object. 507 * 508 * @exception UnsupportedOperationException if this message does not 509 * support the SOAP 1.2 concept of Fault Role. 510 * 511 * @since 1.6, SAAJ 1.3 512 */ 513 public void setFaultRole(String uri) throws SOAPException; 514 515} 516