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