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