/*
* 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 <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>
* The <CODE>SOAPFault</CODE> interface provides methods for retrieving the
* information contained in a <CODE>
* SOAPFault</CODE> 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 <CODE>SOAPFault</CODE> object with the given fault code.
*
* <P>
* Fault codes, which given information about the fault, are defined in the
* SOAP 1.1 specification.
* </P>
*
* @param faultCode
* a <CODE>String</CODE> 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 <CODE>faultCode</CODE> to
* the underlying XML tree.
* @see #getFaultCode() getFaultCode()
*/
public abstract void setFaultCode(String faultCode) throws SOAPException;
/**
* Gets the fault code for this <CODE>SOAPFault</CODE> object.
*
* @return a <CODE>String</CODE> with the fault code
* @see #setFaultCode(java.lang.String) setFaultCode(java.lang.String)
*/
public abstract 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>
*
* @param faultActor
* a <CODE>String</CODE> identifying the actor that caused this
* <CODE>
* SOAPFault</CODE> object
* @throws SOAPException
* if there was an error in adding the <CODE>faultActor</CODE>
* to the underlying XML tree.
* @see #getFaultActor() getFaultActor()
*/
public abstract void setFaultActor(String faultActor) throws SOAPException;
/**
* Gets the fault actor for this <CODE>SOAPFault</CODE> object.
*
* @return a <CODE>String</CODE> giving the actor in the message path that
* caused this <CODE>SOAPFault</CODE> object
* @see #setFaultActor(java.lang.String) setFaultActor(java.lang.String)
*/
public abstract String getFaultActor();
/**
* Sets the fault string for this <CODE>SOAPFault</CODE> object to the given
* string.
*
* @param faultString
* a <CODE>String</CODE> giving an explanation of the fault
* @throws SOAPException
* if there was an error in adding the <CODE>faultString</CODE>
* to the underlying XML tree.
* @see #getFaultString() getFaultString()
*/
public abstract void setFaultString(String faultString)
throws SOAPException;
/**
* Gets the fault string for this <CODE>SOAPFault</CODE> object.
*
* @return a <CODE>String</CODE> giving an explanation of the fault
*/
public abstract String getFaultString();
/**
* Returns the detail element for this <CODE>SOAPFault</CODE> object.
*
* <P>
* A <CODE>Detail</CODE> object carries application-specific error
* information related to <CODE>
* SOAPBodyElement</CODE> objects.
* </P>
*
* @return a <CODE>Detail</CODE> object with application-specific error
* information
*/
public abstract Detail getDetail();
/**
* Creates a <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.
* </P>
*
* @return the new <CODE>Detail</CODE> object
* @throws SOAPException
* if this <CODE>SOAPFault</CODE> object already contains a
* valid <CODE>Detail</CODE> object
*/
public abstract Detail addDetail() throws SOAPException;
/**
* Sets this <code>SOAPFault</code> 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
* <code>QName</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);
* It is preferable to use this method over setFaultCode(String).
* @param name a <code>Name</code> object giving the fault code to be set.
* It must be namespace qualified.
* @throws SOAPException if there was an error in adding the
* <code>faultcode</code>
* element to the underlying XML tree
*/
public abstract void setFaultCode(Name name) 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 <code>Name</code> 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.
* <p>
* In the future, a QName object version of this method may also be added.
*
* @return a <code>Name</code> representing the faultcode
*/
public abstract Name getFaultCodeAsName();
/**
* Sets the fault string for this <code>SOAPFault</code> object to the given
* string and localized to the given locale.
*
* @param faultString
* a <code>String</code> giving an explanation of the fault
* @param locale
* a <code>Locale</code> object indicating the native language of
* the <code>faultString</code>
* @throws SOAPException
* if there was an error in adding the <code>faultString</code>
* to the underlying XML tree
*/
public abstract void setFaultString(String faultString, Locale locale)
throws SOAPException;
/**
* Returns the optional detail element for this <code>SOAPFault</code>
* object.
*
* @return a <code>Locale</code> object indicating the native language of
* the fault string or <code>null</code> if no locale was specified
*/
public abstract Locale getFaultStringLocale();
}
|