325N/A * Copyright (c) 2004, 2011, Oracle and/or its affiliates. All rights reserved. 325N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 325N/A * This code is free software; you can redistribute it and/or modify it 325N/A * under the terms of the GNU General Public License version 2 only, as 325N/A * published by the Free Software Foundation. Oracle designates this 325N/A * particular file as subject to the "Classpath" exception as provided 325N/A * by Oracle in the LICENSE file that accompanied this code. 325N/A * This code is distributed in the hope that it will be useful, but WITHOUT 325N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 325N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 325N/A * version 2 for more details (a copy is included in the LICENSE file that 325N/A * accompanied this code). 325N/A * You should have received a copy of the GNU General Public License version 325N/A * 2 along with this work; if not, write to the Free Software Foundation, 325N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 325N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 325N/A * or visit www.oracle.com if you need additional information or have any 325N/A * An element in the <code>SOAPBody</code> object that contains 325N/A * error and/or status information. This information may relate to 325N/A * errors in the <code>SOAPMessage</code> object or to problems 325N/A * that are not related to the content in the message itself. Problems 325N/A * not related to the message itself are generally errors in 325N/A * processing, such as the inability to communicate with an upstream 325N/A * Depending on the <code>protocol</code> specified while creating the 325N/A * <code>MessageFactory</code> instance, a <code>SOAPFault</code> has 325N/A * sub-elements as defined in the SOAP 1.1/SOAP 1.2 specification. 325N/A * Sets this <code>SOAPFault</code> object with the given fault code. 325N/A * <P> Fault codes, which give information about the fault, are defined 325N/A * in the SOAP 1.1 specification. A fault code is mandatory and must 325N/A * be of type <code>Name</code>. This method provides a convenient 325N/A * way to set a fault code. For example, 325N/A * SOAPEnvelope se = ...; 325N/A * // Create a qualified name in the SOAP namespace with a localName 325N/A * // of "Client". Note that prefix parameter is optional and is null 325N/A * // here which causes the implementation to use an appropriate prefix. 325N/A * Name qname = se.createName("Client", null, 325N/A * SOAPConstants.URI_NS_SOAP_ENVELOPE); 325N/A * SOAPFault fault = ...; 325N/A * fault.setFaultCode(qname); 325N/A * It is preferable to use this method over {@link #setFaultCode(String)}. 325N/A * @param faultCodeQName a <code>Name</code> object giving the fault 325N/A * code to be set. It must be namespace qualified. 325N/A * @see #getFaultCodeAsName 325N/A * @exception SOAPException if there was an error in adding the 325N/A * <i>faultcode</i> element to the underlying XML tree. 325N/A * Sets this <code>SOAPFault</code> object with the given fault code. 325N/A * It is preferable to use this method over {@link #setFaultCode(Name)}. 325N/A * @param faultCodeQName a <code>QName</code> object giving the fault 325N/A * code to be set. It must be namespace qualified. 325N/A * @see #getFaultCodeAsQName 325N/A * @exception SOAPException if there was an error in adding the 325N/A * <code>faultcode</code> element to the underlying XML tree. 325N/A * @see #setFaultCode(Name) 325N/A * @see #getFaultCodeAsQName() 325N/A * Sets this <code>SOAPFault</code> object with the give fault code. 325N/A * Fault codes, which given information about the fault, are defined in 325N/A * the SOAP 1.1 specification. This element is mandatory in SOAP 1.1. 325N/A * Because the fault code is required to be a QName it is preferable to 325N/A * use the {@link #setFaultCode(Name)} form of this method. 325N/A * @param faultCode a <code>String</code> giving the fault code to be set. 325N/A * It must be of the form "prefix:localName" where the prefix has 325N/A * been defined in a namespace declaration. 325N/A * @see #setFaultCode(Name) 325N/A * @see SOAPElement#addNamespaceDeclaration 325N/A * @exception SOAPException if there was an error in adding the 325N/A * <code>faultCode</code> to the underlying XML tree. 325N/A * Gets the mandatory SOAP 1.1 fault code for this 325N/A * <code>SOAPFault</code> object as a SAAJ <code>Name</code> object. 325N/A * The SOAP 1.1 specification requires the value of the "faultcode" 325N/A * element to be of type QName. This method returns the content of the 325N/A * element as a QName in the form of a SAAJ Name object. This method 325N/A * should be used instead of the <code>getFaultCode</code> method since 325N/A * it allows applications to easily access the namespace name without 325N/A * @return a <code>Name</code> representing the faultcode 325N/A * @see #setFaultCode(Name) 325N/A * Gets the fault code for this 325N/A * <code>SOAPFault</code> object as a <code>QName</code> object. 325N/A * @return a <code>QName</code> representing the faultcode 325N/A * @see #setFaultCode(QName) 325N/A * Gets the Subcodes for this <code>SOAPFault</code> as an iterator over 325N/A * @return an <code>Iterator</code> that accesses a sequence of 325N/A * <code>QNames</code>. This <code>Iterator</code> should not support 325N/A * the optional <code>remove</code> method. The order in which the 325N/A * Subcodes are returned reflects the hierarchy of Subcodes present 325N/A * in the fault from top to bottom. 325N/A * @exception UnsupportedOperationException if this message does not 325N/A * support the SOAP 1.2 concept of Subcode. 325N/A * Removes any Subcodes that may be contained by this 325N/A * <code>SOAPFault</code>. Subsequent calls to 325N/A * <code>getFaultSubcodes</code> will return an empty iterator until a call 325N/A * to <code>appendFaultSubcode</code> is made. 325N/A * @exception UnsupportedOperationException if this message does not 325N/A * support the SOAP 1.2 concept of Subcode. 325N/A * Adds a Subcode to the end of the sequence of Subcodes contained by this 325N/A * <code>SOAPFault</code>. Subcodes, which were introduced in SOAP 1.2, are 325N/A * represented by a recursive sequence of subelements rooted in the 325N/A * mandatory Code subelement of a SOAP Fault. 325N/A * @param subcode a QName containing the Value of the Subcode. 325N/A * @exception SOAPException if there was an error in setting the Subcode 325N/A * @exception UnsupportedOperationException if this message does not 325N/A * support the SOAP 1.2 concept of Subcode. 325N/A * Gets the fault code for this <code>SOAPFault</code> object. 325N/A * @return a <code>String</code> with the fault code 325N/A * @see #getFaultCodeAsName 325N/A * Sets this <code>SOAPFault</code> object with the given fault actor. 325N/A * The fault actor is the recipient in the message path who caused the 325N/A * If this <code>SOAPFault</code> supports SOAP 1.2 then this call is 325N/A * equivalent to {@link #setFaultRole(String)} 325N/A * @param faultActor a <code>String</code> identifying the actor that 325N/A * caused this <code>SOAPFault</code> object 325N/A * @exception SOAPException if there was an error in adding the 325N/A * <code>faultActor</code> to the underlying XML tree. 325N/A * Gets the fault actor for this <code>SOAPFault</code> object. 325N/A * If this <code>SOAPFault</code> supports SOAP 1.2 then this call is 325N/A * equivalent to {@link #getFaultRole()} 325N/A * @return a <code>String</code> giving the actor in the message path 325N/A * that caused this <code>SOAPFault</code> object 325N/A * Sets the fault string for this <code>SOAPFault</code> object 325N/A * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then 325N/A * this call is equivalent to: 325N/A * addFaultReasonText(faultString, Locale.getDefault()); 325N/A * @param faultString a <code>String</code> giving an explanation of 325N/A * @exception SOAPException if there was an error in adding the 325N/A * <code>faultString</code> to the underlying XML tree. 325N/A * Sets the fault string for this <code>SOAPFault</code> object 325N/A * to the given string and localized to the given locale. 325N/A * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then 325N/A * this call is equivalent to: 325N/A * addFaultReasonText(faultString, locale); 325N/A * @param faultString a <code>String</code> giving an explanation of 325N/A * @param locale a {@link java.util.Locale Locale} object indicating 325N/A * the native language of the <code>faultString</code> 325N/A * @exception SOAPException if there was an error in adding the 325N/A * <code>faultString</code> to the underlying XML tree. 325N/A * Gets the fault string for this <code>SOAPFault</code> object. 325N/A * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then 325N/A * this call is equivalent to: 325N/A * String reason = null; 325N/A * reason = (String) getFaultReasonTexts().next(); 325N/A * } catch (SOAPException e) {} 325N/A * @return a <code>String</code> giving an explanation of 325N/A * @see #setFaultString(String) 325N/A * @see #setFaultString(String, Locale) 325N/A * Gets the locale of the fault string for this <code>SOAPFault</code> 325N/A * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then 325N/A * this call is equivalent to: 325N/A * Locale locale = null; 325N/A * locale = (Locale) getFaultReasonLocales().next(); 325N/A * } catch (SOAPException e) {} 325N/A * @return a <code>Locale</code> object indicating the native language of 325N/A * the fault string or <code>null</code> if no locale was specified 325N/A * @see #setFaultString(String, Locale) 325N/A * Returns true if this <code>SOAPFault</code> has a <code>Detail</code> 325N/A * subelement and false otherwise. Equivalent to 325N/A * <code>(getDetail()!=null)</code>. 325N/A * @return true if this <code>SOAPFault</code> has a <code>Detail</code> 325N/A * subelement and false otherwise. 325N/A * Returns the optional detail element for this <code>SOAPFault</code> 325N/A * A <code>Detail</code> object carries application-specific error 325N/A * information, the scope of the error information is restricted to 325N/A * faults in the <code>SOAPBodyElement</code> objects if this is a 325N/A * @return a <code>Detail</code> object with application-specific 325N/A * error information if present, null otherwise 325N/A * Creates an optional <code>Detail</code> object and sets it as the 325N/A * <code>Detail</code> object for this <code>SOAPFault</code> 325N/A * It is illegal to add a detail when the fault already 325N/A * contains a detail. Therefore, this method should be called 325N/A * only after the existing detail has been removed. 325N/A * @return the new <code>Detail</code> object 325N/A * @exception SOAPException if this 325N/A * <code>SOAPFault</code> object already contains a 325N/A * valid <code>Detail</code> object 325N/A * Returns an <code>Iterator</code> over a distinct sequence of 325N/A * <code>Locale</code>s for which there are associated Reason Text items. 325N/A * Any of these <code>Locale</code>s can be used in a call to 325N/A * <code>getFaultReasonText</code> in order to obtain a localized version 325N/A * of the Reason Text string. 325N/A * @return an <code>Iterator</code> over a sequence of <code>Locale</code> 325N/A * objects for which there are associated Reason Text items. 325N/A * @exception SOAPException if there was an error in retrieving 325N/A * the fault Reason locales. 325N/A * @exception UnsupportedOperationException if this message does not 325N/A * support the SOAP 1.2 concept of Fault Reason. 325N/A * Returns an <code>Iterator</code> over a sequence of 325N/A * <code>String</code> objects containing all of the Reason Text items for 325N/A * this <code>SOAPFault</code>. 325N/A * @exception SOAPException if there was an error in retrieving 325N/A * the fault Reason texts. 325N/A * @exception UnsupportedOperationException if this message does not 325N/A * support the SOAP 1.2 concept of Fault Reason. 325N/A * Returns the Reason Text associated with the given <code>Locale</code>. 325N/A * If more than one such Reason Text exists the first matching Text is 325N/A * @param locale -- the <code>Locale</code> for which a localized 325N/A * Reason Text is desired 325N/A * @return the Reason Text associated with <code>locale</code> 325N/A * @exception SOAPException if there was an error in retrieving 325N/A * the fault Reason text for the specified locale . 325N/A * @exception UnsupportedOperationException if this message does not 325N/A * support the SOAP 1.2 concept of Fault Reason. 325N/A * Appends or replaces a Reason Text item containing the specified 325N/A * text message and an <i>xml:lang</i> derived from 325N/A * <code>locale</code>. If a Reason Text item with this 325N/A * <i>xml:lang</i> already exists its text value will be replaced 325N/A * with <code>text</code>. 325N/A * The <code>locale</code> parameter should not be <code>null</code> 325N/A * SOAPFault fault = ...; 325N/A * fault.addFaultReasonText("Version Mismatch", Locale.ENGLISH); 325N/A * @param text -- reason message string 325N/A * @param locale -- Locale object representing the locale of the message 325N/A * @exception SOAPException if there was an error in adding the Reason text 325N/A * or the <code>locale</code> passed was <code>null</code>. 325N/A * @exception UnsupportedOperationException if this message does not 325N/A * support the SOAP 1.2 concept of Fault Reason. 325N/A * Returns the optional Node element value for this 325N/A * <code>SOAPFault</code> object. The Node element is 325N/A * optional in SOAP 1.2. 325N/A * @return Content of the env:Fault/env:Node element as a String 325N/A * or <code>null</code> if none 325N/A * @exception UnsupportedOperationException if this message does not 325N/A * support the SOAP 1.2 concept of Fault Node. 325N/A * Creates or replaces any existing Node element value for 325N/A * this <code>SOAPFault</code> object. The Node element 325N/A * is optional in SOAP 1.2. 325N/A * @exception SOAPException if there was an error in setting the 325N/A * Node for this <code>SOAPFault</code> object. 325N/A * @exception UnsupportedOperationException if this message does not 325N/A * support the SOAP 1.2 concept of Fault Node. 325N/A * Returns the optional Role element value for this 325N/A * <code>SOAPFault</code> object. The Role element is 325N/A * optional in SOAP 1.2. 325N/A * @return Content of the env:Fault/env:Role element as a String 325N/A * or <code>null</code> if none 325N/A * @exception UnsupportedOperationException if this message does not 325N/A * support the SOAP 1.2 concept of Fault Role. 325N/A * Creates or replaces any existing Role element value for 325N/A * this <code>SOAPFault</code> object. The Role element 325N/A * is optional in SOAP 1.2. 325N/A * @param uri - the URI of the Role 325N/A * @exception SOAPException if there was an error in setting the 325N/A * Role for this <code>SOAPFault</code> object. 325N/A * @exception UnsupportedOperationException if this message does not 325N/A * support the SOAP 1.2 concept of Fault Role.