View Javadoc
1   /*
2    * Copyright (c) 2004, 2012, 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 }