--- 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
- * Locale
s for which there are associated Reason Text items.
- * Any of these Locale
s 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.