1 /*
2 * $Id: SOAPFault.java,v 1.19 2005/09/26 21:09:04 mk125090 Exp $
3 * $Revision: 1.19 $
4 * $Date: 2005/09/26 21:09:04 $
5 */
6
7 /*
8 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
9 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
10 *
11 * This code is free software; you can redistribute it and/or modify it
12 * under the terms of the GNU General Public License version 2 only, as
13 * published by the Free Software Foundation. Sun designates this
14 * particular file as subject to the "Classpath" exception as provided
15 * by Sun in the LICENSE file that accompanied this code.
16 *
17 * This code is distributed in the hope that it will be useful, but WITHOUT
18 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
20 * version 2 for more details (a copy is included in the LICENSE file that
21 * accompanied this code).
22 *
23 * You should have received a copy of the GNU General Public License version
24 * 2 along with this work; if not, write to the Free Software Foundation,
25 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
26 *
27 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
28 * CA 95054 USA or visit www.sun.com if you need additional information or
29 * have any questions.
30 */
31 package javax.xml.soap;
32
33 import java.util.Iterator;
34 import java.util.Locale;
35
36 import javax.xml.namespace.QName;
37
38 /**
39 * An element in the <code>SOAPBody</code> object that contains
40 * error and/or status information. This information may relate to
41 * errors in the <code>SOAPMessage</code> object or to problems
42 * that are not related to the content in the message itself. Problems
43 * not related to the message itself are generally errors in
44 * processing, such as the inability to communicate with an upstream
45 * server.
46 * <P>
47 * Depending on the <code>protocol</code> specified while creating the
48 * <code>MessageFactory</code> instance, a <code>SOAPFault</code> has
49 * sub-elements as defined in the SOAP 1.1/SOAP 1.2 specification.
50 */
51 public interface SOAPFault extends SOAPBodyElement {
52
53 /**
54 * Sets this <code>SOAPFault</code> object with the given fault code.
55 *
56 * <P> Fault codes, which give information about the fault, are defined
57 * in the SOAP 1.1 specification. A fault code is mandatory and must
58 * be of type <code>Name</code>. This method provides a convenient
59 * way to set a fault code. For example,
60 *
61 * <PRE>
62 * SOAPEnvelope se = ...;
63 * // Create a qualified name in the SOAP namespace with a localName
64 * // of "Client". Note that prefix parameter is optional and is null
65 * // here which causes the implementation to use an appropriate prefix.
66 * Name qname = se.createName("Client", null,
67 * SOAPConstants.URI_NS_SOAP_ENVELOPE);
68 * SOAPFault fault = ...;
69 * fault.setFaultCode(qname);
70 * </PRE>
71 * It is preferable to use this method over {@link #setFaultCode(String)}.
72 *
73 * @param faultCodeQName a <code>Name</code> object giving the fault
74 * code to be set. It must be namespace qualified.
75 * @see #getFaultCodeAsName
76 *
77 * @exception SOAPException if there was an error in adding the
78 * <i>faultcode</i> element to the underlying XML tree.
79 *
80 * @since SAAJ 1.2
81 */
82 public void setFaultCode(Name faultCodeQName) throws SOAPException;
83
84 /**
85 * Sets this <code>SOAPFault</code> object with the given fault code.
86 *
87 * It is preferable to use this method over {@link #setFaultCode(Name)}.
88 *
89 * @param faultCodeQName a <code>QName</code> object giving the fault
90 * code to be set. It must be namespace qualified.
91 * @see #getFaultCodeAsQName
92 *
93 * @exception SOAPException if there was an error in adding the
94 * <code>faultcode</code> element to the underlying XML tree.
95 *
96 * @see #setFaultCode(Name)
97 * @see #getFaultCodeAsQName()
98 *
99 * @since SAAJ 1.3
100 */
101 public void setFaultCode(QName faultCodeQName) throws SOAPException;
102
103 /**
104 * Sets this <code>SOAPFault</code> object with the give fault code.
105 * <P>
106 * Fault codes, which given information about the fault, are defined in
107 * the SOAP 1.1 specification. This element is mandatory in SOAP 1.1.
108 * Because the fault code is required to be a QName it is preferable to
109 * use the {@link #setFaultCode(Name)} form of this method.
110 *
111 * @param faultCode a <code>String</code> giving the fault code to be set.
112 * It must be of the form "prefix:localName" where the prefix has
113 * been defined in a namespace declaration.
114 * @see #setFaultCode(Name)
115 * @see #getFaultCode
116 * @see SOAPElement#addNamespaceDeclaration
117 *
118 * @exception SOAPException if there was an error in adding the
119 * <code>faultCode</code> to the underlying XML tree.
120 */
121 public void setFaultCode(String faultCode) throws SOAPException;
122
123 /**
124 * Gets the mandatory SOAP 1.1 fault code for this
125 * <code>SOAPFault</code> object as a SAAJ <code>Name</code> object.
126 * The SOAP 1.1 specification requires the value of the "faultcode"
127 * element to be of type QName. This method returns the content of the
128 * element as a QName in the form of a SAAJ Name object. This method
129 * should be used instead of the <code>getFaultCode</code> method since
130 * it allows applications to easily access the namespace name without
131 * additional parsing.
132 *
133 * @return a <code>Name</code> representing the faultcode
134 * @see #setFaultCode(Name)
135 *
136 * @since SAAJ 1.2
137 */
138 public Name getFaultCodeAsName();
139
140
141 /**
142 * Gets the fault code for this
143 * <code>SOAPFault</code> object as a <code>QName</code> object.
144 *
145 * @return a <code>QName</code> representing the faultcode
146 *
147 * @see #setFaultCode(QName)
148 *
149 * @since SAAJ 1.3
150 */
151 public QName getFaultCodeAsQName();
152
153 /**
154 * Gets the Subcodes for this <code>SOAPFault</code> as an iterator over
155 * <code>QNames</code>.
156 *
157 * @return an <code>Iterator</code> that accesses a sequence of
158 * <code>QNames</code>. This <code>Iterator</code> should not support
159 * the optional <code>remove</code> method. The order in which the
160 * Subcodes are returned reflects the hierarchy of Subcodes present
161 * in the fault from top to bottom.
162 *
163 * @exception UnsupportedOperationException if this message does not
164 * support the SOAP 1.2 concept of Subcode.
165 *
166 * @since SAAJ 1.3
167 */
168 public Iterator getFaultSubcodes();
169
170 /**
171 * Removes any Subcodes that may be contained by this
172 * <code>SOAPFault</code>. Subsequent calls to
173 * <code>getFaultSubcodes</code> will return an empty iterator until a call
174 * to <code>appendFaultSubcode</code> is made.
175 *
176 * @exception UnsupportedOperationException if this message does not
177 * support the SOAP 1.2 concept of Subcode.
178 *
179 * @since SAAJ 1.3
180 */
181 public void removeAllFaultSubcodes();
182
183 /**
184 * Adds a Subcode to the end of the sequence of Subcodes contained by this
185 * <code>SOAPFault</code>. Subcodes, which were introduced in SOAP 1.2, are
186 * represented by a recursive sequence of subelements rooted in the
187 * mandatory Code subelement of a SOAP Fault.
188 *
189 * @param subcode a QName containing the Value of the Subcode.
190 *
191 * @exception SOAPException if there was an error in setting the Subcode
192 * @exception UnsupportedOperationException if this message does not
193 * support the SOAP 1.2 concept of Subcode.
194 *
195 * @since SAAJ 1.3
196 */
197 public void appendFaultSubcode(QName subcode) throws SOAPException;
198
199 /**
200 * Gets the fault code for this <code>SOAPFault</code> object.
201 *
202 * @return a <code>String</code> with the fault code
203 * @see #getFaultCodeAsName
204 * @see #setFaultCode
205 */
206 public String getFaultCode();
207
208 /**
209 * Sets this <code>SOAPFault</code> object with the given fault actor.
210 * <P>
211 * The fault actor is the recipient in the message path who caused the
212 * fault to happen.
213 * <P>
214 * If this <code>SOAPFault</code> supports SOAP 1.2 then this call is
215 * equivalent to {@link #setFaultRole(String)}
216 *
217 * @param faultActor a <code>String</code> identifying the actor that
218 * caused this <code>SOAPFault</code> object
219 * @see #getFaultActor
220 *
221 * @exception SOAPException if there was an error in adding the
222 * <code>faultActor</code> to the underlying XML tree.
223 */
224 public void setFaultActor(String faultActor) throws SOAPException;
225
226 /**
227 * Gets the fault actor for this <code>SOAPFault</code> object.
228 * <P>
229 * If this <code>SOAPFault</code> supports SOAP 1.2 then this call is
230 * equivalent to {@link #getFaultRole()}
231 *
232 * @return a <code>String</code> giving the actor in the message path
233 * that caused this <code>SOAPFault</code> object
234 * @see #setFaultActor
235 */
236 public String getFaultActor();
237
238 /**
239 * Sets the fault string for this <code>SOAPFault</code> object
240 * to the given string.
241 * <P>
242 * If this
243 * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then
244 * this call is equivalent to:
245 * <pre>
246 * addFaultReasonText(faultString, Locale.getDefault());
247 * </pre>
248 *
249 * @param faultString a <code>String</code> giving an explanation of
250 * the fault
251 * @see #getFaultString
252 *
253 * @exception SOAPException if there was an error in adding the
254 * <code>faultString</code> to the underlying XML tree.
255 */
256 public void setFaultString(String faultString) throws SOAPException;
257
258 /**
259 * Sets the fault string for this <code>SOAPFault</code> object
260 * to the given string and localized to the given locale.
261 * <P>
262 * If this
263 * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then
264 * this call is equivalent to:
265 * <pre>
266 * addFaultReasonText(faultString, locale);
267 * </pre>
268 *
269 * @param faultString a <code>String</code> giving an explanation of
270 * the fault
271 * @param locale a {@link java.util.Locale Locale} object indicating
272 * the native language of the <code>faultString</code>
273 * @see #getFaultString
274 *
275 * @exception SOAPException if there was an error in adding the
276 * <code>faultString</code> to the underlying XML tree.
277 *
278 * @since SAAJ 1.2
279 */
280 public void setFaultString(String faultString, Locale locale)
281 throws SOAPException;
282
283 /**
284 * Gets the fault string for this <code>SOAPFault</code> object.
285 * <P>
286 * If this
287 * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then
288 * this call is equivalent to:
289 * <pre>
290 * String reason = null;
291 * try {
292 * reason = (String) getFaultReasonTexts().next();
293 * } catch (SOAPException e) {}
294 * return reason;
295 * </pre>
296 *
297 * @return a <code>String</code> giving an explanation of
298 * the fault
299 * @see #setFaultString(String)
300 * @see #setFaultString(String, Locale)
301 */
302 public String getFaultString();
303
304 /**
305 * Gets the locale of the fault string for this <code>SOAPFault</code>
306 * object.
307 * <P>
308 * If this
309 * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then
310 * this call is equivalent to:
311 * <pre>
312 * Locale locale = null;
313 * try {
314 * locale = (Locale) getFaultReasonLocales().next();
315 * } catch (SOAPException e) {}
316 * return locale;
317 * </pre>
318 *
319 * @return a <code>Locale</code> object indicating the native language of
320 * the fault string or <code>null</code> if no locale was specified
321 * @see #setFaultString(String, Locale)
322 *
323 * @since SAAJ 1.2
324 */
325 public Locale getFaultStringLocale();
326
327 /**
328 * Returns true if this <code>SOAPFault</code> has a <code>Detail</code>
329 * subelement and false otherwise. Equivalent to
330 * <code>(getDetail()!=null)</code>.
331 *
332 * @return true if this <code>SOAPFault</code> has a <code>Detail</code>
333 * subelement and false otherwise.
334 *
335 * @since SAAJ 1.3
336 */
337 public boolean hasDetail();
338
339 /**
340 * Returns the optional detail element for this <code>SOAPFault</code>
341 * object.
342 * <P>
343 * A <code>Detail</code> object carries application-specific error
344 * information, the scope of the error information is restricted to
345 * faults in the <code>SOAPBodyElement</code> objects if this is a
346 * SOAP 1.1 Fault.
347 *
348 * @return a <code>Detail</code> object with application-specific
349 * error information if present, null otherwise
350 */
351 public Detail getDetail();
352
353 /**
354 * Creates an optional <code>Detail</code> object and sets it as the
355 * <code>Detail</code> object for this <code>SOAPFault</code>
356 * object.
357 * <P>
358 * It is illegal to add a detail when the fault already
359 * contains a detail. Therefore, this method should be called
360 * only after the existing detail has been removed.
361 *
362 * @return the new <code>Detail</code> object
363 *
364 * @exception SOAPException if this
365 * <code>SOAPFault</code> object already contains a
366 * valid <code>Detail</code> object
367 */
368 public Detail addDetail() throws SOAPException;
369
370 /**
371 * Returns an <code>Iterator</code> over a distinct sequence of
372 * <code>Locale</code>s for which there are associated Reason Text items.
373 * Any of these <code>Locale</code>s can be used in a call to
374 * <code>getFaultReasonText</code> in order to obtain a localized version
375 * of the Reason Text string.
376 *
377 * @return an <code>Iterator</code> over a sequence of <code>Locale</code>
378 * objects for which there are associated Reason Text items.
379 *
380 * @exception SOAPException if there was an error in retrieving
381 * the fault Reason locales.
382 * @exception UnsupportedOperationException if this message does not
383 * support the SOAP 1.2 concept of Fault Reason.
384 *
385 * @since SAAJ 1.3
386 */
387 public Iterator getFaultReasonLocales() throws SOAPException;
388
389 /**
390 * Returns an <code>Iterator</code> over a sequence of
391 * <code>String</code> objects containing all of the Reason Text items for
392 * this <code>SOAPFault</code>.
393 *
394 * @return an <code>Iterator</code> over env:Fault/env:Reason/env:Text items.
395 *
396 * @exception SOAPException if there was an error in retrieving
397 * the fault Reason texts.
398 * @exception UnsupportedOperationException if this message does not
399 * support the SOAP 1.2 concept of Fault Reason.
400 *
401 * @since SAAJ 1.3
402 */
403 public Iterator getFaultReasonTexts() throws SOAPException;
404
405 /**
406 * Returns the Reason Text associated with the given <code>Locale</code>.
407 * If more than one such Reason Text exists the first matching Text is
408 * returned
409 *
410 * @param locale -- the <code>Locale</code> for which a localized
411 * Reason Text is desired
412 *
413 * @return the Reason Text associated with <code>locale</code>
414 *
415 * @see #getFaultString
416 *
417 * @exception SOAPException if there was an error in retrieving
418 * the fault Reason text for the specified locale .
419 * @exception UnsupportedOperationException if this message does not
420 * support the SOAP 1.2 concept of Fault Reason.
421 *
422 * @since SAAJ 1.3
423 */
424 public String getFaultReasonText(Locale locale) throws SOAPException;
425
426 /**
427 * Appends or replaces a Reason Text item containing the specified
428 * text message and an <i>xml:lang</i> derived from
429 * <code>locale</code>. If a Reason Text item with this
430 * <i>xml:lang</i> already exists its text value will be replaced
431 * with <code>text</code>.
432 * The <code>locale</code> parameter should not be <code>null</code>
433 * <P>
434 * Code sample:
435 *
436 * <PRE>
437 * SOAPFault fault = ...;
438 * fault.addFaultReasonText("Version Mismatch", Locale.ENGLISH);
439 * </PRE>
440 *
441 * @param text -- reason message string
442 * @param locale -- Locale object representing the locale of the message
443 *
444 * @exception SOAPException if there was an error in adding the Reason text
445 * or the <code>locale</code> passed was <code>null</code>.
446 * @exception UnsupportedOperationException if this message does not
447 * support the SOAP 1.2 concept of Fault Reason.
448 *
449 * @since SAAJ 1.3
450 */
451 public void addFaultReasonText(String text, java.util.Locale locale)
452 throws SOAPException;
453
454 /**
455 * Returns the optional Node element value for this
456 * <code>SOAPFault</code> object. The Node element is
457 * optional in SOAP 1.2.
458 *
459 * @return Content of the env:Fault/env:Node element as a String
460 * or <code>null</code> if none
461 *
462 * @exception UnsupportedOperationException if this message does not
463 * support the SOAP 1.2 concept of Fault Node.
464 *
465 * @since SAAJ 1.3
466 */
467 public String getFaultNode();
468
469 /**
470 * Creates or replaces any existing Node element value for
471 * this <code>SOAPFault</code> object. The Node element
472 * is optional in SOAP 1.2.
473 *
474 * @exception SOAPException if there was an error in setting the
475 * Node for this <code>SOAPFault</code> object.
476 * @exception UnsupportedOperationException if this message does not
477 * support the SOAP 1.2 concept of Fault Node.
478 *
479 *
480 * @since SAAJ 1.3
481 */
482 public void setFaultNode(String uri) throws SOAPException;
483
484 /**
485 * Returns the optional Role element value for this
486 * <code>SOAPFault</code> object. The Role element is
487 * optional in SOAP 1.2.
488 *
489 * @return Content of the env:Fault/env:Role element as a String
490 * or <code>null</code> if none
491 *
492 * @exception UnsupportedOperationException if this message does not
493 * support the SOAP 1.2 concept of Fault Role.
494 *
495 * @since SAAJ 1.3
496 */
497 public String getFaultRole();
498
499 /**
500 * Creates or replaces any existing Role element value for
501 * this <code>SOAPFault</code> object. The Role element
502 * is optional in SOAP 1.2.
503 *
504 * @param uri - the URI of the Role
505 *
506 * @exception SOAPException if there was an error in setting the
507 * Role for this <code>SOAPFault</code> object.
508 *
509 * @exception UnsupportedOperationException if this message does not
510 * support the SOAP 1.2 concept of Fault Role.
511 *
512 * @since SAAJ 1.3
513 */
514 public void setFaultRole(String uri) throws SOAPException;
515
516 }
Save This Page