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