/* * Copyright (c) 2004, 2011, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.xml.soap; import java.util.Iterator; import java.util.Locale; import javax.xml.namespace.QName; /** * An element in the SOAPBody object that contains * error and/or status information. This information may relate to * errors in the SOAPMessage object or to problems * that are not related to the content in the message itself. Problems * not related to the message itself are generally errors in * processing, such as the inability to communicate with an upstream * server. *

* Depending on the protocol specified while creating the * MessageFactory instance, a SOAPFault has * sub-elements as defined in the SOAP 1.1/SOAP 1.2 specification. */ public interface SOAPFault extends SOAPBodyElement { /** * Sets this SOAPFault object with the given fault code. * *

Fault codes, which give information about the fault, are defined * in the SOAP 1.1 specification. A fault code is mandatory and must * be of type Name. This method provides a convenient * way to set a fault code. For example, * *

     * SOAPEnvelope se = ...;
     * // Create a qualified name in the SOAP namespace with a localName
     * // of "Client". Note that prefix parameter is optional and is null
     * // here which causes the implementation to use an appropriate prefix.
     * Name qname = se.createName("Client", null,
     *                            SOAPConstants.URI_NS_SOAP_ENVELOPE);
     * SOAPFault fault = ...;
     * fault.setFaultCode(qname);
     * 
* It is preferable to use this method over {@link #setFaultCode(String)}. * * @param faultCodeQName a Name object giving the fault * code to be set. It must be namespace qualified. * @see #getFaultCodeAsName * * @exception SOAPException if there was an error in adding the * faultcode element to the underlying XML tree. * * @since SAAJ 1.2 */ public void setFaultCode(Name faultCodeQName) throws SOAPException; /** * Sets this SOAPFault object with the given fault code. * * It is preferable to use this method over {@link #setFaultCode(Name)}. * * @param faultCodeQName a QName object giving the fault * code to be set. It must be namespace qualified. * @see #getFaultCodeAsQName * * @exception SOAPException if there was an error in adding the * faultcode element to the underlying XML tree. * * @see #setFaultCode(Name) * @see #getFaultCodeAsQName() * * @since SAAJ 1.3 */ public void setFaultCode(QName faultCodeQName) throws SOAPException; /** * Sets this SOAPFault object with the give fault code. *

* Fault codes, which given information about the fault, are defined in * the SOAP 1.1 specification. This element is mandatory in SOAP 1.1. * Because the fault code is required to be a QName it is preferable to * use the {@link #setFaultCode(Name)} form of this method. * * @param faultCode a String giving the fault code to be set. * It must be of the form "prefix:localName" where the prefix has * been defined in a namespace declaration. * @see #setFaultCode(Name) * @see #getFaultCode * @see SOAPElement#addNamespaceDeclaration * * @exception SOAPException if there was an error in adding the * faultCode to the underlying XML tree. */ public void setFaultCode(String faultCode) throws SOAPException; /** * Gets the mandatory SOAP 1.1 fault code for this * SOAPFault object as a SAAJ Name object. * The SOAP 1.1 specification requires the value of the "faultcode" * element to be of type QName. This method returns the content of the * element as a QName in the form of a SAAJ Name object. This method * should be used instead of the getFaultCode method since * it allows applications to easily access the namespace name without * additional parsing. * * @return a Name representing the faultcode * @see #setFaultCode(Name) * * @since SAAJ 1.2 */ public Name getFaultCodeAsName(); /** * Gets the fault code for this * SOAPFault object as a QName object. * * @return a QName representing the faultcode * * @see #setFaultCode(QName) * * @since SAAJ 1.3 */ public QName getFaultCodeAsQName(); /** * Gets the Subcodes for this SOAPFault as an iterator over * QNames. * * @return an Iterator that accesses a sequence of * QNames. This Iterator should not support * the optional remove method. The order in which the * Subcodes are returned reflects the hierarchy of Subcodes present * in the fault from top to bottom. * * @exception UnsupportedOperationException if this message does not * support the SOAP 1.2 concept of Subcode. * * @since SAAJ 1.3 */ public Iterator getFaultSubcodes(); /** * Removes any Subcodes that may be contained by this * SOAPFault. Subsequent calls to * getFaultSubcodes will return an empty iterator until a call * to appendFaultSubcode is made. * * @exception UnsupportedOperationException if this message does not * support the SOAP 1.2 concept of Subcode. * * @since SAAJ 1.3 */ public void removeAllFaultSubcodes(); /** * Adds a Subcode to the end of the sequence of Subcodes contained by this * SOAPFault. Subcodes, which were introduced in SOAP 1.2, are * represented by a recursive sequence of subelements rooted in the * mandatory Code subelement of a SOAP Fault. * * @param subcode a QName containing the Value of the Subcode. * * @exception SOAPException if there was an error in setting the Subcode * @exception UnsupportedOperationException if this message does not * support the SOAP 1.2 concept of Subcode. * * @since SAAJ 1.3 */ public void appendFaultSubcode(QName subcode) throws SOAPException; /** * Gets the fault code for this SOAPFault object. * * @return a String with the fault code * @see #getFaultCodeAsName * @see #setFaultCode */ public String getFaultCode(); /** * Sets this SOAPFault object with the given fault actor. *

* The fault actor is the recipient in the message path who caused the * fault to happen. *

* If this SOAPFault supports SOAP 1.2 then this call is * equivalent to {@link #setFaultRole(String)} * * @param faultActor a String identifying the actor that * caused this SOAPFault object * @see #getFaultActor * * @exception SOAPException if there was an error in adding the * faultActor to the underlying XML tree. */ public void setFaultActor(String faultActor) throws SOAPException; /** * Gets the fault actor for this SOAPFault object. *

* If this SOAPFault supports SOAP 1.2 then this call is * equivalent to {@link #getFaultRole()} * * @return a String giving the actor in the message path * that caused this SOAPFault object * @see #setFaultActor */ public String getFaultActor(); /** * Sets the fault string for this SOAPFault object * to the given string. *

* If this * SOAPFault is part of a message that supports SOAP 1.2 then * this call is equivalent to: *

     *      addFaultReasonText(faultString, Locale.getDefault());
     * 
* * @param faultString a String giving an explanation of * the fault * @see #getFaultString * * @exception SOAPException if there was an error in adding the * faultString to the underlying XML tree. */ public void setFaultString(String faultString) throws SOAPException; /** * Sets the fault string for this SOAPFault object * to the given string and localized to the given locale. *

* If this * SOAPFault is part of a message that supports SOAP 1.2 then * this call is equivalent to: *

     *      addFaultReasonText(faultString, locale);
     * 
* * @param faultString a String giving an explanation of * the fault * @param locale a {@link java.util.Locale Locale} object indicating * the native language of the faultString * @see #getFaultString * * @exception SOAPException if there was an error in adding the * faultString to the underlying XML tree. * * @since SAAJ 1.2 */ public void setFaultString(String faultString, Locale locale) throws SOAPException; /** * Gets the fault string for this SOAPFault object. *

* If this * SOAPFault is part of a message that supports SOAP 1.2 then * this call is equivalent to: *

     *    String reason = null;
     *    try {
     *        reason = (String) getFaultReasonTexts().next();
     *    } catch (SOAPException e) {}
     *    return reason;
     * 
* * @return a String giving an explanation of * the fault * @see #setFaultString(String) * @see #setFaultString(String, Locale) */ public String getFaultString(); /** * Gets the locale of the fault string for this SOAPFault * object. *

* If this * SOAPFault is part of a message that supports SOAP 1.2 then * this call is equivalent to: *

     *    Locale locale = null;
     *    try {
     *        locale = (Locale) getFaultReasonLocales().next();
     *    } catch (SOAPException e) {}
     *    return locale;
     * 
* * @return a Locale object indicating the native language of * the fault string or null if no locale was specified * @see #setFaultString(String, Locale) * * @since SAAJ 1.2 */ public Locale getFaultStringLocale(); /** * Returns true if this SOAPFault has a Detail * subelement and false otherwise. Equivalent to * (getDetail()!=null). * * @return true if this SOAPFault has a Detail * subelement and false otherwise. * * @since SAAJ 1.3 */ public boolean hasDetail(); /** * Returns the optional detail element for this SOAPFault * object. *

* A Detail object carries application-specific error * information, the scope of the error information is restricted to * faults in the SOAPBodyElement objects if this is a * SOAP 1.1 Fault. * * @return a Detail object with application-specific * error information if present, null otherwise */ public Detail getDetail(); /** * Creates an optional Detail object and sets it as the * Detail object for this SOAPFault * object. *

* It is illegal to add a detail when the fault already * contains a detail. Therefore, this method should be called * only after the existing detail has been removed. * * @return the new Detail object * * @exception SOAPException if this * SOAPFault object already contains a * valid Detail object */ public Detail addDetail() throws SOAPException; /** * Returns an Iterator over a distinct sequence of * Locales for which there are associated Reason Text items. * Any of these Locales can be used in a call to * getFaultReasonText in order to obtain a localized version * of the Reason Text string. * * @return an Iterator over a sequence of Locale * objects for which there are associated Reason Text items. * * @exception SOAPException if there was an error in retrieving * the fault Reason locales. * @exception UnsupportedOperationException if this message does not * support the SOAP 1.2 concept of Fault Reason. * * @since SAAJ 1.3 */ public Iterator getFaultReasonLocales() throws SOAPException; /** * Returns an Iterator over a sequence of * String objects containing all of the Reason Text items for * this SOAPFault. * * @return an Iterator over env:Fault/env:Reason/env:Text items. * * @exception SOAPException if there was an error in retrieving * the fault Reason texts. * @exception UnsupportedOperationException if this message does not * support the SOAP 1.2 concept of Fault Reason. * * @since SAAJ 1.3 */ public Iterator getFaultReasonTexts() throws SOAPException; /** * Returns the Reason Text associated with the given Locale. * If more than one such Reason Text exists the first matching Text is * returned * * @param locale -- the Locale for which a localized * Reason Text is desired * * @return the Reason Text associated with locale * * @see #getFaultString * * @exception SOAPException if there was an error in retrieving * the fault Reason text for the specified locale . * @exception UnsupportedOperationException if this message does not * support the SOAP 1.2 concept of Fault Reason. * * @since SAAJ 1.3 */ public String getFaultReasonText(Locale locale) throws SOAPException; /** * Appends or replaces a Reason Text item containing the specified * text message and an xml:lang derived from * locale. If a Reason Text item with this * xml:lang already exists its text value will be replaced * with text. * The locale parameter should not be null *

* Code sample: * *

     * SOAPFault fault = ...;
     * fault.addFaultReasonText("Version Mismatch", Locale.ENGLISH);
     * 
* * @param text -- reason message string * @param locale -- Locale object representing the locale of the message * * @exception SOAPException if there was an error in adding the Reason text * or the locale passed was null. * @exception UnsupportedOperationException if this message does not * support the SOAP 1.2 concept of Fault Reason. * * @since SAAJ 1.3 */ public void addFaultReasonText(String text, java.util.Locale locale) throws SOAPException; /** * Returns the optional Node element value for this * SOAPFault object. The Node element is * optional in SOAP 1.2. * * @return Content of the env:Fault/env:Node element as a String * or null if none * * @exception UnsupportedOperationException if this message does not * support the SOAP 1.2 concept of Fault Node. * * @since SAAJ 1.3 */ public String getFaultNode(); /** * Creates or replaces any existing Node element value for * this SOAPFault object. The Node element * is optional in SOAP 1.2. * * @exception SOAPException if there was an error in setting the * Node for this SOAPFault object. * @exception UnsupportedOperationException if this message does not * support the SOAP 1.2 concept of Fault Node. * * * @since SAAJ 1.3 */ public void setFaultNode(String uri) throws SOAPException; /** * Returns the optional Role element value for this * SOAPFault object. The Role element is * optional in SOAP 1.2. * * @return Content of the env:Fault/env:Role element as a String * or null if none * * @exception UnsupportedOperationException if this message does not * support the SOAP 1.2 concept of Fault Role. * * @since SAAJ 1.3 */ public String getFaultRole(); /** * Creates or replaces any existing Role element value for * this SOAPFault object. The Role element * is optional in SOAP 1.2. * * @param uri - the URI of the Role * * @exception SOAPException if there was an error in setting the * Role for this SOAPFault object. * * @exception UnsupportedOperationException if this message does not * support the SOAP 1.2 concept of Fault Role. * * @since SAAJ 1.3 */ public void setFaultRole(String uri) throws SOAPException; }