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.Iterator;
  29 import java.util.Locale;
  30 
  31 import javax.xml.namespace.QName;
  32 
  33 /**
  34  * An element in the <code>SOAPBody</code> object that contains
  35  * error and/or status information. This information may relate to
  36  * errors in the <code>SOAPMessage</code> 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</code> specified while creating the
  43  * <code>MessageFactory</code> instance,  a <code>SOAPFault</code> has
  44  * sub-elements as defined in the SOAP 1.1/SOAP 1.2 specification.
  45  *
  46  * @since 1.6
  47  */
  48 public interface SOAPFault extends SOAPBodyElement {
  49 
  50     /**
  51      * Sets this <code>SOAPFault</code> 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</code>. This method provides a convenient
  56      * way to set a fault code. For example,
  57      *
  58      * <PRE>
  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</code> 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</code> 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</code> 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</code> 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</code> 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</code> 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</code> 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</code> object as a SAAJ <code>Name</code> 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</code> method since
 127      * it allows applications to easily access the namespace name without
 128      * additional parsing.
 129      *
 130      * @return a <code>Name</code> 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</code> object as a <code>QName</code> object.
 141      *
 142      * @return a <code>QName</code> 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</code> as an iterator over
 152      * <code>QNames</code>.
 153      *
 154      * @return an <code>Iterator</code> that accesses a sequence of
 155      *      <code>QNames</code>. This <code>Iterator</code> should not support
 156      *      the optional <code>remove</code> 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 getFaultSubcodes();
 166 
 167     /**
 168      * Removes any Subcodes that may be contained by this
 169      * <code>SOAPFault</code>. Subsequent calls to
 170      * <code>getFaultSubcodes</code> will return an empty iterator until a call
 171      * to <code>appendFaultSubcode</code> 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</code>. 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</code> object.
 198      *
 199      * @return a <code>String</code> with the fault code
 200      * @see #getFaultCodeAsName
 201      * @see #setFaultCode
 202      */
 203     public String getFaultCode();
 204 
 205     /**
 206      * Sets this <code>SOAPFault</code> 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</code> supports SOAP 1.2 then this call is
 212      * equivalent to {@link #setFaultRole(String)}
 213      *
 214      * @param faultActor a <code>String</code> identifying the actor that
 215      *        caused this <code>SOAPFault</code> object
 216      * @see #getFaultActor
 217      *
 218      * @exception SOAPException if there was an error in adding the
 219      *            <code>faultActor</code> 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</code> object.
 225      * <P>
 226      * If this <code>SOAPFault</code> supports SOAP 1.2 then this call is
 227      * equivalent to {@link #getFaultRole()}
 228      *
 229      * @return a <code>String</code> giving the actor in the message path
 230      *         that caused this <code>SOAPFault</code> object
 231      * @see #setFaultActor
 232      */
 233     public String getFaultActor();
 234 
 235     /**
 236      * Sets the fault string for this <code>SOAPFault</code> object
 237      * to the given string.
 238      * <P>
 239      * If this
 240      * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then
 241      * this call is equivalent to:
 242      * <pre>
 243      *      addFaultReasonText(faultString, Locale.getDefault());
 244      * </pre>
 245      *
 246      * @param faultString a <code>String</code> 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</code> 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</code> object
 257      * to the given string and localized to the given locale.
 258      * <P>
 259      * If this
 260      * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then
 261      * this call is equivalent to:
 262      * <pre>
 263      *      addFaultReasonText(faultString, locale);
 264      * </pre>
 265      *
 266      * @param faultString a <code>String</code> 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</code>
 270      * @see #getFaultString
 271      *
 272      * @exception SOAPException if there was an error in adding the
 273      *            <code>faultString</code> 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</code> object.
 282      * <P>
 283      * If this
 284      * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then
 285      * this call is equivalent to:
 286      * <pre>
 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</code> 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</code>
 303      * object.
 304      * <P>
 305      * If this
 306      * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then
 307      * this call is equivalent to:
 308      * <pre>
 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</code> object indicating the native language of
 317      *          the fault string or <code>null</code> 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</code> has a <code>Detail</code>
 326      * subelement and false otherwise. Equivalent to
 327      * <code>(getDetail()!=null)</code>.
 328      *
 329      * @return true if this <code>SOAPFault</code> has a <code>Detail</code>
 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</code>
 338      * object.
 339      * <P>
 340      * A <code>Detail</code> object carries application-specific error
 341      * information, the scope of the error information is restricted to
 342      * faults in the <code>SOAPBodyElement</code> objects if this is a
 343      * SOAP 1.1 Fault.
 344      *
 345      * @return a <code>Detail</code> object with application-specific
 346      *         error information if present, null otherwise
 347      */
 348     public Detail getDetail();
 349 
 350     /**
 351      * Creates an optional <code>Detail</code> object and sets it as the
 352      * <code>Detail</code> object for this <code>SOAPFault</code>
 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</code> object
 360      *
 361      * @exception SOAPException if this
 362      *            <code>SOAPFault</code> object already contains a
 363      *            valid <code>Detail</code> object
 364      */
 365     public Detail addDetail() throws SOAPException;
 366 
 367     /**
 368      * Returns an <code>Iterator</code> over a distinct sequence of
 369      * <code>Locale</code>s for which there are associated Reason Text items.
 370      * Any of these <code>Locale</code>s can be used in a call to
 371      * <code>getFaultReasonText</code> in order to obtain a localized version
 372      * of the Reason Text string.
 373      *
 374      * @return an <code>Iterator</code> over a sequence of <code>Locale</code>
 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 getFaultReasonLocales() throws SOAPException;
 385 
 386     /**
 387      * Returns an <code>Iterator</code> over a sequence of
 388      * <code>String</code> objects containing all of the Reason Text items for
 389      * this <code>SOAPFault</code>.
 390      *
 391      * @return an <code>Iterator</code> 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 getFaultReasonTexts() throws SOAPException;
 401 
 402     /**
 403      * Returns the Reason Text associated with the given <code>Locale</code>.
 404      * If more than one such Reason Text exists the first matching Text is
 405      * returned
 406      *
 407      * @param locale -- the <code>Locale</code> for which a localized
 408      *      Reason Text is desired
 409      *
 410      * @return the Reason Text associated with <code>locale</code>
 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</code>. If a Reason Text item with this
 427      * <i>xml:lang</i> already exists its text value will be replaced
 428      * with <code>text</code>.
 429      * The <code>locale</code> parameter should not be <code>null</code>
 430      * <P>
 431      * Code sample:
 432      *
 433      * <PRE>
 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</code> passed was <code>null</code>.
 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</code> 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</code> 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</code> object. The Node element
 469      * is optional in SOAP 1.2.
 470      *
 471      * @exception SOAPException  if there was an error in setting the
 472      *            Node for this  <code>SOAPFault</code> object.
 473      * @exception UnsupportedOperationException if this message does not
 474      *      support the SOAP 1.2 concept of Fault Node.
 475      *
 476      *
 477      * @since 1.6, SAAJ 1.3
 478      */
 479     public void setFaultNode(String uri) throws SOAPException;
 480 
 481     /**
 482      * Returns the optional Role element value for this
 483      * <code>SOAPFault</code> object. The Role element is
 484      * optional in SOAP 1.2.
 485      *
 486      * @return Content of the env:Fault/env:Role element as a String
 487      * or <code>null</code> if none
 488      *
 489      * @exception UnsupportedOperationException if this message does not
 490      *      support the SOAP 1.2 concept of Fault Role.
 491      *
 492      * @since 1.6, SAAJ 1.3
 493      */
 494     public String getFaultRole();
 495 
 496     /**
 497      * Creates or replaces any existing Role element value for
 498      * this <code>SOAPFault</code> object. The Role element
 499      * is optional in SOAP 1.2.
 500      *
 501      * @param uri - the URI of the Role
 502      *
 503      * @exception SOAPException  if there was an error in setting the
 504      *            Role for this  <code>SOAPFault</code> object.
 505      *
 506      * @exception UnsupportedOperationException if this message does not
 507      *      support the SOAP 1.2 concept of Fault Role.
 508      *
 509      * @since 1.6, SAAJ 1.3
 510      */
 511     public void setFaultRole(String uri) throws SOAPException;
 512 
 513 }