SOAPBody object that contains
- * error and/or status information. This information may relate to
- * errors in the SOAPMessage object or to problems
- * that are not related to the content in the message itself. Problems
- * not related to the message itself are generally errors in
- * processing, such as the inability to communicate with an upstream
- * server.
- *
- * Depending on the protocol specified while creating the
- * MessageFactory instance, a SOAPFault has
- * sub-elements as defined in the SOAP 1.1/SOAP 1.2 specification.
- *
- * @since 1.6
- */
-public interface SOAPFault extends SOAPBodyElement {
-
- /**
- * Sets this SOAPFault object with the given fault code.
- *
- *
Fault codes, which give information about the fault, are defined
- * in the SOAP 1.1 specification. A fault code is mandatory and must
- * be of type Name. This method provides a convenient
- * way to set a fault code. For example,
- *
- *
- * SOAPEnvelope se = ...;
- * // Create a qualified name in the SOAP namespace with a localName
- * // of "Client". Note that prefix parameter is optional and is null
- * // here which causes the implementation to use an appropriate prefix.
- * Name qname = se.createName("Client", null,
- * SOAPConstants.URI_NS_SOAP_ENVELOPE);
- * SOAPFault fault = ...;
- * fault.setFaultCode(qname);
- *
- * It is preferable to use this method over {@link #setFaultCode(String)}.
- *
- * @param faultCodeQName a Name object giving the fault
- * code to be set. It must be namespace qualified.
- * @see #getFaultCodeAsName
- *
- * @exception SOAPException if there was an error in adding the
- * faultcode element to the underlying XML tree.
- *
- * @since 1.6, SAAJ 1.2
- */
- public void setFaultCode(Name faultCodeQName) throws SOAPException;
-
- /**
- * Sets this SOAPFault object with the given fault code.
- *
- * It is preferable to use this method over {@link #setFaultCode(Name)}.
- *
- * @param faultCodeQName a QName object giving the fault
- * code to be set. It must be namespace qualified.
- * @see #getFaultCodeAsQName
- *
- * @exception SOAPException if there was an error in adding the
- * faultcode element to the underlying XML tree.
- *
- * @see #setFaultCode(Name)
- * @see #getFaultCodeAsQName()
- *
- * @since 1.6, SAAJ 1.3
- */
- public void setFaultCode(QName faultCodeQName) throws SOAPException;
-
- /**
- * Sets this SOAPFault object with the give fault code.
- *
- * Fault codes, which given information about the fault, are defined in
- * the SOAP 1.1 specification. This element is mandatory in SOAP 1.1.
- * Because the fault code is required to be a QName it is preferable to
- * use the {@link #setFaultCode(Name)} form of this method.
- *
- * @param faultCode a String giving the fault code to be set.
- * It must be of the form "prefix:localName" where the prefix has
- * been defined in a namespace declaration.
- * @see #setFaultCode(Name)
- * @see #getFaultCode
- * @see SOAPElement#addNamespaceDeclaration
- *
- * @exception SOAPException if there was an error in adding the
- * faultCode to the underlying XML tree.
- */
- public void setFaultCode(String faultCode) throws SOAPException;
-
- /**
- * Gets the mandatory SOAP 1.1 fault code for this
- * SOAPFault object as a SAAJ Name object.
- * The SOAP 1.1 specification requires the value of the "faultcode"
- * element to be of type QName. This method returns the content of the
- * element as a QName in the form of a SAAJ Name object. This method
- * should be used instead of the getFaultCode method since
- * it allows applications to easily access the namespace name without
- * additional parsing.
- *
- * @return a Name representing the faultcode
- * @see #setFaultCode(Name)
- *
- * @since 1.6, SAAJ 1.2
- */
- public Name getFaultCodeAsName();
-
-
- /**
- * Gets the fault code for this
- * SOAPFault object as a QName object.
- *
- * @return a QName representing the faultcode
- *
- * @see #setFaultCode(QName)
- *
- * @since 1.6, SAAJ 1.3
- */
- public QName getFaultCodeAsQName();
-
- /**
- * Gets the Subcodes for this SOAPFault as an iterator over
- * QNames.
- *
- * @return an Iterator that accesses a sequence of
- * QNames. This Iterator should not support
- * the optional remove method. The order in which the
- * Subcodes are returned reflects the hierarchy of Subcodes present
- * in the fault from top to bottom.
- *
- * @exception UnsupportedOperationException if this message does not
- * support the SOAP 1.2 concept of Subcode.
- *
- * @since 1.6, SAAJ 1.3
- */
- public Iterator getFaultSubcodes();
-
- /**
- * Removes any Subcodes that may be contained by this
- * SOAPFault. Subsequent calls to
- * getFaultSubcodes will return an empty iterator until a call
- * to appendFaultSubcode is made.
- *
- * @exception UnsupportedOperationException if this message does not
- * support the SOAP 1.2 concept of Subcode.
- *
- * @since 1.6, SAAJ 1.3
- */
- public void removeAllFaultSubcodes();
-
- /**
- * Adds a Subcode to the end of the sequence of Subcodes contained by this
- * SOAPFault. Subcodes, which were introduced in SOAP 1.2, are
- * represented by a recursive sequence of subelements rooted in the
- * mandatory Code subelement of a SOAP Fault.
- *
- * @param subcode a QName containing the Value of the Subcode.
- *
- * @exception SOAPException if there was an error in setting the Subcode
- * @exception UnsupportedOperationException if this message does not
- * support the SOAP 1.2 concept of Subcode.
- *
- * @since 1.6, SAAJ 1.3
- */
- public void appendFaultSubcode(QName subcode) throws SOAPException;
-
- /**
- * Gets the fault code for this SOAPFault object.
- *
- * @return a String with the fault code
- * @see #getFaultCodeAsName
- * @see #setFaultCode
- */
- public String getFaultCode();
-
- /**
- * Sets this SOAPFault object with the given fault actor.
- *
- * The fault actor is the recipient in the message path who caused the - * fault to happen. - *
- * If this SOAPFault supports SOAP 1.2 then this call is
- * equivalent to {@link #setFaultRole(String)}
- *
- * @param faultActor a String identifying the actor that
- * caused this SOAPFault object
- * @see #getFaultActor
- *
- * @exception SOAPException if there was an error in adding the
- * faultActor to the underlying XML tree.
- */
- public void setFaultActor(String faultActor) throws SOAPException;
-
- /**
- * Gets the fault actor for this SOAPFault object.
- *
- * If this SOAPFault supports SOAP 1.2 then this call is
- * equivalent to {@link #getFaultRole()}
- *
- * @return a String giving the actor in the message path
- * that caused this SOAPFault object
- * @see #setFaultActor
- */
- public String getFaultActor();
-
- /**
- * Sets the fault string for this SOAPFault object
- * to the given string.
- *
- * If this
- * SOAPFault is part of a message that supports SOAP 1.2 then
- * this call is equivalent to:
- *
- * addFaultReasonText(faultString, Locale.getDefault()); - *- * - * @param faultString a
String giving an explanation of
- * the fault
- * @see #getFaultString
- *
- * @exception SOAPException if there was an error in adding the
- * faultString to the underlying XML tree.
- */
- public void setFaultString(String faultString) throws SOAPException;
-
- /**
- * Sets the fault string for this SOAPFault object
- * to the given string and localized to the given locale.
- *
- * If this
- * SOAPFault is part of a message that supports SOAP 1.2 then
- * this call is equivalent to:
- *
- * addFaultReasonText(faultString, locale); - *- * - * @param faultString a
String giving an explanation of
- * the fault
- * @param locale a {@link java.util.Locale Locale} object indicating
- * the native language of the faultString
- * @see #getFaultString
- *
- * @exception SOAPException if there was an error in adding the
- * faultString to the underlying XML tree.
- *
- * @since 1.6, SAAJ 1.2
- */
- public void setFaultString(String faultString, Locale locale)
- throws SOAPException;
-
- /**
- * Gets the fault string for this SOAPFault object.
- *
- * If this
- * SOAPFault is part of a message that supports SOAP 1.2 then
- * this call is equivalent to:
- *
- * String reason = null;
- * try {
- * reason = (String) getFaultReasonTexts().next();
- * } catch (SOAPException e) {}
- * return reason;
- *
- *
- * @return a String giving an explanation of
- * the fault
- * @see #setFaultString(String)
- * @see #setFaultString(String, Locale)
- */
- public String getFaultString();
-
- /**
- * Gets the locale of the fault string for this SOAPFault
- * object.
- *
- * If this
- * SOAPFault is part of a message that supports SOAP 1.2 then
- * this call is equivalent to:
- *
- * Locale locale = null;
- * try {
- * locale = (Locale) getFaultReasonLocales().next();
- * } catch (SOAPException e) {}
- * return locale;
- *
- *
- * @return a Locale object indicating the native language of
- * the fault string or null if no locale was specified
- * @see #setFaultString(String, Locale)
- *
- * @since 1.6, SAAJ 1.2
- */
- public Locale getFaultStringLocale();
-
- /**
- * Returns true if this SOAPFault has a Detail
- * subelement and false otherwise. Equivalent to
- * (getDetail()!=null).
- *
- * @return true if this SOAPFault has a Detail
- * subelement and false otherwise.
- *
- * @since 1.6, SAAJ 1.3
- */
- public boolean hasDetail();
-
- /**
- * Returns the optional detail element for this SOAPFault
- * object.
- *
- * A Detail object carries application-specific error
- * information, the scope of the error information is restricted to
- * faults in the SOAPBodyElement objects if this is a
- * SOAP 1.1 Fault.
- *
- * @return a Detail object with application-specific
- * error information if present, null otherwise
- */
- public Detail getDetail();
-
- /**
- * Creates an optional Detail object and sets it as the
- * Detail object for this SOAPFault
- * object.
- *
- * It is illegal to add a detail when the fault already
- * contains a detail. Therefore, this method should be called
- * only after the existing detail has been removed.
- *
- * @return the new Detail object
- *
- * @exception SOAPException if this
- * SOAPFault object already contains a
- * valid Detail object
- */
- public Detail addDetail() throws SOAPException;
-
- /**
- * Returns an Iterator over a distinct sequence of
- * Locales for which there are associated Reason Text items.
- * Any of these Locales can be used in a call to
- * getFaultReasonText in order to obtain a localized version
- * of the Reason Text string.
- *
- * @return an Iterator over a sequence of Locale
- * objects for which there are associated Reason Text items.
- *
- * @exception SOAPException if there was an error in retrieving
- * the fault Reason locales.
- * @exception UnsupportedOperationException if this message does not
- * support the SOAP 1.2 concept of Fault Reason.
- *
- * @since 1.6, SAAJ 1.3
- */
- public Iterator getFaultReasonLocales() throws SOAPException;
-
- /**
- * Returns an Iterator over a sequence of
- * String objects containing all of the Reason Text items for
- * this SOAPFault.
- *
- * @return an Iterator over env:Fault/env:Reason/env:Text items.
- *
- * @exception SOAPException if there was an error in retrieving
- * the fault Reason texts.
- * @exception UnsupportedOperationException if this message does not
- * support the SOAP 1.2 concept of Fault Reason.
- *
- * @since 1.6, SAAJ 1.3
- */
- public Iterator getFaultReasonTexts() throws SOAPException;
-
- /**
- * Returns the Reason Text associated with the given Locale.
- * If more than one such Reason Text exists the first matching Text is
- * returned
- *
- * @param locale -- the Locale for which a localized
- * Reason Text is desired
- *
- * @return the Reason Text associated with locale
- *
- * @see #getFaultString
- *
- * @exception SOAPException if there was an error in retrieving
- * the fault Reason text for the specified locale .
- * @exception UnsupportedOperationException if this message does not
- * support the SOAP 1.2 concept of Fault Reason.
- *
- * @since 1.6, SAAJ 1.3
- */
- public String getFaultReasonText(Locale locale) throws SOAPException;
-
- /**
- * Appends or replaces a Reason Text item containing the specified
- * text message and an xml:lang derived from
- * locale. If a Reason Text item with this
- * xml:lang already exists its text value will be replaced
- * with text.
- * The locale parameter should not be null
- *
- * Code sample: - * - *
- * SOAPFault fault = ...;
- * fault.addFaultReasonText("Version Mismatch", Locale.ENGLISH);
- *
- *
- * @param text -- reason message string
- * @param locale -- Locale object representing the locale of the message
- *
- * @exception SOAPException if there was an error in adding the Reason text
- * or the locale passed was null.
- * @exception UnsupportedOperationException if this message does not
- * support the SOAP 1.2 concept of Fault Reason.
- *
- * @since 1.6, SAAJ 1.3
- */
- public void addFaultReasonText(String text, java.util.Locale locale)
- throws SOAPException;
-
- /**
- * Returns the optional Node element value for this
- * SOAPFault object. The Node element is
- * optional in SOAP 1.2.
- *
- * @return Content of the env:Fault/env:Node element as a String
- * or null if none
- *
- * @exception UnsupportedOperationException if this message does not
- * support the SOAP 1.2 concept of Fault Node.
- *
- * @since 1.6, SAAJ 1.3
- */
- public String getFaultNode();
-
- /**
- * Creates or replaces any existing Node element value for
- * this SOAPFault object. The Node element
- * is optional in SOAP 1.2.
- *
- * @exception SOAPException if there was an error in setting the
- * Node for this SOAPFault object.
- * @exception UnsupportedOperationException if this message does not
- * support the SOAP 1.2 concept of Fault Node.
- *
- *
- * @since 1.6, SAAJ 1.3
- */
- public void setFaultNode(String uri) throws SOAPException;
-
- /**
- * Returns the optional Role element value for this
- * SOAPFault object. The Role element is
- * optional in SOAP 1.2.
- *
- * @return Content of the env:Fault/env:Role element as a String
- * or null if none
- *
- * @exception UnsupportedOperationException if this message does not
- * support the SOAP 1.2 concept of Fault Role.
- *
- * @since 1.6, SAAJ 1.3
- */
- public String getFaultRole();
-
- /**
- * Creates or replaces any existing Role element value for
- * this SOAPFault object. The Role element
- * is optional in SOAP 1.2.
- *
- * @param uri - the URI of the Role
- *
- * @exception SOAPException if there was an error in setting the
- * Role for this SOAPFault object.
- *
- * @exception UnsupportedOperationException if this message does not
- * support the SOAP 1.2 concept of Fault Role.
- *
- * @since 1.6, SAAJ 1.3
- */
- public void setFaultRole(String uri) throws SOAPException;
-
-}