< prev index next >

src/java.xml.ws/share/classes/javax/xml/soap/SOAPFault.java

Print this page

        

@@ -1,7 +1,7 @@
 /*
- * Copyright (c) 2004, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2004, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this

@@ -29,47 +29,47 @@
 import java.util.Locale;
 
 import javax.xml.namespace.QName;
 
 /**
- * An element in the <code>SOAPBody</code> object that contains
+ * An element in the {@code SOAPBody} object that contains
  * error and/or status information. This information may relate to
- * errors in the <code>SOAPMessage</code> object or to problems
+ * errors in the {@code 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.
  * <P>
- * Depending on the <code>protocol</code> specified while creating the
- * <code>MessageFactory</code> instance,  a <code>SOAPFault</code> has
+ * Depending on the {@code protocol} specified while creating the
+ * {@code MessageFactory} instance,  a {@code 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 <code>SOAPFault</code> object with the given fault code.
+     * Sets this {@code SOAPFault} object with the given fault code.
      *
      * <P> 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 <code>Name</code>. This method provides a convenient
+     * be of type {@code Name}. This method provides a convenient
      * way to set a fault code. For example,
      *
-     * <PRE>
+     * <pre>{@code
      * 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);
-     * </PRE>
+     * }</pre>
      * It is preferable to use this method over {@link #setFaultCode(String)}.
      *
-     * @param faultCodeQName a <code>Name</code> object giving the fault
+     * @param faultCodeQName a {@code 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
      *            <i>faultcode</i> element to the underlying XML tree.

@@ -77,85 +77,85 @@
      * @since 1.6, SAAJ 1.2
      */
     public void setFaultCode(Name faultCodeQName) throws SOAPException;
 
     /**
-     * Sets this <code>SOAPFault</code> object with the given fault code.
+     * Sets this {@code SOAPFault} object with the given fault code.
      *
      * It is preferable to use this method over {@link #setFaultCode(Name)}.
      *
-     * @param faultCodeQName a <code>QName</code> object giving the fault
+     * @param faultCodeQName a {@code 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
-     *            <code>faultcode</code> element to the underlying XML tree.
+     *            {@code 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 <code>SOAPFault</code> object with the give fault code.
+     * Sets this {@code SOAPFault} object with the give fault code.
      * <P>
      * 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 <code>String</code> giving the fault code to be set.
+     * @param faultCode a {@code 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
-     *            <code>faultCode</code> to the underlying XML tree.
+     *            {@code faultCode} to the underlying XML tree.
      */
     public void setFaultCode(String faultCode) throws SOAPException;
 
     /**
      * Gets the mandatory SOAP 1.1 fault code for this
-     * <code>SOAPFault</code> object as a SAAJ <code>Name</code> object.
+     * {@code SOAPFault} object as a SAAJ {@code 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 <code>getFaultCode</code> method since
+     * should be used instead of the {@code getFaultCode} method since
      * it allows applications to easily access the namespace name without
      * additional parsing.
      *
-     * @return a <code>Name</code> representing the faultcode
+     * @return a {@code Name} representing the faultcode
      * @see #setFaultCode(Name)
      *
      * @since 1.6, SAAJ 1.2
      */
     public Name getFaultCodeAsName();
 
 
     /**
      * Gets the fault code for this
-     * <code>SOAPFault</code> object as a <code>QName</code> object.
+     * {@code SOAPFault} object as a {@code QName} object.
      *
-     * @return a <code>QName</code> representing the faultcode
+     * @return a {@code QName} representing the faultcode
      *
      * @see #setFaultCode(QName)
      *
      * @since 1.6, SAAJ 1.3
      */
     public QName getFaultCodeAsQName();
 
     /**
-     * Gets the Subcodes for this <code>SOAPFault</code> as an iterator over
-     * <code>QNames</code>.
+     * Gets the Subcodes for this {@code SOAPFault} as an iterator over
+     * {@code QNames}.
      *
-     * @return an <code>Iterator</code> that accesses a sequence of
-     *      <code>QNames</code>. This <code>Iterator</code> should not support
-     *      the optional <code>remove</code> method. The order in which the
+     * @return an {@code Iterator} that accesses a sequence of
+     *      {@code QNames}. This {@code Iterator} should not support
+     *      the optional {@code 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.

@@ -164,24 +164,24 @@
      */
     public Iterator getFaultSubcodes();
 
     /**
      * Removes any Subcodes that may be contained by this
-     * <code>SOAPFault</code>. Subsequent calls to
-     * <code>getFaultSubcodes</code> will return an empty iterator until a call
-     * to <code>appendFaultSubcode</code> is made.
+     * {@code SOAPFault}. Subsequent calls to
+     * {@code getFaultSubcodes} will return an empty iterator until a call
+     * to {@code 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
-     * <code>SOAPFault</code>. Subcodes, which were introduced in SOAP 1.2, are
+     * {@code 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.
      *

@@ -192,188 +192,188 @@
      * @since 1.6, SAAJ 1.3
      */
     public void appendFaultSubcode(QName subcode) throws SOAPException;
 
     /**
-     * Gets the fault code for this <code>SOAPFault</code> object.
+     * Gets the fault code for this {@code SOAPFault} object.
      *
-     * @return a <code>String</code> with the fault code
+     * @return a {@code String} with the fault code
      * @see #getFaultCodeAsName
      * @see #setFaultCode
      */
     public String getFaultCode();
 
     /**
-     * Sets this <code>SOAPFault</code> object with the given fault actor.
+     * Sets this {@code SOAPFault} object with the given fault actor.
      * <P>
      * The fault actor is the recipient in the message path who caused the
      * fault to happen.
      * <P>
-     * If this <code>SOAPFault</code> supports SOAP 1.2 then this call is
+     * If this {@code SOAPFault} supports SOAP 1.2 then this call is
      * equivalent to {@link #setFaultRole(String)}
      *
-     * @param faultActor a <code>String</code> identifying the actor that
-     *        caused this <code>SOAPFault</code> object
+     * @param faultActor a {@code String} identifying the actor that
+     *        caused this {@code SOAPFault} object
      * @see #getFaultActor
      *
      * @exception SOAPException if there was an error in adding the
-     *            <code>faultActor</code> to the underlying XML tree.
+     *            {@code faultActor} to the underlying XML tree.
      */
     public void setFaultActor(String faultActor) throws SOAPException;
 
     /**
-     * Gets the fault actor for this <code>SOAPFault</code> object.
+     * Gets the fault actor for this {@code SOAPFault} object.
      * <P>
-     * If this <code>SOAPFault</code> supports SOAP 1.2 then this call is
+     * If this {@code SOAPFault} supports SOAP 1.2 then this call is
      * equivalent to {@link #getFaultRole()}
      *
-     * @return a <code>String</code> giving the actor in the message path
-     *         that caused this <code>SOAPFault</code> object
+     * @return a {@code String} giving the actor in the message path
+     *         that caused this {@code SOAPFault} object
      * @see #setFaultActor
      */
     public String getFaultActor();
 
     /**
-     * Sets the fault string for this <code>SOAPFault</code> object
+     * Sets the fault string for this {@code SOAPFault} object
      * to the given string.
      * <P>
      * If this
-     * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then
+     * {@code SOAPFault} is part of a message that supports SOAP 1.2 then
      * this call is equivalent to:
-     * <pre>
+     * <pre>{@code
      *      addFaultReasonText(faultString, Locale.getDefault());
-     * </pre>
+     * }</pre>
      *
-     * @param faultString a <code>String</code> giving an explanation of
+     * @param faultString a {@code String} giving an explanation of
      *        the fault
      * @see #getFaultString
      *
      * @exception SOAPException if there was an error in adding the
-     *            <code>faultString</code> to the underlying XML tree.
+     *            {@code faultString} to the underlying XML tree.
      */
     public void setFaultString(String faultString) throws SOAPException;
 
     /**
-     * Sets the fault string for this <code>SOAPFault</code> object
+     * Sets the fault string for this {@code SOAPFault} object
      * to the given string and localized to the given locale.
      * <P>
      * If this
-     * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then
+     * {@code SOAPFault} is part of a message that supports SOAP 1.2 then
      * this call is equivalent to:
-     * <pre>
+     * <pre>{@code
      *      addFaultReasonText(faultString, locale);
-     * </pre>
+     * }</pre>
      *
-     * @param faultString a <code>String</code> giving an explanation of
+     * @param faultString a {@code String} giving an explanation of
      *         the fault
      * @param locale a {@link java.util.Locale Locale} object indicating
-     *         the native language of the <code>faultString</code>
+     *         the native language of the {@code faultString}
      * @see #getFaultString
      *
      * @exception SOAPException if there was an error in adding the
-     *            <code>faultString</code> to the underlying XML tree.
+     *            {@code 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 <code>SOAPFault</code> object.
+     * Gets the fault string for this {@code SOAPFault} object.
      * <P>
      * If this
-     * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then
+     * {@code SOAPFault} is part of a message that supports SOAP 1.2 then
      * this call is equivalent to:
-     * <pre>
+     * <pre>{@code
      *    String reason = null;
      *    try {
      *        reason = (String) getFaultReasonTexts().next();
      *    } catch (SOAPException e) {}
      *    return reason;
-     * </pre>
+     * }</pre>
      *
-     * @return a <code>String</code> giving an explanation of
+     * @return a {@code 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 <code>SOAPFault</code>
+     * Gets the locale of the fault string for this {@code SOAPFault}
      * object.
      * <P>
      * If this
-     * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then
+     * {@code SOAPFault} is part of a message that supports SOAP 1.2 then
      * this call is equivalent to:
-     * <pre>
+     * <pre>{@code
      *    Locale locale = null;
      *    try {
      *        locale = (Locale) getFaultReasonLocales().next();
      *    } catch (SOAPException e) {}
      *    return locale;
-     * </pre>
+     * }</pre>
      *
-     * @return a <code>Locale</code> object indicating the native language of
-     *          the fault string or <code>null</code> if no locale was specified
+     * @return a {@code Locale} object indicating the native language of
+     *          the fault string or {@code null} if no locale was specified
      * @see #setFaultString(String, Locale)
      *
      * @since 1.6, SAAJ 1.2
      */
     public Locale getFaultStringLocale();
 
     /**
-     * Returns true if this <code>SOAPFault</code> has a <code>Detail</code>
+     * Returns true if this {@code SOAPFault} has a {@code Detail}
      * subelement and false otherwise. Equivalent to
-     * <code>(getDetail()!=null)</code>.
+     * {@code (getDetail()!=null)}.
      *
-     * @return true if this <code>SOAPFault</code> has a <code>Detail</code>
+     * @return true if this {@code SOAPFault} has a {@code Detail}
      * subelement and false otherwise.
      *
      * @since 1.6, SAAJ 1.3
      */
     public boolean hasDetail();
 
     /**
-     * Returns the optional detail element for this <code>SOAPFault</code>
+     * Returns the optional detail element for this {@code SOAPFault}
      * object.
      * <P>
-     * A <code>Detail</code> object carries application-specific error
+     * A {@code Detail} object carries application-specific error
      * information, the scope of the error information is restricted to
-     * faults in the <code>SOAPBodyElement</code> objects if this is a
+     * faults in the {@code SOAPBodyElement} objects if this is a
      * SOAP 1.1 Fault.
      *
-     * @return a <code>Detail</code> object with application-specific
+     * @return a {@code Detail} object with application-specific
      *         error information if present, null otherwise
      */
     public Detail getDetail();
 
     /**
-     * Creates an optional <code>Detail</code> object and sets it as the
-     * <code>Detail</code> object for this <code>SOAPFault</code>
+     * Creates an optional {@code Detail} object and sets it as the
+     * {@code Detail} object for this {@code SOAPFault}
      * object.
      * <P>
      * 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 <code>Detail</code> object
+     * @return the new {@code Detail} object
      *
      * @exception SOAPException if this
-     *            <code>SOAPFault</code> object already contains a
-     *            valid <code>Detail</code> object
+     *            {@code SOAPFault} object already contains a
+     *            valid {@code Detail} object
      */
     public Detail addDetail() throws SOAPException;
 
     /**
-     * Returns an <code>Iterator</code> over a distinct sequence of
-     * <code>Locale</code>s for which there are associated Reason Text items.
-     * Any of these <code>Locale</code>s can be used in a call to
-     * <code>getFaultReasonText</code> in order to obtain a localized version
+     * Returns an {@code Iterator} over a distinct sequence of
+     * {@code Locale}s for which there are associated Reason Text items.
+     * Any of these {@code Locale}s can be used in a call to
+     * {@code getFaultReasonText} in order to obtain a localized version
      * of the Reason Text string.
      *
-     * @return an <code>Iterator</code> over a sequence of <code>Locale</code>
+     * @return an {@code Iterator} over a sequence of {@code 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

@@ -382,15 +382,15 @@
      * @since 1.6, SAAJ 1.3
      */
     public Iterator getFaultReasonLocales() throws SOAPException;
 
     /**
-     * Returns an <code>Iterator</code> over a sequence of
-     * <code>String</code> objects containing all of the Reason Text items for
-     * this <code>SOAPFault</code>.
+     * Returns an {@code Iterator} over a sequence of
+     * {@code String} objects containing all of the Reason Text items for
+     * this {@code SOAPFault}.
      *
-     * @return an <code>Iterator</code> over env:Fault/env:Reason/env:Text items.
+     * @return an {@code 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.

@@ -398,18 +398,18 @@
      * @since 1.6, SAAJ 1.3
      */
     public Iterator getFaultReasonTexts() throws SOAPException;
 
     /**
-     * Returns the Reason Text associated with the given <code>Locale</code>.
+     * Returns the Reason Text associated with the given {@code Locale}.
      * If more than one such Reason Text exists the first matching Text is
      * returned
      *
-     * @param locale -- the <code>Locale</code> for which a localized
+     * @param locale -- the {@code Locale} for which a localized
      *      Reason Text is desired
      *
-     * @return the Reason Text associated with <code>locale</code>
+     * @return the Reason Text associated with {@code locale}
      *
      * @see #getFaultString
      *
      * @exception SOAPException if there was an error in retrieving
      * the  fault Reason text for the specified locale .

@@ -421,89 +421,89 @@
     public String getFaultReasonText(Locale locale) throws SOAPException;
 
     /**
      * Appends or replaces a Reason Text item containing the specified
      * text message and an <i>xml:lang</i> derived from
-     * <code>locale</code>. If a Reason Text item with this
+     * {@code locale}. If a Reason Text item with this
      * <i>xml:lang</i> already exists its text value will be replaced
-     * with <code>text</code>.
-     * The <code>locale</code> parameter should not be <code>null</code>
+     * with {@code text}.
+     * The {@code locale} parameter should not be {@code null}
      * <P>
      * Code sample:
      *
-     * <PRE>
+     * <pre>{@code
      * SOAPFault fault = ...;
      * fault.addFaultReasonText("Version Mismatch", Locale.ENGLISH);
-     * </PRE>
+     * }</pre>
      *
      * @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 <code>locale</code> passed was <code>null</code>.
+     * or the {@code locale} passed was {@code 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
-     * <code>SOAPFault</code> object. The Node element is
+     * {@code SOAPFault} object. The Node element is
      * optional in SOAP 1.2.
      *
      * @return Content of the env:Fault/env:Node element as a String
-     * or <code>null</code> if none
+     * or {@code 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 <code>SOAPFault</code> object. The Node element
+     * this {@code SOAPFault} object. The Node element
      * is optional in SOAP 1.2.
      *
      * @exception SOAPException  if there was an error in setting the
-     *            Node for this  <code>SOAPFault</code> object.
+     *            Node for this  {@code 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
-     * <code>SOAPFault</code> object. The Role element is
+     * {@code SOAPFault} object. The Role element is
      * optional in SOAP 1.2.
      *
      * @return Content of the env:Fault/env:Role element as a String
-     * or <code>null</code> if none
+     * or {@code 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 <code>SOAPFault</code> object. The Role element
+     * this {@code 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  <code>SOAPFault</code> object.
+     *            Role for this  {@code SOAPFault} object.
      *
      * @exception UnsupportedOperationException if this message does not
      *      support the SOAP 1.2 concept of Fault Role.
      *
      * @since 1.6, SAAJ 1.3
< prev index next >