diff -r 000000000000 -r 373ffda63c9a src/share/jaxws_classes/javax/xml/soap/SOAPFault.java
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/share/jaxws_classes/javax/xml/soap/SOAPFault.java Wed Apr 27 01:27:09 2016 +0800
@@ -0,0 +1,511 @@
+/*
+ * Copyright (c) 2004, 2012, 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
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package javax.xml.soap;
+
+import java.util.Iterator;
+import java.util.Locale;
+
+import javax.xml.namespace.QName;
+
+/**
+ * An element in the 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.
+ */
+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 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 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 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 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 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 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 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 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 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 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
+ * 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
+ * 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 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 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 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 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 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 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 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 SAAJ 1.3
+ */
+ public void setFaultRole(String uri) throws SOAPException;
+
+}