| /* |
| * 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 <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/> |
| * <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(String) setFaultCode(java.lang.String) |
| */ |
| public abstract String getFaultCode(); |
| |
| /** |
| * Sets this <CODE>SOAPFault</CODE> object with the given fault actor. |
| * <p/> |
| * <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(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/> |
| * <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/> |
| * <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. |
| * <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>QName</code>. This method |
| * provides a convenient way to set a fault code. For example, |
| * <p/> |
| * <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); |
| * <p/> |
| * 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(); |
| |
| 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; |
| } |
