/*
 * Copyright (c) 2005, 2006, 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 <code>SOAPBody</code> object that contains
 * error and/or status information. This information may relate to
 * errors in the <code>SOAPMessage</code> 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.
 * <P>
 * Depending on the <code>protocol</code> specified while creating the 
 * <code>MessageFactory</code> instance,  a <code>SOAPFault</code> has 
 * sub-elements as defined in the SOAP 1.1/SOAP 1.2 specification.
 */
public interface SOAPFault extends SOAPBodyElement {

    /**
     * Sets this <code>SOAPFault</code> object with the given fault code.
     *
     * <P> 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 <code>Name</code>. This method provides a convenient
     * way to set a fault code. For example,
     *
     * <PRE>
     * 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);
     * </PRE>
     * It is preferable to use this method over {@link #setFaultCode(String)}.
     *
     * @param faultCodeQName a <code>Name</code> 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
     *            <i>faultcode</i> element to the underlying XML tree.
     *
     * @since SAAJ 1.2
     */
    public void setFaultCode(Name faultCodeQName) throws SOAPException;

    /**
     * Sets this <code>SOAPFault</code> object with the given fault code.
     *
     * It is preferable to use this method over {@link #setFaultCode(Name)}.
     *
     * @param faultCodeQName a <code>QName</code> 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
     *            <code>faultcode</code> element to the underlying XML tree.
     *
     * @see #setFaultCode(Name)
     * @see #getFaultCodeAsQName()
     * 
     * @since SAAJ 1.3
     */
    public void setFaultCode(QName faultCodeQName) throws SOAPException;

    /**
     * Sets this <code>SOAPFault</code> object with the give fault code.
     * <P>
     * 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 <code>String</code> 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
     *            <code>faultCode</code> to the underlying XML tree.
     */
    public void setFaultCode(String faultCode) throws SOAPException;

    /**
     * Gets the mandatory SOAP 1.1 fault code for this
     * <code>SOAPFault</code> object as a SAAJ <code>Name</code> 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 <code>getFaultCode</code> method since
     * it allows applications to easily access the namespace name without
     * additional parsing.
     *
     * @return a <code>Name</code> representing the faultcode
     * @see #setFaultCode(Name)
     * 
     * @since SAAJ 1.2
     */
    public Name getFaultCodeAsName();
    
    
    /**
     * Gets the fault code for this
     * <code>SOAPFault</code> object as a <code>QName</code> object.
     *
     * @return a <code>QName</code> representing the faultcode
     * 
     * @see #setFaultCode(QName)
     * 
     * @since SAAJ 1.3
     */
    public QName getFaultCodeAsQName();

    /**
     * Gets the Subcodes for this <code>SOAPFault</code> as an iterator over 
     * <code>QNames</code>. 
     *
     * @return an <code>Iterator</code> that accesses a sequence of 
     *      <code>QNames</code>. This <code>Iterator</code> should not support
     *      the optional <code>remove</code> 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 
     * <code>SOAPFault</code>. Subsequent calls to 
     * <code>getFaultSubcodes</code> will return an empty iterator until a call
     * to <code>appendFaultSubcode</code> 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
     * <code>SOAPFault</code>. 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 <code>SOAPFault</code> object.
     *
     * @return a <code>String</code> with the fault code
     * @see #getFaultCodeAsName
     * @see #setFaultCode
     */
    public String getFaultCode();

    /**
     * Sets this <code>SOAPFault</code> object with the given fault actor.
     * <P>
     * The fault actor is the recipient in the message path who caused the
     * fault to happen.
     * <P>
     * If this <code>SOAPFault</code> supports SOAP 1.2 then this call is
     * equivalent to {@link #setFaultRole(String)}
     *
     * @param faultActor a <code>String</code> identifying the actor that
     *        caused this <code>SOAPFault</code> object
     * @see #getFaultActor
     *
     * @exception SOAPException if there was an error in adding the
     *            <code>faultActor</code> to the underlying XML tree.
     */
    public void setFaultActor(String faultActor) throws SOAPException;

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

    /**
     * Sets the fault string for this <code>SOAPFault</code> object
     * to the given string.
     * <P>
     * If this
     * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then
     * this call is equivalent to: 
     * <pre>
     *      addFaultReasonText(faultString, Locale.getDefault());
     * </pre>
     *
     * @param faultString a <code>String</code> giving an explanation of
     *        the fault
     * @see #getFaultString
     *
     * @exception SOAPException if there was an error in adding the
     *            <code>faultString</code> to the underlying XML tree.
     */
    public void setFaultString(String faultString) throws SOAPException;

    /**
     * Sets the fault string for this <code>SOAPFault</code> object
     * to the given string and localized to the given locale.
     * <P>
     * If this
     * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then
     * this call is equivalent to: 
     * <pre>
     *      addFaultReasonText(faultString, locale);
     * </pre>
     *
     * @param faultString a <code>String</code> giving an explanation of
     *         the fault
     * @param locale a {@link java.util.Locale Locale} object indicating
     *         the native language of the <code>faultString</code> 
     * @see #getFaultString
     *
     * @exception SOAPException if there was an error in adding the
     *            <code>faultString</code> to the underlying XML tree.
     * 
     * @since SAAJ 1.2
     */
    public void setFaultString(String faultString, Locale locale)
        throws SOAPException;

    /**
     * Gets the fault string for this <code>SOAPFault</code> object. 
     * <P>
     * If this
     * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then
     * this call is equivalent to: 
     * <pre>
     *    String reason = null;
     *    try {
     *        reason = (String) getFaultReasonTexts().next();
     *    } catch (SOAPException e) {}
     *    return reason;
     * </pre>
     *
     * @return a <code>String</code> 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 <code>SOAPFault</code> 
     * object. 
     * <P>
     * If this
     * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then
     * this call is equivalent to: 
     * <pre>
     *    Locale locale = null;
     *    try {
     *        locale = (Locale) getFaultReasonLocales().next();
     *    } catch (SOAPException e) {}
     *    return locale;
     * </pre>
     * 
     * @return a <code>Locale</code> object indicating the native language of
     *          the fault string or <code>null</code> if no locale was specified
     * @see #setFaultString(String, Locale)
     * 
     * @since SAAJ 1.2
     */
    public Locale getFaultStringLocale();

    /**
     * Returns true if this <code>SOAPFault</code> has a <code>Detail</code>
     * subelement and false otherwise. Equivalent to 
     * <code>(getDetail()!=null)</code>.
     * 
     * @return true if this <code>SOAPFault</code> has a <code>Detail</code>
     * subelement and false otherwise.
     * 
     * @since SAAJ 1.3
     */
    public boolean hasDetail();
    
    /**
     * Returns the optional detail element for this <code>SOAPFault</code>
     * object.
     * <P>
     * A <code>Detail</code> object carries application-specific error
     * information, the scope of the error information is restricted to 
     * faults in the <code>SOAPBodyElement</code> objects if this is a 
     * SOAP 1.1 Fault. 
     *
     * @return a <code>Detail</code> object with application-specific
     *         error information if present, null otherwise
     */
    public Detail getDetail();

    /**
     * Creates an optional <code>Detail</code> object and sets it as the
     * <code>Detail</code> object for this <code>SOAPFault</code>
     * object.
     * <P>
     * 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 <code>Detail</code> object
     *
     * @exception SOAPException if this
     *            <code>SOAPFault</code> object already contains a
     *            valid <code>Detail</code> object
     */
    public Detail addDetail() throws SOAPException;

    /**
     * Returns an <code>Iterator</code> over a distinct sequence of 
     * <code>Locale</code>s for which there are associated Reason Text items. 
     * Any of these <code>Locale</code>s can be used in a call to 
     * <code>getFaultReasonText</code> in order to obtain a localized version
     * of the Reason Text string.
     * 
     * @return an <code>Iterator</code> over a sequence of <code>Locale</code>
     *      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 <code>Iterator</code> over a sequence of 
     * <code>String</code> objects containing all of the Reason Text items for
     * this <code>SOAPFault</code>. 
     *
     * @return an <code>Iterator</code> 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 <code>Locale</code>. 
     * If more than one such Reason Text exists the first matching Text is 
     * returned
     * 
     * @param locale -- the <code>Locale</code> for which a localized 
     *      Reason Text is desired
     * 
     * @return the Reason Text associated with <code>locale</code>
     * 
     * @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 <i>xml:lang</i> derived from 
     * <code>locale</code>. If a Reason Text item with this 
     * <i>xml:lang</i> already exists its text value will be replaced
     * with <code>text</code>. 
     * The <code>locale</code> parameter should not be <code>null</code>
     * <P>
     * Code sample:
     *
     * <PRE>
     * SOAPFault fault = ...;
     * fault.addFaultReasonText("Version Mismatch", Locale.ENGLISH);
     * </PRE>
     *
     * @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 <code>locale</code> passed was <code>null</code>.
     * @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
     * <code>SOAPFault</code> object. The Node element is
     * optional in SOAP 1.2.
     *
     * @return Content of the env:Fault/env:Node element as a String
     * or <code>null</code> 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 <code>SOAPFault</code> object. The Node element
     * is optional in SOAP 1.2.
     *
     * @exception SOAPException  if there was an error in setting the
     *            Node for this  <code>SOAPFault</code> 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
     * <code>SOAPFault</code> object. The Role element is
     * optional in SOAP 1.2.
     *
     * @return Content of the env:Fault/env:Role element as a String
     * or <code>null</code> 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 <code>SOAPFault</code> 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  <code>SOAPFault</code> 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;

}