javax.xml.soap.SOAPFault Maven / Gradle / Ivy
/*
* 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 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(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(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();
public abstract void addFaultReasonText(java.lang.String reasonText,
java.util.Locale locale)
throws SOAPException;
public abstract void appendFaultSubcode(javax.xml.namespace.QName qname)
throws SOAPException;
public abstract javax.xml.namespace.QName getFaultCodeAsQName();
public abstract java.lang.String getFaultNode();
public abstract java.util.Iterator getFaultReasonLocales()
throws SOAPException;
public abstract java.lang.String getFaultReasonText(java.util.Locale locale)
throws SOAPException;
public abstract java.util.Iterator getFaultReasonTexts()
throws SOAPException;
public abstract java.lang.String getFaultRole();
public abstract java.util.Iterator getFaultSubcodes();
public abstract boolean hasDetail();
public abstract void removeAllFaultSubcodes();
public abstract void setFaultCode(javax.xml.namespace.QName qname)
throws SOAPException;
public abstract void setFaultNode(java.lang.String s)
throws SOAPException;
public abstract void setFaultRole(java.lang.String s)
throws SOAPException;
}