KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > xml > soap > SOAPFault


1 /*
2  * $Id: SOAPFault.java,v 1.20 2006/02/14 04:40:57 vj135062 Exp $
3  * $Revision: 1.20 $
4  * $Date: 2006/02/14 04:40:57 $
5  */
6
7 /*
8  * The contents of this file are subject to the terms
9  * of the Common Development and Distribution License
10  * (the License). You may not use this file except in
11  * compliance with the License.
12  *
13  * You can obtain a copy of the license at
14  * https://glassfish.dev.java.net/public/CDDLv1.0.html.
15  * See the License for the specific language governing
16  * permissions and limitations under the License.
17  *
18  * When distributing Covered Code, include this CDDL
19  * Header Notice in each file and include the License file
20  * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
21  * If applicable, add the following below the CDDL Header,
22  * with the fields enclosed by brackets [] replaced by
23  * you own identifying information:
24  * "Portions Copyrighted [year] [name of copyright owner]"
25  *
26  * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
27  */
28 package javax.xml.soap;
29
30 import java.util.Iterator JavaDoc;
31 import java.util.Locale JavaDoc;
32
33 import javax.xml.namespace.QName JavaDoc;
34
35 /**
36  * An element in the <code>SOAPBody</code> object that contains
37  * error and/or status information. This information may relate to
38  * errors in the <code>SOAPMessage</code> object or to problems
39  * that are not related to the content in the message itself. Problems
40  * not related to the message itself are generally errors in
41  * processing, such as the inability to communicate with an upstream
42  * server.
43  * <P>
44  * Depending on the <code>protocol</code> specified while creating the
45  * <code>MessageFactory</code> instance, a <code>SOAPFault</code> has
46  * sub-elements as defined in the SOAP 1.1/SOAP 1.2 specification.
47  */
48 public interface SOAPFault extends SOAPBodyElement JavaDoc {
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 SAAJ 1.2
78      */
79     public void setFaultCode(Name JavaDoc faultCodeQName) throws SOAPException JavaDoc;
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 SAAJ 1.3
97      */
98     public void setFaultCode(QName JavaDoc faultCodeQName) throws SOAPException JavaDoc;
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 JavaDoc faultCode) throws SOAPException JavaDoc;
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 SAAJ 1.2
134      */
135     public Name JavaDoc 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 SAAJ 1.3
147      */
148     public QName JavaDoc 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 SAAJ 1.3
164      */
165     public Iterator JavaDoc 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 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 SAAJ 1.3
193      */
194     public void appendFaultSubcode(QName JavaDoc subcode) throws SOAPException JavaDoc;
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 JavaDoc 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 JavaDoc faultActor) throws SOAPException JavaDoc;
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 JavaDoc 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 JavaDoc faultString) throws SOAPException JavaDoc;
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 SAAJ 1.2
276      */
277     public void setFaultString(String JavaDoc faultString, Locale JavaDoc locale)
278         throws SOAPException JavaDoc;
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 JavaDoc 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 SAAJ 1.2
321      */
322     public Locale JavaDoc 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 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 JavaDoc 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 JavaDoc addDetail() throws SOAPException JavaDoc;
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 SAAJ 1.3
383      */
384     public Iterator JavaDoc getFaultReasonLocales() throws SOAPException JavaDoc;
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 SAAJ 1.3
399      */
400     public Iterator JavaDoc getFaultReasonTexts() throws SOAPException JavaDoc;
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 SAAJ 1.3
420      */
421     public String JavaDoc getFaultReasonText(Locale JavaDoc locale) throws SOAPException JavaDoc;
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 SAAJ 1.3
447      */
448     public void addFaultReasonText(String JavaDoc text, java.util.Locale JavaDoc locale)
449         throws SOAPException JavaDoc;
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 SAAJ 1.3
463      */
464     public String JavaDoc 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 SAAJ 1.3
478      */
479     public void setFaultNode(String JavaDoc uri) throws SOAPException JavaDoc;
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 SAAJ 1.3
493      */
494     public String JavaDoc 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 SAAJ 1.3
510      */
511     public void setFaultRole(String JavaDoc uri) throws SOAPException JavaDoc;
512
513 }
514
Popular Tags