- All Superinterfaces:
Element
,Node
,Node
,SOAPBodyElement
,SOAPElement
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.
- Since:
- 1.6
-
Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
-
Method Summary
Modifier and TypeMethodDescriptionCreates an optionalDetail
object and sets it as theDetail
object for thisSOAPFault
object.void
addFaultReasonText
(String text, Locale locale) Appends or replaces a Reason Text item containing the specified text message and an xml:lang derived fromlocale
.void
appendFaultSubcode
(QName subcode) Adds a Subcode to the end of the sequence of Subcodes contained by thisSOAPFault
.Returns the optional detail element for thisSOAPFault
object.Gets the fault actor for thisSOAPFault
object.Gets the fault code for thisSOAPFault
object.Gets the mandatory SOAP 1.1 fault code for thisSOAPFault
object as a SAAJName
object.Gets the fault code for thisSOAPFault
object as aQName
object.Returns the optional Node element value for thisSOAPFault
object.Returns anIterator
over a distinct sequence ofLocale
s for which there are associated Reason Text items.getFaultReasonText
(Locale locale) Returns the Reason Text associated with the givenLocale
.Returns anIterator
over a sequence ofString
objects containing all the Reason Text items for thisSOAPFault
.Returns the optional Role element value for thisSOAPFault
object.Gets the fault string for thisSOAPFault
object.Gets the locale of the fault string for thisSOAPFault
object.Gets the Subcodes for thisSOAPFault
as an iterator overQNames
.boolean
Returns true if thisSOAPFault
has aDetail
subelement and false otherwise.void
Removes any Subcodes that may be contained by thisSOAPFault
.void
setFaultActor
(String faultActor) Sets thisSOAPFault
object with the given fault actor.void
setFaultCode
(Name faultCodeQName) Sets thisSOAPFault
object with the given fault code.void
setFaultCode
(String faultCode) Sets thisSOAPFault
object with the give fault code.void
setFaultCode
(QName faultCodeQName) Sets thisSOAPFault
object with the given fault code.void
setFaultNode
(String uri) Creates or replaces any existing Node element value for thisSOAPFault
object.void
setFaultRole
(String uri) Creates or replaces any existing Role element value for thisSOAPFault
object.void
setFaultString
(String faultString) Sets the fault string for thisSOAPFault
object to the given string.void
setFaultString
(String faultString, Locale locale) Sets the fault string for thisSOAPFault
object to the given string and localized to the given locale.Methods inherited from interface org.w3c.dom.Element
getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getElementsByTagName, getElementsByTagNameNS, getSchemaTypeInfo, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS, setIdAttribute, setIdAttributeNode, setIdAttributeNS
Methods inherited from interface jakarta.xml.soap.Node
detachNode, getParentElement, getValue, recycleNode, setParentElement, setValue
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData
Methods inherited from interface jakarta.xml.soap.SOAPElement
addAttribute, addAttribute, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addNamespaceDeclaration, addTextNode, createQName, getAllAttributes, getAllAttributesAsQNames, getAttributeValue, getAttributeValue, getChildElements, getChildElements, getChildElements, getElementName, getElementQName, getEncodingStyle, getNamespacePrefixes, getNamespaceURI, getVisibleNamespacePrefixes, removeAttribute, removeAttribute, removeContents, removeNamespaceDeclaration, setElementQName, setEncodingStyle
-
Method Details
-
setFaultCode
Sets thisSOAPFault
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);
setFaultCode(String)
.- Parameters:
faultCodeQName
- aName
object giving the fault code to be set. It must be namespace qualified.- Throws:
SOAPException
- if there was an error in adding the faultcode element to the underlying XML tree.- Since:
- 1.6, SAAJ 1.2
- See Also:
-
setFaultCode
Sets thisSOAPFault
object with the given fault code.It is preferable to use this method over
setFaultCode(Name)
.- Parameters:
faultCodeQName
- aQName
object giving the fault code to be set. It must be namespace qualified.- Throws:
SOAPException
- if there was an error in adding thefaultcode
element to the underlying XML tree.- Since:
- 1.6, SAAJ 1.3
- See Also:
-
setFaultCode
Sets thisSOAPFault
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
setFaultCode(Name)
form of this method.- Parameters:
faultCode
- aString
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.- Throws:
SOAPException
- if there was an error in adding thefaultCode
to the underlying XML tree.- See Also:
-
getFaultCodeAsName
Name getFaultCodeAsName()Gets the mandatory SOAP 1.1 fault code for thisSOAPFault
object as a SAAJName
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 thegetFaultCode
method since it allows applications to easily access the namespace name without additional parsing.- Returns:
- a
Name
representing the faultcode - Since:
- 1.6, SAAJ 1.2
- See Also:
-
getFaultCodeAsQName
QName getFaultCodeAsQName()Gets the fault code for thisSOAPFault
object as aQName
object.- Returns:
- a
QName
representing the faultcode - Since:
- 1.6, SAAJ 1.3
- See Also:
-
getFaultSubcodes
Gets the Subcodes for thisSOAPFault
as an iterator overQNames
.- Returns:
- an
Iterator
that accesses a sequence ofQNames
. ThisIterator
should not support the optionalremove
method. The order in which the Subcodes are returned reflects the hierarchy of Subcodes present in the fault from top to bottom. - Throws:
UnsupportedOperationException
- if this message does not support the SOAP 1.2 concept of Subcode.- Since:
- 1.6, SAAJ 1.3
-
removeAllFaultSubcodes
void removeAllFaultSubcodes()Removes any Subcodes that may be contained by thisSOAPFault
. Subsequent calls togetFaultSubcodes
will return an empty iterator until a call toappendFaultSubcode
is made.- Throws:
UnsupportedOperationException
- if this message does not support the SOAP 1.2 concept of Subcode.- Since:
- 1.6, SAAJ 1.3
-
appendFaultSubcode
Adds a Subcode to the end of the sequence of Subcodes contained by thisSOAPFault
. 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.- Parameters:
subcode
- a QName containing the Value of the Subcode.- Throws:
SOAPException
- if there was an error in setting the SubcodeUnsupportedOperationException
- if this message does not support the SOAP 1.2 concept of Subcode.- Since:
- 1.6, SAAJ 1.3
-
getFaultCode
String getFaultCode()Gets the fault code for thisSOAPFault
object.- Returns:
- a
String
with the fault code - See Also:
-
setFaultActor
Sets thisSOAPFault
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 tosetFaultRole(String)
- Parameters:
faultActor
- aString
identifying the actor that caused thisSOAPFault
object- Throws:
SOAPException
- if there was an error in adding thefaultActor
to the underlying XML tree.- See Also:
-
getFaultActor
String getFaultActor()Gets the fault actor for thisSOAPFault
object.If this
SOAPFault
supports SOAP 1.2 then this call is equivalent togetFaultRole()
- Returns:
- a
String
giving the actor in the message path that caused thisSOAPFault
object - See Also:
-
setFaultString
Sets the fault string for thisSOAPFault
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());
- Parameters:
faultString
- aString
giving an explanation of the fault- Throws:
SOAPException
- if there was an error in adding thefaultString
to the underlying XML tree.- See Also:
-
setFaultString
Sets the fault string for thisSOAPFault
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);
- Parameters:
faultString
- aString
giving an explanation of the faultlocale
- aLocale
object indicating the native language of thefaultString
- Throws:
SOAPException
- if there was an error in adding thefaultString
to the underlying XML tree.- Since:
- 1.6, SAAJ 1.2
- See Also:
-
getFaultString
String getFaultString()Gets the fault string for thisSOAPFault
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;
- Returns:
- a
String
giving an explanation of the fault - See Also:
-
getFaultStringLocale
Locale getFaultStringLocale()Gets the locale of the fault string for thisSOAPFault
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;
- Returns:
- a
Locale
object indicating the native language of the fault string ornull
if no locale was specified - Since:
- 1.6, SAAJ 1.2
- See Also:
-
hasDetail
boolean hasDetail()Returns true if thisSOAPFault
has aDetail
subelement and false otherwise. Equivalent to(getDetail()!=null)
.- Returns:
- true if this
SOAPFault
has aDetail
subelement and false otherwise. - Since:
- 1.6, SAAJ 1.3
-
getDetail
Detail getDetail()Returns the optional detail element for thisSOAPFault
object.A
Detail
object carries application-specific error information, the scope of the error information is restricted to faults in theSOAPBodyElement
objects if this is a SOAP 1.1 Fault.- Returns:
- a
Detail
object with application-specific error information if present, null otherwise
-
addDetail
Creates an optionalDetail
object and sets it as theDetail
object for thisSOAPFault
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.
- Returns:
- the new
Detail
object - Throws:
SOAPException
- if thisSOAPFault
object already contains a validDetail
object
-
getFaultReasonLocales
Returns anIterator
over a distinct sequence ofLocale
s for which there are associated Reason Text items. Any of theseLocale
s can be used in a call togetFaultReasonText
in order to obtain a localized version of the Reason Text string.- Returns:
- an
Iterator
over a sequence ofLocale
objects for which there are associated Reason Text items. - Throws:
SOAPException
- if there was an error in retrieving the fault Reason locales.UnsupportedOperationException
- if this message does not support the SOAP 1.2 concept of Fault Reason.- Since:
- 1.6, SAAJ 1.3
-
getFaultReasonTexts
Returns anIterator
over a sequence ofString
objects containing all the Reason Text items for thisSOAPFault
.- Returns:
- an
Iterator
over env:Fault/env:Reason/env:Text items. - Throws:
SOAPException
- if there was an error in retrieving the fault Reason texts.UnsupportedOperationException
- if this message does not support the SOAP 1.2 concept of Fault Reason.- Since:
- 1.6, SAAJ 1.3
-
getFaultReasonText
Returns the Reason Text associated with the givenLocale
. If more than one such Reason Text exists the first matching Text is returned- Parameters:
locale
- -- theLocale
for which a localized Reason Text is desired- Returns:
- the Reason Text associated with
locale
- Throws:
SOAPException
- if there was an error in retrieving the fault Reason text for the specified locale .UnsupportedOperationException
- if this message does not support the SOAP 1.2 concept of Fault Reason.- Since:
- 1.6, SAAJ 1.3
- See Also:
-
addFaultReasonText
Appends or replaces a Reason Text item containing the specified text message and an xml:lang derived fromlocale
. If a Reason Text item with this xml:lang already exists its text value will be replaced withtext
. Thelocale
parameter should not benull
Code sample:
SOAPFault fault = ...; fault.addFaultReasonText("Version Mismatch", Locale.ENGLISH);
- Parameters:
text
- -- reason message stringlocale
- -- Locale object representing the locale of the message- Throws:
SOAPException
- if there was an error in adding the Reason text or thelocale
passed wasnull
.UnsupportedOperationException
- if this message does not support the SOAP 1.2 concept of Fault Reason.- Since:
- 1.6, SAAJ 1.3
-
getFaultNode
String getFaultNode()Returns the optional Node element value for thisSOAPFault
object. The Node element is optional in SOAP 1.2.- Returns:
- Content of the env:Fault/env:Node element as a String
or
null
if none - Throws:
UnsupportedOperationException
- if this message does not support the SOAP 1.2 concept of Fault Node.- Since:
- 1.6, SAAJ 1.3
-
setFaultNode
Creates or replaces any existing Node element value for thisSOAPFault
object. The Node element is optional in SOAP 1.2.- Parameters:
uri
- the URI of the Node- Throws:
SOAPException
- if there was an error in setting the Node for thisSOAPFault
object.UnsupportedOperationException
- if this message does not support the SOAP 1.2 concept of Fault Node.- Since:
- 1.6, SAAJ 1.3
-
getFaultRole
String getFaultRole()Returns the optional Role element value for thisSOAPFault
object. The Role element is optional in SOAP 1.2.- Returns:
- Content of the env:Fault/env:Role element as a String
or
null
if none - Throws:
UnsupportedOperationException
- if this message does not support the SOAP 1.2 concept of Fault Role.- Since:
- 1.6, SAAJ 1.3
-
setFaultRole
Creates or replaces any existing Role element value for thisSOAPFault
object. The Role element is optional in SOAP 1.2.- Parameters:
uri
- the URI of the Role- Throws:
SOAPException
- if there was an error in setting the Role for thisSOAPFault
object.UnsupportedOperationException
- if this message does not support the SOAP 1.2 concept of Fault Role.- Since:
- 1.6, SAAJ 1.3
-