javax.xml.soap.SOAPFault Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2004-2012 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* http://glassfish.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
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
* 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
* 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;
}