/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you 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 aString
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 aString
* 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.
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 newDetail
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 aName
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 thisSOAPFault
* object as a SAAJName
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 * SAAJName
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 thisSOAPFault
object to the given * string and localized to the given locale. * * @param faultString aString
giving an explanation of * the fault * @param locale aLocale
object indicating the * native language of thefaultString
* @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 thisSOAPFault
* object. * * @return aLocale
object indicating the native language of * the fault string ornull
if no locale was * specified */ public abstract Locale getFaultStringLocale(); }