001 /*
002 * Copyright 2001-2004 The Apache Software Foundation.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package javax.xml.soap;
017
018 import java.util.Locale;
019
020 /**
021 * An element in the <CODE>SOAPBody</CODE> object that contains
022 * error and/or status information. This information may relate to
023 * errors in the <CODE>SOAPMessage</CODE> object or to problems
024 * that are not related to the content in the message itself.
025 * Problems not related to the message itself are generally errors
026 * in processing, such as the inability to communicate with an
027 * upstream server.
028 * <P>
029 * The <CODE>SOAPFault</CODE> interface provides methods for
030 * retrieving the information contained in a <CODE>
031 * SOAPFault</CODE> object and for setting the fault code, the
032 * fault actor, and a string describing the fault. A fault code is
033 * one of the codes defined in the SOAP 1.1 specification that
034 * describe the fault. An actor is an intermediate recipient to
035 * whom a message was routed. The message path may include one or
036 * more actors, or, if no actors are specified, the message goes
037 * only to the default actor, which is the final intended
038 * recipient.
039 */
040 public interface SOAPFault extends SOAPBodyElement {
041
042 /**
043 * Sets this <CODE>SOAPFault</CODE> object with the given
044 * fault code.
045 *
046 * <P>Fault codes, which given information about the fault,
047 * are defined in the SOAP 1.1 specification.</P>
048 * @param faultCode a <CODE>String</CODE> giving
049 * the fault code to be set; must be one of the fault codes
050 * defined in the SOAP 1.1 specification
051 * @throws SOAPException if there was an error in
052 * adding the <CODE>faultCode</CODE> to the underlying XML
053 * tree.
054 * @see #getFaultCode() getFaultCode()
055 */
056 public abstract void setFaultCode(String faultCode) throws SOAPException;
057
058 /**
059 * Gets the fault code for this <CODE>SOAPFault</CODE>
060 * object.
061 * @return a <CODE>String</CODE> with the fault code
062 * @see #setFaultCode(java.lang.String) setFaultCode(java.lang.String)
063 */
064 public abstract String getFaultCode();
065
066 /**
067 * Sets this <CODE>SOAPFault</CODE> object with the given
068 * fault actor.
069 *
070 * <P>The fault actor is the recipient in the message path who
071 * caused the fault to happen.</P>
072 * @param faultActor a <CODE>String</CODE>
073 * identifying the actor that caused this <CODE>
074 * SOAPFault</CODE> object
075 * @throws SOAPException if there was an error in
076 * adding the <CODE>faultActor</CODE> to the underlying XML
077 * tree.
078 * @see #getFaultActor() getFaultActor()
079 */
080 public abstract void setFaultActor(String faultActor) throws SOAPException;
081
082 /**
083 * Gets the fault actor for this <CODE>SOAPFault</CODE>
084 * object.
085 * @return a <CODE>String</CODE> giving the actor in the message
086 * path that caused this <CODE>SOAPFault</CODE> object
087 * @see #setFaultActor(java.lang.String) setFaultActor(java.lang.String)
088 */
089 public abstract String getFaultActor();
090
091 /**
092 * Sets the fault string for this <CODE>SOAPFault</CODE>
093 * object to the given string.
094 *
095 * @param faultString a <CODE>String</CODE>
096 * giving an explanation of the fault
097 * @throws SOAPException if there was an error in
098 * adding the <CODE>faultString</CODE> to the underlying XML
099 * tree.
100 * @see #getFaultString() getFaultString()
101 */
102 public abstract void setFaultString(String faultString)
103 throws SOAPException;
104
105 /**
106 * Gets the fault string for this <CODE>SOAPFault</CODE>
107 * object.
108 * @return a <CODE>String</CODE> giving an explanation of the
109 * fault
110 */
111 public abstract String getFaultString();
112
113 /**
114 * Returns the detail element for this <CODE>SOAPFault</CODE>
115 * object.
116 *
117 * <P>A <CODE>Detail</CODE> object carries
118 * application-specific error information related to <CODE>
119 * SOAPBodyElement</CODE> objects.</P>
120 * @return a <CODE>Detail</CODE> object with
121 * application-specific error information
122 */
123 public abstract Detail getDetail();
124
125 /**
126 * Creates a <CODE>Detail</CODE> object and sets it as the
127 * <CODE>Detail</CODE> object for this <CODE>SOAPFault</CODE>
128 * object.
129 *
130 * <P>It is illegal to add a detail when the fault already
131 * contains a detail. Therefore, this method should be called
132 * only after the existing detail has been removed.</P>
133 * @return the new <CODE>Detail</CODE> object
134 * @throws SOAPException if this
135 * <CODE>SOAPFault</CODE> object already contains a valid
136 * <CODE>Detail</CODE> object
137 */
138 public abstract Detail addDetail() throws SOAPException;
139
140 /**
141 * Sets this <code>SOAPFault</code> object with the given fault code.
142 *
143 * Fault codes, which give information about the fault, are defined in the
144 * SOAP 1.1 specification. A fault code is mandatory and must be of type
145 * <code>QName</code>. This method provides a convenient way to set a fault
146 * code. For example,
147 *
148 * <pre>
149 SOAPEnvelope se = ...;
150 // Create a qualified name in the SOAP namespace with a localName
151 // of "Client". Note that prefix parameter is optional and is null
152 // here which causes the implementation to use an appropriate prefix.
153 Name qname = se.createName("Client", null,
154 SOAPConstants.URI_NS_SOAP_ENVELOPE);
155 SOAPFault fault = ...;
156 fault.setFaultCode(qname);
157 *
158 * It is preferable to use this method over setFaultCode(String).
159 *
160 * @param name a <code>Name</code> object giving the fault code to be set.
161 * It must be namespace qualified.
162 * @throws SOAPException if there was an error in adding the
163 * <code>faultcode</code> element to the underlying XML tree
164 */
165 public abstract void setFaultCode(Name name) throws SOAPException;
166
167 /**
168 * Gets the mandatory SOAP 1.1 fault code for this <code>SOAPFault</code>
169 * object as a SAAJ <code>Name</code> object. The SOAP 1.1 specification
170 * requires the value of the "faultcode" element to be of type QName. This
171 * method returns the content of the element as a QName in the form of a
172 * SAAJ <code>Name</code> object. This method should be used instead of the
173 * <code>getFaultCode()</code> method since it allows applications to easily
174 * access the namespace name without additional parsing.
175 * <p>
176 * In the future, a QName object version of this method may also be added.
177 * @return a <code>Name</code> representing the faultcode
178 */
179 public abstract Name getFaultCodeAsName();
180
181 /**
182 * Sets the fault string for this <code>SOAPFault</code> object to the given
183 * string and localized to the given locale.
184 *
185 * @param faultString a <code>String</code> giving an explanation of
186 * the fault
187 * @param locale a <code>Locale</code> object indicating the
188 * native language of the <code>faultString</code>
189 * @throws SOAPException if there was an error in adding the
190 * <code>faultString</code> to the underlying XML tree
191 */
192 public abstract void setFaultString(String faultString, Locale locale) throws SOAPException;
193
194 /**
195 * Returns the optional detail element for this <code>SOAPFault</code>
196 * object.
197 *
198 * @return a <code>Locale</code> object indicating the native language of
199 * the fault string or <code>null</code> if no locale was
200 * specified
201 */
202 public abstract Locale getFaultStringLocale();
203 }