001: /*
002: * $Id: SOAPFault.java,v 1.21 2006/03/30 00:59:41 ofung Exp $
003: * $Revision: 1.21 $
004: * $Date: 2006/03/30 00:59:41 $
005: */
006:
007: /*
008: * The contents of this file are subject to the terms
009: * of the Common Development and Distribution License
010: * (the License). You may not use this file except in
011: * compliance with the License.
012: *
013: * You can obtain a copy of the license at
014: * https://glassfish.dev.java.net/public/CDDLv1.0.html.
015: * See the License for the specific language governing
016: * permissions and limitations under the License.
017: *
018: * When distributing Covered Code, include this CDDL
019: * Header Notice in each file and include the License file
020: * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
021: * If applicable, add the following below the CDDL Header,
022: * with the fields enclosed by brackets [] replaced by
023: * you own identifying information:
024: * "Portions Copyrighted [year] [name of copyright owner]"
025: *
026: * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
027: */
028: package javax.xml.soap;
029:
030: import java.util.Iterator;
031: import java.util.Locale;
032:
033: import javax.xml.namespace.QName;
034:
035: /**
036: * An element in the <code>SOAPBody</code> object that contains
037: * error and/or status information. This information may relate to
038: * errors in the <code>SOAPMessage</code> object or to problems
039: * that are not related to the content in the message itself. Problems
040: * not related to the message itself are generally errors in
041: * processing, such as the inability to communicate with an upstream
042: * server.
043: * <P>
044: * Depending on the <code>protocol</code> specified while creating the
045: * <code>MessageFactory</code> instance, a <code>SOAPFault</code> has
046: * sub-elements as defined in the SOAP 1.1/SOAP 1.2 specification.
047: */
048: public interface SOAPFault extends SOAPBodyElement {
049:
050: /**
051: * Sets this <code>SOAPFault</code> object with the given fault code.
052: *
053: * <P> Fault codes, which give information about the fault, are defined
054: * in the SOAP 1.1 specification. A fault code is mandatory and must
055: * be of type <code>Name</code>. This method provides a convenient
056: * way to set a fault code. For example,
057: *
058: * <PRE>
059: * SOAPEnvelope se = ...;
060: * // Create a qualified name in the SOAP namespace with a localName
061: * // of "Client". Note that prefix parameter is optional and is null
062: * // here which causes the implementation to use an appropriate prefix.
063: * Name qname = se.createName("Client", null,
064: * SOAPConstants.URI_NS_SOAP_ENVELOPE);
065: * SOAPFault fault = ...;
066: * fault.setFaultCode(qname);
067: * </PRE>
068: * It is preferable to use this method over {@link #setFaultCode(String)}.
069: *
070: * @param faultCodeQName a <code>Name</code> object giving the fault
071: * code to be set. It must be namespace qualified.
072: * @see #getFaultCodeAsName
073: *
074: * @exception SOAPException if there was an error in adding the
075: * <i>faultcode</i> element to the underlying XML tree.
076: *
077: * @since SAAJ 1.2
078: */
079: public void setFaultCode(Name faultCodeQName) throws SOAPException;
080:
081: /**
082: * Sets this <code>SOAPFault</code> object with the given fault code.
083: *
084: * It is preferable to use this method over {@link #setFaultCode(Name)}.
085: *
086: * @param faultCodeQName a <code>QName</code> object giving the fault
087: * code to be set. It must be namespace qualified.
088: * @see #getFaultCodeAsQName
089: *
090: * @exception SOAPException if there was an error in adding the
091: * <code>faultcode</code> element to the underlying XML tree.
092: *
093: * @see #setFaultCode(Name)
094: * @see #getFaultCodeAsQName()
095: *
096: * @since SAAJ 1.3
097: */
098: public void setFaultCode(QName faultCodeQName) throws SOAPException;
099:
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 SAAJ 1.2
134: */
135: public Name getFaultCodeAsName();
136:
137: /**
138: * Gets the fault code for this
139: * <code>SOAPFault</code> object as a <code>QName</code> object.
140: *
141: * @return a <code>QName</code> representing the faultcode
142: *
143: * @see #setFaultCode(QName)
144: *
145: * @since SAAJ 1.3
146: */
147: public QName getFaultCodeAsQName();
148:
149: /**
150: * Gets the Subcodes for this <code>SOAPFault</code> as an iterator over
151: * <code>QNames</code>.
152: *
153: * @return an <code>Iterator</code> that accesses a sequence of
154: * <code>QNames</code>. This <code>Iterator</code> should not support
155: * the optional <code>remove</code> method. The order in which the
156: * Subcodes are returned reflects the hierarchy of Subcodes present
157: * in the fault from top to bottom.
158: *
159: * @exception UnsupportedOperationException if this message does not
160: * support the SOAP 1.2 concept of Subcode.
161: *
162: * @since SAAJ 1.3
163: */
164: public Iterator getFaultSubcodes();
165:
166: /**
167: * Removes any Subcodes that may be contained by this
168: * <code>SOAPFault</code>. Subsequent calls to
169: * <code>getFaultSubcodes</code> will return an empty iterator until a call
170: * to <code>appendFaultSubcode</code> is made.
171: *
172: * @exception UnsupportedOperationException if this message does not
173: * support the SOAP 1.2 concept of Subcode.
174: *
175: * @since SAAJ 1.3
176: */
177: public void removeAllFaultSubcodes();
178:
179: /**
180: * Adds a Subcode to the end of the sequence of Subcodes contained by this
181: * <code>SOAPFault</code>. Subcodes, which were introduced in SOAP 1.2, are
182: * represented by a recursive sequence of subelements rooted in the
183: * mandatory Code subelement of a SOAP Fault.
184: *
185: * @param subcode a QName containing the Value of the Subcode.
186: *
187: * @exception SOAPException if there was an error in setting the Subcode
188: * @exception UnsupportedOperationException if this message does not
189: * support the SOAP 1.2 concept of Subcode.
190: *
191: * @since SAAJ 1.3
192: */
193: public void appendFaultSubcode(QName subcode) throws SOAPException;
194:
195: /**
196: * Gets the fault code for this <code>SOAPFault</code> object.
197: *
198: * @return a <code>String</code> with the fault code
199: * @see #getFaultCodeAsName
200: * @see #setFaultCode
201: */
202: public String getFaultCode();
203:
204: /**
205: * Sets this <code>SOAPFault</code> object with the given fault actor.
206: * <P>
207: * The fault actor is the recipient in the message path who caused the
208: * fault to happen.
209: * <P>
210: * If this <code>SOAPFault</code> supports SOAP 1.2 then this call is
211: * equivalent to {@link #setFaultRole(String)}
212: *
213: * @param faultActor a <code>String</code> identifying the actor that
214: * caused this <code>SOAPFault</code> object
215: * @see #getFaultActor
216: *
217: * @exception SOAPException if there was an error in adding the
218: * <code>faultActor</code> to the underlying XML tree.
219: */
220: public void setFaultActor(String faultActor) throws SOAPException;
221:
222: /**
223: * Gets the fault actor for this <code>SOAPFault</code> object.
224: * <P>
225: * If this <code>SOAPFault</code> supports SOAP 1.2 then this call is
226: * equivalent to {@link #getFaultRole()}
227: *
228: * @return a <code>String</code> giving the actor in the message path
229: * that caused this <code>SOAPFault</code> object
230: * @see #setFaultActor
231: */
232: public String getFaultActor();
233:
234: /**
235: * Sets the fault string for this <code>SOAPFault</code> object
236: * to the given string.
237: * <P>
238: * If this
239: * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then
240: * this call is equivalent to:
241: * <pre>
242: * addFaultReasonText(faultString, Locale.getDefault());
243: * </pre>
244: *
245: * @param faultString a <code>String</code> giving an explanation of
246: * the fault
247: * @see #getFaultString
248: *
249: * @exception SOAPException if there was an error in adding the
250: * <code>faultString</code> to the underlying XML tree.
251: */
252: public void setFaultString(String faultString) throws SOAPException;
253:
254: /**
255: * Sets the fault string for this <code>SOAPFault</code> object
256: * to the given string and localized to the given locale.
257: * <P>
258: * If this
259: * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then
260: * this call is equivalent to:
261: * <pre>
262: * addFaultReasonText(faultString, locale);
263: * </pre>
264: *
265: * @param faultString a <code>String</code> giving an explanation of
266: * the fault
267: * @param locale a {@link java.util.Locale Locale} object indicating
268: * the native language of the <code>faultString</code>
269: * @see #getFaultString
270: *
271: * @exception SOAPException if there was an error in adding the
272: * <code>faultString</code> to the underlying XML tree.
273: *
274: * @since SAAJ 1.2
275: */
276: public void setFaultString(String faultString, Locale locale)
277: throws SOAPException;
278:
279: /**
280: * Gets the fault string for this <code>SOAPFault</code> object.
281: * <P>
282: * If this
283: * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then
284: * this call is equivalent to:
285: * <pre>
286: * String reason = null;
287: * try {
288: * reason = (String) getFaultReasonTexts().next();
289: * } catch (SOAPException e) {}
290: * return reason;
291: * </pre>
292: *
293: * @return a <code>String</code> giving an explanation of
294: * the fault
295: * @see #setFaultString(String)
296: * @see #setFaultString(String, Locale)
297: */
298: public String getFaultString();
299:
300: /**
301: * Gets the locale of the fault string for this <code>SOAPFault</code>
302: * object.
303: * <P>
304: * If this
305: * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then
306: * this call is equivalent to:
307: * <pre>
308: * Locale locale = null;
309: * try {
310: * locale = (Locale) getFaultReasonLocales().next();
311: * } catch (SOAPException e) {}
312: * return locale;
313: * </pre>
314: *
315: * @return a <code>Locale</code> object indicating the native language of
316: * the fault string or <code>null</code> if no locale was specified
317: * @see #setFaultString(String, Locale)
318: *
319: * @since SAAJ 1.2
320: */
321: public Locale getFaultStringLocale();
322:
323: /**
324: * Returns true if this <code>SOAPFault</code> has a <code>Detail</code>
325: * subelement and false otherwise. Equivalent to
326: * <code>(getDetail()!=null)</code>.
327: *
328: * @return true if this <code>SOAPFault</code> has a <code>Detail</code>
329: * subelement and false otherwise.
330: *
331: * @since SAAJ 1.3
332: */
333: public boolean hasDetail();
334:
335: /**
336: * Returns the optional detail element for this <code>SOAPFault</code>
337: * object.
338: * <P>
339: * A <code>Detail</code> object carries application-specific error
340: * information, the scope of the error information is restricted to
341: * faults in the <code>SOAPBodyElement</code> objects if this is a
342: * SOAP 1.1 Fault.
343: *
344: * @return a <code>Detail</code> object with application-specific
345: * error information if present, null otherwise
346: */
347: public Detail getDetail();
348:
349: /**
350: * Creates an optional <code>Detail</code> object and sets it as the
351: * <code>Detail</code> object for this <code>SOAPFault</code>
352: * object.
353: * <P>
354: * It is illegal to add a detail when the fault already
355: * contains a detail. Therefore, this method should be called
356: * only after the existing detail has been removed.
357: *
358: * @return the new <code>Detail</code> object
359: *
360: * @exception SOAPException if this
361: * <code>SOAPFault</code> object already contains a
362: * valid <code>Detail</code> object
363: */
364: public Detail addDetail() throws SOAPException;
365:
366: /**
367: * Returns an <code>Iterator</code> over a distinct sequence of
368: * <code>Locale</code>s for which there are associated Reason Text items.
369: * Any of these <code>Locale</code>s can be used in a call to
370: * <code>getFaultReasonText</code> in order to obtain a localized version
371: * of the Reason Text string.
372: *
373: * @return an <code>Iterator</code> over a sequence of <code>Locale</code>
374: * objects for which there are associated Reason Text items.
375: *
376: * @exception SOAPException if there was an error in retrieving
377: * the fault Reason locales.
378: * @exception UnsupportedOperationException if this message does not
379: * support the SOAP 1.2 concept of Fault Reason.
380: *
381: * @since SAAJ 1.3
382: */
383: public Iterator getFaultReasonLocales() throws SOAPException;
384:
385: /**
386: * Returns an <code>Iterator</code> over a sequence of
387: * <code>String</code> objects containing all of the Reason Text items for
388: * this <code>SOAPFault</code>.
389: *
390: * @return an <code>Iterator</code> over env:Fault/env:Reason/env:Text items.
391: *
392: * @exception SOAPException if there was an error in retrieving
393: * the fault Reason texts.
394: * @exception UnsupportedOperationException if this message does not
395: * support the SOAP 1.2 concept of Fault Reason.
396: *
397: * @since SAAJ 1.3
398: */
399: public Iterator getFaultReasonTexts() throws SOAPException;
400:
401: /**
402: * Returns the Reason Text associated with the given <code>Locale</code>.
403: * If more than one such Reason Text exists the first matching Text is
404: * returned
405: *
406: * @param locale -- the <code>Locale</code> for which a localized
407: * Reason Text is desired
408: *
409: * @return the Reason Text associated with <code>locale</code>
410: *
411: * @see #getFaultString
412: *
413: * @exception SOAPException if there was an error in retrieving
414: * the fault Reason text for the specified locale .
415: * @exception UnsupportedOperationException if this message does not
416: * support the SOAP 1.2 concept of Fault Reason.
417: *
418: * @since SAAJ 1.3
419: */
420: public String getFaultReasonText(Locale locale)
421: 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 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 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 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 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 SAAJ 1.3
510: */
511: public void setFaultRole(String uri) throws SOAPException;
512:
513: }
|