--- old/src/java.xml.ws/share/classes/javax/xml/soap/SOAPFault.java 2015-07-08 13:25:14.000000000 +0200 +++ new/src/java.xml.ws/share/classes/javax/xml/soap/SOAPFault.java 2015-07-08 13:25:14.000000000 +0200 @@ -1,5 +1,5 @@ /* - * 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 @@ -31,16 +31,16 @@ import javax.xml.namespace.QName; /** - * An element in the SOAPBody 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 SOAPMessage 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. *

- * Depending on the protocol specified while creating the - * MessageFactory instance, a SOAPFault 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 @@ -48,14 +48,14 @@ public interface SOAPFault extends SOAPBodyElement { /** - * Sets this SOAPFault object with the given fault code. + * Sets this {@code 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 + * be of type {@code Name}. This method provides a convenient * way to set a fault code. For example, * - *

+     * {@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
@@ -64,10 +64,10 @@
      *                            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 + * @param faultCodeQName a {@code Name} object giving the fault * code to be set. It must be namespace qualified. * @see #getFaultCodeAsName * @@ -79,16 +79,16 @@ public void setFaultCode(Name faultCodeQName) throws SOAPException; /** - * Sets this SOAPFault 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 QName 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 - * faultcode element to the underlying XML tree. + * {@code faultcode} element to the underlying XML tree. * * @see #setFaultCode(Name) * @see #getFaultCodeAsQName() @@ -98,14 +98,14 @@ public void setFaultCode(QName faultCodeQName) throws SOAPException; /** - * Sets this SOAPFault object with the give fault code. + * Sets this {@code 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. + * @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) @@ -113,21 +113,21 @@ * @see SOAPElement#addNamespaceDeclaration * * @exception SOAPException if there was an error in adding the - * faultCode 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 - * SOAPFault object as a SAAJ Name 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 getFaultCode 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 Name representing the faultcode + * @return a {@code Name} representing the faultcode * @see #setFaultCode(Name) * * @since 1.6, SAAJ 1.2 @@ -137,9 +137,9 @@ /** * Gets the fault code for this - * SOAPFault object as a QName object. + * {@code SOAPFault} object as a {@code QName} object. * - * @return a QName representing the faultcode + * @return a {@code QName} representing the faultcode * * @see #setFaultCode(QName) * @@ -148,12 +148,12 @@ public QName getFaultCodeAsQName(); /** - * Gets the Subcodes for this SOAPFault as an iterator over - * QNames. + * Gets the Subcodes for this {@code SOAPFault} as an iterator over + * {@code QNames}. * - * @return an Iterator that accesses a sequence of - * QNames. This Iterator should not support - * the optional remove 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. * @@ -166,9 +166,9 @@ /** * 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. + * {@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. @@ -179,7 +179,7 @@ /** * Adds a Subcode to the end of the sequence of Subcodes contained by this - * SOAPFault. 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. * @@ -194,83 +194,83 @@ public void appendFaultSubcode(QName subcode) throws SOAPException; /** - * Gets the fault code for this SOAPFault object. + * Gets the fault code for this {@code SOAPFault} object. * - * @return a String with the fault code + * @return a {@code String} with the fault code * @see #getFaultCodeAsName * @see #setFaultCode */ public String getFaultCode(); /** - * Sets this SOAPFault object with the given fault actor. + * Sets this {@code 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 + * If this {@code 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 + * @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 - * faultActor 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 SOAPFault object. + * Gets the fault actor for this {@code SOAPFault} object. *

- * If this SOAPFault 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 String giving the actor in the message path - * that caused this SOAPFault 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 SOAPFault object + * Sets the fault string for this {@code SOAPFault} object * to the given string. *

* If this - * SOAPFault 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: - *

+     * {@code
      *      addFaultReasonText(faultString, Locale.getDefault());
-     * 
+ * } * - * @param faultString a String 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 - * faultString 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 SOAPFault object + * Sets the fault string for this {@code 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 + * {@code SOAPFault} is part of a message that supports SOAP 1.2 then * this call is equivalent to: - *

+     * {@code
      *      addFaultReasonText(faultString, locale);
-     * 
+ * } * - * @param faultString a String 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 faultString + * the native language of the {@code faultString} * @see #getFaultString * * @exception SOAPException if there was an error in adding the - * faultString to the underlying XML tree. + * {@code faultString} to the underlying XML tree. * * @since 1.6, SAAJ 1.2 */ @@ -278,20 +278,20 @@ throws SOAPException; /** - * Gets the fault string for this SOAPFault object. + * Gets the fault string for this {@code SOAPFault} object. *

* If this - * SOAPFault 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: - *

+     * {@code
      *    String reason = null;
      *    try {
      *        reason = (String) getFaultReasonTexts().next();
      *    } catch (SOAPException e) {}
      *    return reason;
-     * 
+ * } * - * @return a String giving an explanation of + * @return a {@code String} giving an explanation of * the fault * @see #setFaultString(String) * @see #setFaultString(String, Locale) @@ -299,22 +299,22 @@ public String getFaultString(); /** - * Gets the locale of the fault string for this SOAPFault + * Gets the locale of the fault string for this {@code SOAPFault} * object. *

* If this - * SOAPFault 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: - *

+     * {@code
      *    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 + * @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 @@ -322,11 +322,11 @@ public Locale getFaultStringLocale(); /** - * Returns true if this SOAPFault has a Detail + * Returns true if this {@code SOAPFault} has a {@code Detail} * subelement and false otherwise. Equivalent to - * (getDetail()!=null). + * {@code (getDetail()!=null)}. * - * @return true if this SOAPFault has a Detail + * @return true if this {@code SOAPFault} has a {@code Detail} * subelement and false otherwise. * * @since 1.6, SAAJ 1.3 @@ -334,44 +334,44 @@ public boolean hasDetail(); /** - * Returns the optional detail element for this SOAPFault + * Returns the optional detail element for this {@code SOAPFault} * object. *

- * A Detail 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 SOAPBodyElement objects if this is a + * faults in the {@code SOAPBodyElement} objects if this is a * SOAP 1.1 Fault. * - * @return a Detail object with application-specific + * @return a {@code 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 + * Creates an optional {@code Detail} object and sets it as the + * {@code Detail} object for this {@code 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 + * @return the new {@code Detail} object * * @exception SOAPException if this - * SOAPFault object already contains a - * valid Detail object + * {@code SOAPFault} object already contains a + * valid {@code 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 + * 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 Iterator over a sequence of Locale + * @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 @@ -384,11 +384,11 @@ public Iterator getFaultReasonLocales() throws SOAPException; /** - * Returns an Iterator over a sequence of - * String objects containing all of the Reason Text items for - * this SOAPFault. + * Returns an {@code Iterator} over a sequence of + * {@code String} objects containing all of the Reason Text items for + * this {@code SOAPFault}. * - * @return an Iterator 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. @@ -400,14 +400,14 @@ public Iterator getFaultReasonTexts() throws SOAPException; /** - * Returns the Reason Text associated with the given Locale. + * 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 Locale for which a localized + * @param locale -- the {@code Locale} for which a localized * Reason Text is desired * - * @return the Reason Text associated with locale + * @return the Reason Text associated with {@code locale} * * @see #getFaultString * @@ -423,23 +423,23 @@ /** * 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 + * {@code 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 + * with {@code text}. + * The {@code locale} parameter should not be {@code null} *

* Code sample: * - *

+     * {@code
      * 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. + * or the {@code locale} passed was {@code null}. * @exception UnsupportedOperationException if this message does not * support the SOAP 1.2 concept of Fault Reason. * @@ -450,11 +450,11 @@ /** * Returns the optional Node element value for this - * SOAPFault 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 null if none + * or {@code null} if none * * @exception UnsupportedOperationException if this message does not * support the SOAP 1.2 concept of Fault Node. @@ -465,11 +465,11 @@ /** * Creates or replaces any existing Node element value for - * this SOAPFault 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 SOAPFault object. + * Node for this {@code SOAPFault} object. * @exception UnsupportedOperationException if this message does not * support the SOAP 1.2 concept of Fault Node. * @@ -480,11 +480,11 @@ /** * Returns the optional Role element value for this - * SOAPFault 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 null if none + * or {@code null} if none * * @exception UnsupportedOperationException if this message does not * support the SOAP 1.2 concept of Fault Role. @@ -495,13 +495,13 @@ /** * Creates or replaces any existing Role element value for - * this SOAPFault 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 SOAPFault object. + * Role for this {@code SOAPFault} object. * * @exception UnsupportedOperationException if this message does not * support the SOAP 1.2 concept of Fault Role.