aoqi@0: /* aoqi@0: * Copyright (c) 2004, 2012, Oracle and/or its affiliates. All rights reserved. aoqi@0: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. aoqi@0: * aoqi@0: * This code is free software; you can redistribute it and/or modify it aoqi@0: * under the terms of the GNU General Public License version 2 only, as aoqi@0: * published by the Free Software Foundation. Oracle designates this aoqi@0: * particular file as subject to the "Classpath" exception as provided aoqi@0: * by Oracle in the LICENSE file that accompanied this code. aoqi@0: * aoqi@0: * This code is distributed in the hope that it will be useful, but WITHOUT aoqi@0: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or aoqi@0: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License aoqi@0: * version 2 for more details (a copy is included in the LICENSE file that aoqi@0: * accompanied this code). aoqi@0: * aoqi@0: * You should have received a copy of the GNU General Public License version aoqi@0: * 2 along with this work; if not, write to the Free Software Foundation, aoqi@0: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. aoqi@0: * aoqi@0: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA aoqi@0: * or visit www.oracle.com if you need additional information or have any aoqi@0: * questions. aoqi@0: */ aoqi@0: aoqi@0: package javax.xml.soap; aoqi@0: aoqi@0: import java.util.Iterator; aoqi@0: import java.util.Locale; aoqi@0: aoqi@0: import javax.xml.namespace.QName; aoqi@0: aoqi@0: /** aoqi@0: * An element in the SOAPBody object that contains aoqi@0: * error and/or status information. This information may relate to aoqi@0: * errors in the SOAPMessage object or to problems aoqi@0: * that are not related to the content in the message itself. Problems aoqi@0: * not related to the message itself are generally errors in aoqi@0: * processing, such as the inability to communicate with an upstream aoqi@0: * server. aoqi@0: *

aoqi@0: * Depending on the protocol specified while creating the aoqi@0: * MessageFactory instance, a SOAPFault has aoqi@0: * sub-elements as defined in the SOAP 1.1/SOAP 1.2 specification. aoqi@0: */ aoqi@0: public interface SOAPFault extends SOAPBodyElement { aoqi@0: aoqi@0: /** aoqi@0: * Sets this SOAPFault object with the given fault code. aoqi@0: * aoqi@0: *

Fault codes, which give information about the fault, are defined aoqi@0: * in the SOAP 1.1 specification. A fault code is mandatory and must aoqi@0: * be of type Name. This method provides a convenient aoqi@0: * way to set a fault code. For example, aoqi@0: * aoqi@0: * 

aoqi@0:      * SOAPEnvelope se = ...;
aoqi@0:      * // Create a qualified name in the SOAP namespace with a localName
aoqi@0:      * // of "Client". Note that prefix parameter is optional and is null
aoqi@0:      * // here which causes the implementation to use an appropriate prefix.
aoqi@0:      * Name qname = se.createName("Client", null,
aoqi@0:      *                            SOAPConstants.URI_NS_SOAP_ENVELOPE);
aoqi@0:      * SOAPFault fault = ...;
aoqi@0:      * fault.setFaultCode(qname);
aoqi@0:      *
aoqi@0: * It is preferable to use this method over {@link #setFaultCode(String)}. aoqi@0: * aoqi@0: * @param faultCodeQName a Name object giving the fault aoqi@0: * code to be set. It must be namespace qualified. aoqi@0: * @see #getFaultCodeAsName aoqi@0: * aoqi@0: * @exception SOAPException if there was an error in adding the aoqi@0: * faultcode element to the underlying XML tree. aoqi@0: * aoqi@0: * @since SAAJ 1.2 aoqi@0: */ aoqi@0: public void setFaultCode(Name faultCodeQName) throws SOAPException; aoqi@0: aoqi@0: /** aoqi@0: * Sets this SOAPFault object with the given fault code. aoqi@0: * aoqi@0: * It is preferable to use this method over {@link #setFaultCode(Name)}. aoqi@0: * aoqi@0: * @param faultCodeQName a QName object giving the fault aoqi@0: * code to be set. It must be namespace qualified. aoqi@0: * @see #getFaultCodeAsQName aoqi@0: * aoqi@0: * @exception SOAPException if there was an error in adding the aoqi@0: * faultcode element to the underlying XML tree. aoqi@0: * aoqi@0: * @see #setFaultCode(Name) aoqi@0: * @see #getFaultCodeAsQName() aoqi@0: * aoqi@0: * @since SAAJ 1.3 aoqi@0: */ aoqi@0: public void setFaultCode(QName faultCodeQName) throws SOAPException; aoqi@0: aoqi@0: /** aoqi@0: * Sets this SOAPFault object with the give fault code. aoqi@0: *

aoqi@0: * Fault codes, which given information about the fault, are defined in aoqi@0: * the SOAP 1.1 specification. This element is mandatory in SOAP 1.1. aoqi@0: * Because the fault code is required to be a QName it is preferable to aoqi@0: * use the {@link #setFaultCode(Name)} form of this method. aoqi@0: * aoqi@0: * @param faultCode a String giving the fault code to be set. aoqi@0: * It must be of the form "prefix:localName" where the prefix has aoqi@0: * been defined in a namespace declaration. aoqi@0: * @see #setFaultCode(Name) aoqi@0: * @see #getFaultCode aoqi@0: * @see SOAPElement#addNamespaceDeclaration aoqi@0: * aoqi@0: * @exception SOAPException if there was an error in adding the aoqi@0: * faultCode to the underlying XML tree. aoqi@0: */ aoqi@0: public void setFaultCode(String faultCode) throws SOAPException; aoqi@0: aoqi@0: /** aoqi@0: * Gets the mandatory SOAP 1.1 fault code for this aoqi@0: * SOAPFault object as a SAAJ Name object. aoqi@0: * The SOAP 1.1 specification requires the value of the "faultcode" aoqi@0: * element to be of type QName. This method returns the content of the aoqi@0: * element as a QName in the form of a SAAJ Name object. This method aoqi@0: * should be used instead of the getFaultCode method since aoqi@0: * it allows applications to easily access the namespace name without aoqi@0: * additional parsing. aoqi@0: * aoqi@0: * @return a Name representing the faultcode aoqi@0: * @see #setFaultCode(Name) aoqi@0: * aoqi@0: * @since SAAJ 1.2 aoqi@0: */ aoqi@0: public Name getFaultCodeAsName(); aoqi@0: aoqi@0: aoqi@0: /** aoqi@0: * Gets the fault code for this aoqi@0: * SOAPFault object as a QName object. aoqi@0: * aoqi@0: * @return a QName representing the faultcode aoqi@0: * aoqi@0: * @see #setFaultCode(QName) aoqi@0: * aoqi@0: * @since SAAJ 1.3 aoqi@0: */ aoqi@0: public QName getFaultCodeAsQName(); aoqi@0: aoqi@0: /** aoqi@0: * Gets the Subcodes for this SOAPFault as an iterator over aoqi@0: * QNames. aoqi@0: * aoqi@0: * @return an Iterator that accesses a sequence of aoqi@0: * QNames. This Iterator should not support aoqi@0: * the optional remove method. The order in which the aoqi@0: * Subcodes are returned reflects the hierarchy of Subcodes present aoqi@0: * in the fault from top to bottom. aoqi@0: * aoqi@0: * @exception UnsupportedOperationException if this message does not aoqi@0: * support the SOAP 1.2 concept of Subcode. aoqi@0: * aoqi@0: * @since SAAJ 1.3 aoqi@0: */ aoqi@0: public Iterator getFaultSubcodes(); aoqi@0: aoqi@0: /** aoqi@0: * Removes any Subcodes that may be contained by this aoqi@0: * SOAPFault. Subsequent calls to aoqi@0: * getFaultSubcodes will return an empty iterator until a call aoqi@0: * to appendFaultSubcode is made. aoqi@0: * aoqi@0: * @exception UnsupportedOperationException if this message does not aoqi@0: * support the SOAP 1.2 concept of Subcode. aoqi@0: * aoqi@0: * @since SAAJ 1.3 aoqi@0: */ aoqi@0: public void removeAllFaultSubcodes(); aoqi@0: aoqi@0: /** aoqi@0: * Adds a Subcode to the end of the sequence of Subcodes contained by this aoqi@0: * SOAPFault. Subcodes, which were introduced in SOAP 1.2, are aoqi@0: * represented by a recursive sequence of subelements rooted in the aoqi@0: * mandatory Code subelement of a SOAP Fault. aoqi@0: * aoqi@0: * @param subcode a QName containing the Value of the Subcode. aoqi@0: * aoqi@0: * @exception SOAPException if there was an error in setting the Subcode aoqi@0: * @exception UnsupportedOperationException if this message does not aoqi@0: * support the SOAP 1.2 concept of Subcode. aoqi@0: * aoqi@0: * @since SAAJ 1.3 aoqi@0: */ aoqi@0: public void appendFaultSubcode(QName subcode) throws SOAPException; aoqi@0: aoqi@0: /** aoqi@0: * Gets the fault code for this SOAPFault object. aoqi@0: * aoqi@0: * @return a String with the fault code aoqi@0: * @see #getFaultCodeAsName aoqi@0: * @see #setFaultCode aoqi@0: */ aoqi@0: public String getFaultCode(); aoqi@0: aoqi@0: /** aoqi@0: * Sets this SOAPFault object with the given fault actor. aoqi@0: *

aoqi@0: * The fault actor is the recipient in the message path who caused the aoqi@0: * fault to happen. aoqi@0: *

aoqi@0: * If this SOAPFault supports SOAP 1.2 then this call is aoqi@0: * equivalent to {@link #setFaultRole(String)} aoqi@0: * aoqi@0: * @param faultActor a String identifying the actor that aoqi@0: * caused this SOAPFault object aoqi@0: * @see #getFaultActor aoqi@0: * aoqi@0: * @exception SOAPException if there was an error in adding the aoqi@0: * faultActor to the underlying XML tree. aoqi@0: */ aoqi@0: public void setFaultActor(String faultActor) throws SOAPException; aoqi@0: aoqi@0: /** aoqi@0: * Gets the fault actor for this SOAPFault object. aoqi@0: *

aoqi@0: * If this SOAPFault supports SOAP 1.2 then this call is aoqi@0: * equivalent to {@link #getFaultRole()} aoqi@0: * aoqi@0: * @return a String giving the actor in the message path aoqi@0: * that caused this SOAPFault object aoqi@0: * @see #setFaultActor aoqi@0: */ aoqi@0: public String getFaultActor(); aoqi@0: aoqi@0: /** aoqi@0: * Sets the fault string for this SOAPFault object aoqi@0: * to the given string. aoqi@0: *

aoqi@0: * If this aoqi@0: * SOAPFault is part of a message that supports SOAP 1.2 then aoqi@0: * this call is equivalent to: aoqi@0: * 

aoqi@0:      *      addFaultReasonText(faultString, Locale.getDefault());
aoqi@0:      *
aoqi@0: * aoqi@0: * @param faultString a String giving an explanation of aoqi@0: * the fault aoqi@0: * @see #getFaultString aoqi@0: * aoqi@0: * @exception SOAPException if there was an error in adding the aoqi@0: * faultString to the underlying XML tree. aoqi@0: */ aoqi@0: public void setFaultString(String faultString) throws SOAPException; aoqi@0: aoqi@0: /** aoqi@0: * Sets the fault string for this SOAPFault object aoqi@0: * to the given string and localized to the given locale. aoqi@0: *

aoqi@0: * If this aoqi@0: * SOAPFault is part of a message that supports SOAP 1.2 then aoqi@0: * this call is equivalent to: aoqi@0: * 

aoqi@0:      *      addFaultReasonText(faultString, locale);
aoqi@0:      *
aoqi@0: * aoqi@0: * @param faultString a String giving an explanation of aoqi@0: * the fault aoqi@0: * @param locale a {@link java.util.Locale Locale} object indicating aoqi@0: * the native language of the faultString aoqi@0: * @see #getFaultString aoqi@0: * aoqi@0: * @exception SOAPException if there was an error in adding the aoqi@0: * faultString to the underlying XML tree. aoqi@0: * aoqi@0: * @since SAAJ 1.2 aoqi@0: */ aoqi@0: public void setFaultString(String faultString, Locale locale) aoqi@0: throws SOAPException; aoqi@0: aoqi@0: /** aoqi@0: * Gets the fault string for this SOAPFault object. aoqi@0: *

aoqi@0: * If this aoqi@0: * SOAPFault is part of a message that supports SOAP 1.2 then aoqi@0: * this call is equivalent to: aoqi@0: * 

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

aoqi@0: * If this aoqi@0: * SOAPFault is part of a message that supports SOAP 1.2 then aoqi@0: * this call is equivalent to: aoqi@0: * 

aoqi@0:      *    Locale locale = null;
aoqi@0:      *    try {
aoqi@0:      *        locale = (Locale) getFaultReasonLocales().next();
aoqi@0:      *    } catch (SOAPException e) {}
aoqi@0:      *    return locale;
aoqi@0:      *
aoqi@0: * aoqi@0: * @return a Locale object indicating the native language of aoqi@0: * the fault string or null if no locale was specified aoqi@0: * @see #setFaultString(String, Locale) aoqi@0: * aoqi@0: * @since SAAJ 1.2 aoqi@0: */ aoqi@0: public Locale getFaultStringLocale(); aoqi@0: aoqi@0: /** aoqi@0: * Returns true if this SOAPFault has a Detail aoqi@0: * subelement and false otherwise. Equivalent to aoqi@0: * (getDetail()!=null). aoqi@0: * aoqi@0: * @return true if this SOAPFault has a Detail aoqi@0: * subelement and false otherwise. aoqi@0: * aoqi@0: * @since SAAJ 1.3 aoqi@0: */ aoqi@0: public boolean hasDetail(); aoqi@0: aoqi@0: /** aoqi@0: * Returns the optional detail element for this SOAPFault aoqi@0: * object. aoqi@0: *

aoqi@0: * A Detail object carries application-specific error aoqi@0: * information, the scope of the error information is restricted to aoqi@0: * faults in the SOAPBodyElement objects if this is a aoqi@0: * SOAP 1.1 Fault. aoqi@0: * aoqi@0: * @return a Detail object with application-specific aoqi@0: * error information if present, null otherwise aoqi@0: */ aoqi@0: public Detail getDetail(); aoqi@0: aoqi@0: /** aoqi@0: * Creates an optional Detail object and sets it as the aoqi@0: * Detail object for this SOAPFault aoqi@0: * object. aoqi@0: *

aoqi@0: * It is illegal to add a detail when the fault already aoqi@0: * contains a detail. Therefore, this method should be called aoqi@0: * only after the existing detail has been removed. aoqi@0: * aoqi@0: * @return the new Detail object aoqi@0: * aoqi@0: * @exception SOAPException if this aoqi@0: * SOAPFault object already contains a aoqi@0: * valid Detail object aoqi@0: */ aoqi@0: public Detail addDetail() throws SOAPException; aoqi@0: aoqi@0: /** aoqi@0: * Returns an Iterator over a distinct sequence of aoqi@0: * Locales for which there are associated Reason Text items. aoqi@0: * Any of these Locales can be used in a call to aoqi@0: * getFaultReasonText in order to obtain a localized version aoqi@0: * of the Reason Text string. aoqi@0: * aoqi@0: * @return an Iterator over a sequence of Locale aoqi@0: * objects for which there are associated Reason Text items. aoqi@0: * aoqi@0: * @exception SOAPException if there was an error in retrieving aoqi@0: * the fault Reason locales. aoqi@0: * @exception UnsupportedOperationException if this message does not aoqi@0: * support the SOAP 1.2 concept of Fault Reason. aoqi@0: * aoqi@0: * @since SAAJ 1.3 aoqi@0: */ aoqi@0: public Iterator getFaultReasonLocales() throws SOAPException; aoqi@0: aoqi@0: /** aoqi@0: * Returns an Iterator over a sequence of aoqi@0: * String objects containing all of the Reason Text items for aoqi@0: * this SOAPFault. aoqi@0: * aoqi@0: * @return an Iterator over env:Fault/env:Reason/env:Text items. aoqi@0: * aoqi@0: * @exception SOAPException if there was an error in retrieving aoqi@0: * the fault Reason texts. aoqi@0: * @exception UnsupportedOperationException if this message does not aoqi@0: * support the SOAP 1.2 concept of Fault Reason. aoqi@0: * aoqi@0: * @since SAAJ 1.3 aoqi@0: */ aoqi@0: public Iterator getFaultReasonTexts() throws SOAPException; aoqi@0: aoqi@0: /** aoqi@0: * Returns the Reason Text associated with the given Locale. aoqi@0: * If more than one such Reason Text exists the first matching Text is aoqi@0: * returned aoqi@0: * aoqi@0: * @param locale -- the Locale for which a localized aoqi@0: * Reason Text is desired aoqi@0: * aoqi@0: * @return the Reason Text associated with locale aoqi@0: * aoqi@0: * @see #getFaultString aoqi@0: * aoqi@0: * @exception SOAPException if there was an error in retrieving aoqi@0: * the fault Reason text for the specified locale . aoqi@0: * @exception UnsupportedOperationException if this message does not aoqi@0: * support the SOAP 1.2 concept of Fault Reason. aoqi@0: * aoqi@0: * @since SAAJ 1.3 aoqi@0: */ aoqi@0: public String getFaultReasonText(Locale locale) throws SOAPException; aoqi@0: aoqi@0: /** aoqi@0: * Appends or replaces a Reason Text item containing the specified aoqi@0: * text message and an xml:lang derived from aoqi@0: * locale. If a Reason Text item with this aoqi@0: * xml:lang already exists its text value will be replaced aoqi@0: * with text. aoqi@0: * The locale parameter should not be null aoqi@0: *

aoqi@0: * Code sample: aoqi@0: * aoqi@0: * 

aoqi@0:      * SOAPFault fault = ...;
aoqi@0:      * fault.addFaultReasonText("Version Mismatch", Locale.ENGLISH);
aoqi@0:      *
aoqi@0: * aoqi@0: * @param text -- reason message string aoqi@0: * @param locale -- Locale object representing the locale of the message aoqi@0: * aoqi@0: * @exception SOAPException if there was an error in adding the Reason text aoqi@0: * or the locale passed was null. aoqi@0: * @exception UnsupportedOperationException if this message does not aoqi@0: * support the SOAP 1.2 concept of Fault Reason. aoqi@0: * aoqi@0: * @since SAAJ 1.3 aoqi@0: */ aoqi@0: public void addFaultReasonText(String text, java.util.Locale locale) aoqi@0: throws SOAPException; aoqi@0: aoqi@0: /** aoqi@0: * Returns the optional Node element value for this aoqi@0: * SOAPFault object. The Node element is aoqi@0: * optional in SOAP 1.2. aoqi@0: * aoqi@0: * @return Content of the env:Fault/env:Node element as a String aoqi@0: * or null if none aoqi@0: * aoqi@0: * @exception UnsupportedOperationException if this message does not aoqi@0: * support the SOAP 1.2 concept of Fault Node. aoqi@0: * aoqi@0: * @since SAAJ 1.3 aoqi@0: */ aoqi@0: public String getFaultNode(); aoqi@0: aoqi@0: /** aoqi@0: * Creates or replaces any existing Node element value for aoqi@0: * this SOAPFault object. The Node element aoqi@0: * is optional in SOAP 1.2. aoqi@0: * aoqi@0: * @exception SOAPException if there was an error in setting the aoqi@0: * Node for this SOAPFault object. aoqi@0: * @exception UnsupportedOperationException if this message does not aoqi@0: * support the SOAP 1.2 concept of Fault Node. aoqi@0: * aoqi@0: * aoqi@0: * @since SAAJ 1.3 aoqi@0: */ aoqi@0: public void setFaultNode(String uri) throws SOAPException; aoqi@0: aoqi@0: /** aoqi@0: * Returns the optional Role element value for this aoqi@0: * SOAPFault object. The Role element is aoqi@0: * optional in SOAP 1.2. aoqi@0: * aoqi@0: * @return Content of the env:Fault/env:Role element as a String aoqi@0: * or null if none aoqi@0: * aoqi@0: * @exception UnsupportedOperationException if this message does not aoqi@0: * support the SOAP 1.2 concept of Fault Role. aoqi@0: * aoqi@0: * @since SAAJ 1.3 aoqi@0: */ aoqi@0: public String getFaultRole(); aoqi@0: aoqi@0: /** aoqi@0: * Creates or replaces any existing Role element value for aoqi@0: * this SOAPFault object. The Role element aoqi@0: * is optional in SOAP 1.2. aoqi@0: * aoqi@0: * @param uri - the URI of the Role aoqi@0: * aoqi@0: * @exception SOAPException if there was an error in setting the aoqi@0: * Role for this SOAPFault object. aoqi@0: * aoqi@0: * @exception UnsupportedOperationException if this message does not aoqi@0: * support the SOAP 1.2 concept of Fault Role. aoqi@0: * aoqi@0: * @since SAAJ 1.3 aoqi@0: */ aoqi@0: public void setFaultRole(String uri) throws SOAPException; aoqi@0: aoqi@0: }