/*

 * Copyright (c) 2004, 2013, 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.

     *

     */

    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()

     *

     */

    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)

     *

     */

    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)

     *

     */

    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.

     *

     */

    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.

     *

     */

    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.

     *

     */

    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.

     *

     */

    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)

     *

     */

    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.

     *

     */

    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.

     *

     */

    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.

     *

     */

    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.

     *

     */

    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.

     *

     */

    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.

     *

     */

    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.

     *

     *

     */

    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.

     *

     */

    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.

     *

     */

    public void setFaultRole(String uri) throws SOAPException;

}