/* * Copyright 2001-2004 The Apache Software Foundation. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package javax.xml.soap; import java.util.Locale; /** * 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. *

* The SOAPFault interface provides methods for * retrieving the information contained in a * SOAPFault object and for setting the fault code, the * fault actor, and a string describing the fault. A fault code is * one of the codes defined in the SOAP 1.1 specification that * describe the fault. An actor is an intermediate recipient to * whom a message was routed. The message path may include one or * more actors, or, if no actors are specified, the message goes * only to the default actor, which is the final intended * recipient. */ public interface SOAPFault extends SOAPBodyElement { /** * Sets this SOAPFault object with the given * fault code. * *

Fault codes, which given information about the fault, * are defined in the SOAP 1.1 specification.

* @param faultCode a String giving * the fault code to be set; must be one of the fault codes * defined in the SOAP 1.1 specification * @throws SOAPException if there was an error in * adding the faultCode to the underlying XML * tree. * @see #getFaultCode() getFaultCode() */ public abstract void setFaultCode(String faultCode) throws SOAPException; /** * Gets the fault code for this SOAPFault * object. * @return a String with the fault code * @see #setFaultCode(java.lang.String) setFaultCode(java.lang.String) */ public abstract 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.

* @param faultActor a String * identifying the actor that caused this * SOAPFault object * @throws SOAPException if there was an error in * adding the faultActor to the underlying XML * tree. * @see #getFaultActor() getFaultActor() */ public abstract void setFaultActor(String faultActor) throws SOAPException; /** * Gets the fault actor for this SOAPFault * object. * @return a String giving the actor in the message * path that caused this SOAPFault object * @see #setFaultActor(java.lang.String) setFaultActor(java.lang.String) */ public abstract String getFaultActor(); /** * Sets the fault string for this SOAPFault * object to the given string. * * @param faultString a String * giving an explanation of the fault * @throws SOAPException if there was an error in * adding the faultString to the underlying XML * tree. * @see #getFaultString() getFaultString() */ public abstract void setFaultString(String faultString) throws SOAPException; /** * Gets the fault string for this SOAPFault * object. * @return a String giving an explanation of the * fault */ public abstract String getFaultString(); /** * Returns the detail element for this SOAPFault * object. * *

A Detail object carries * application-specific error information related to * SOAPBodyElement objects.

* @return a Detail object with * application-specific error information */ public abstract Detail getDetail(); /** * Creates a 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 * @throws SOAPException if this * SOAPFault object already contains a valid * Detail object */ public abstract Detail addDetail() throws SOAPException; /** * 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 * QName. 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 setFaultCode(String).
     *
     * @param name a Name object giving the fault code to be set.
     *              It must be namespace qualified.
     * @throws SOAPException if there was an error in adding the
     *              faultcode element to the underlying XML tree
     */
    public abstract void setFaultCode(Name name) 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.
     * 

     * In the future, a QName object version of this method may also be added.
     * @return a Name representing the faultcode
     */
    public abstract Name getFaultCodeAsName();

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

    /**
     * Returns the optional detail element for this SOAPFault
     * object.
     *
     * @return a Locale object indicating the native language of
     *              the fault string or null if no locale was
     *              specified
     */
    public abstract Locale getFaultStringLocale();
}