org.apache.axis

Class AxisFault

public class AxisFault extends RemoteException

An exception which maps cleanly to a SOAP fault. This is a base class for exceptions which are mapped to faults. SOAP faults contain
  1. A fault string
  2. A fault code
  3. A fault actor
  4. Fault details; an xml tree of fault specific stuff

Author: Doug Davis (dug@us.ibm.com) James Snell (jasnell@us.ibm.com) Steve Loughran

Field Summary
protected StringfaultActor
protected QNamefaultCode
protected VectorfaultDetails
protected ArrayListfaultHeaders
SOAP headers which should be serialized with the Fault.
protected StringfaultNode
protected StringfaultString
protected VectorfaultSubCode
SOAP1.2 addition: subcodes of faults; a Vector of QNames
protected static Loglog
The Log used by this class for all logging.
Constructor Summary
AxisFault(String code, String faultString, String actor, Element[] details)
Make a fault in the Constants.NS_URI_AXIS namespace.
AxisFault(QName code, String faultString, String actor, Element[] details)
Make a fault in any namespace.
AxisFault(QName code, QName[] subcodes, String faultString, String actor, String node, Element[] details)
Make a fault in any namespace.
protected AxisFault(Exception target)
Wrap an AxisFault around an existing Exception.
AxisFault(String message)
create a simple axis fault from the message.
AxisFault()
No-arg constructor for building one from an XML stream.
AxisFault(String message, Throwable t)
create a fault from any throwable; When faulting a throwable (as opposed to an exception), stack trace information does not go into the fault.
Method Summary
voidaddFaultDetail(Element detail)
Append an element to the fault detail list.
voidaddFaultDetail(QName qname, String body)
Create an element of the given qname and add it to the details.
voidaddFaultDetailString(String detail)
add a string tag to the fault details.
voidaddFaultSubCode(QName code)
Add a fault sub-code.
voidaddFaultSubCodeAsString(String code)
Add a fault sub-code with the local name code and namespace Constants.NS_URI_AXIS.
voidaddHeader(SOAPHeaderElement header)
Add a SOAP header which should be serialized along with the fault.
voidaddHostname(String hostname)
add the hostname string.
voidaddHostnameIfNeeded()
add the hostname of the current system.
voidclearFaultDetails()
Clear the fault details list.
voidclearFaultSubCodes()
Clear all fault sub-codes.
voidclearHeaders()
Clear all fault headers.
voiddump()
Dump the fault info to the log at debug level.
StringdumpToString()
turn the fault and details into a string, with XML escaping. subclassers: for security (cross-site-scripting) reasons, escape everything that could contain caller-supplied data.
StringgetFaultActor()
get the fault actor
QNamegetFaultCode()
Get the fault code QName.
Element[]getFaultDetails()
Get all the fault details.
StringgetFaultNode()
Get the fault node.
StringgetFaultReason()
This is SOAP 1.2 equivalent of {@link #getFaultString()}.
StringgetFaultRole()
This is SOAP 1.2 equivalent of {@link #getFaultActor()}.
StringgetFaultString()
Get the fault string; this will never be null but may be the empty string.
QName[]getFaultSubCodes()
get the fault subcode list; only used in SOAP 1.2
ArrayListgetHeaders()
Get the SOAP headers associated with this fault.
protected voidinitFaultSubCodes()
Do whatever is needed to create the fault subcodes data structure, if it is needed.
ElementlookupFaultDetail(QName qname)
Find a fault detail element by its qname.
static AxisFaultmakeFault(Exception e)
Make an AxisFault based on a passed Exception.
voidoutput(SerializationContext context)
Add this fault and any needed headers to the output context.
voidprintStackTrace(PrintStream ps)
The override of the base class method prints out the fault info before the stack trace.
voidprintStackTrace(PrintWriter pw)
The override of the base class method prints out the fault info before the stack trace.
booleanremoveFaultDetail(QName qname)
Find and remove a specified fault detail element.
voidremoveHostname()
strip out the hostname on a message.
voidsetFaultActor(String actor)
Set the fault actor.
voidsetFaultCode(QName code)
Set the fault code.
voidsetFaultCode(String code)
Set the fault code (as a String).
voidsetFaultCodeAsString(String code)
set a fault code string that is turned into a qname in the SOAP 1.1 or 1.2 namespace, depending on the current context
voidsetFaultDetail(Element[] details)
Set the fault detail element to the arrary of details.
voidsetFaultDetailString(String details)
set the fault details to a string element.
voidsetFaultNode(String node)
Set the fault node.
voidsetFaultReason(String str)
This is SOAP 1.2 equivalent of {@link #setFaultString(java.lang.String)}.
voidsetFaultRole(String role)
This is SOAP 1.2 equivalent of {@link #setFaultActor(java.lang.String)}.
voidsetFaultString(String str)
Set a fault string.
StringtoString()
Stringify this fault as the current fault string.
voidwriteDetails(QName qname, SerializationContext context)
Writes any exception data to the faultDetails.

Field Detail

faultActor

protected String faultActor

faultCode

protected QName faultCode

faultDetails

protected Vector faultDetails

faultHeaders

protected ArrayList faultHeaders
SOAP headers which should be serialized with the Fault.

faultNode

protected String faultNode

faultString

protected String faultString

faultSubCode

protected Vector faultSubCode
SOAP1.2 addition: subcodes of faults; a Vector of QNames

log

protected static Log log
The Log used by this class for all logging.

Constructor Detail

AxisFault

public AxisFault(String code, String faultString, String actor, Element[] details)
Make a fault in the Constants.NS_URI_AXIS namespace.

Parameters: code fault code which will be passed into the Axis namespace faultString fault string actor fault actor details details; if null the current stack trace and classname is inserted into the details.

AxisFault

public AxisFault(QName code, String faultString, String actor, Element[] details)
Make a fault in any namespace.

Parameters: code fault code which will be passed into the Axis namespace faultString fault string actor fault actor details details; if null the current stack trace and classname is inserted into the details.

AxisFault

public AxisFault(QName code, QName[] subcodes, String faultString, String actor, String node, Element[] details)
Make a fault in any namespace.

Parameters: code fault code which will be passed into the Axis namespace subcodes fault subcodes which will be pased into the Axis namespace faultString fault string actor fault actor, same as fault role in SOAP 1.2 node which node caused the fault on the SOAP path details details; if null the current stack trace and classname is inserted into the details.

Since: axis1.1

AxisFault

protected AxisFault(Exception target)
Wrap an AxisFault around an existing Exception. This is private to force everyone to use makeFault() above, which sanity-checks us.

Parameters: target the target Exception

AxisFault

public AxisFault(String message)
create a simple axis fault from the message. Classname and stack trace go into the fault details.

Parameters: message

AxisFault

public AxisFault()
No-arg constructor for building one from an XML stream.

AxisFault

public AxisFault(String message, Throwable t)
create a fault from any throwable; When faulting a throwable (as opposed to an exception), stack trace information does not go into the fault.

Parameters: message any extra text to with the fault t whatever is to be turned into a fault

Method Detail

addFaultDetail

public void addFaultDetail(Element detail)
Append an element to the fault detail list.

Parameters: detail the new element to add

Since: Axis1.1

addFaultDetail

public void addFaultDetail(QName qname, String body)
Create an element of the given qname and add it to the details.

Parameters: qname qname of the element body string to use as body

addFaultDetailString

public void addFaultDetailString(String detail)
add a string tag to the fault details.

Parameters: detail XML fragment

addFaultSubCode

public void addFaultSubCode(QName code)
Add a fault sub-code. This is new in SOAP 1.2, ignored in SOAP 1.1.

Parameters: code the QName of the fault sub-code to add

Since: axis1.1

addFaultSubCodeAsString

public void addFaultSubCodeAsString(String code)
Add a fault sub-code with the local name code and namespace Constants.NS_URI_AXIS. This is new in SOAP 1.2, ignored in SOAP 1.1

Parameters: code the local name of the code to add

Since: axis1.1

addHeader

public void addHeader(SOAPHeaderElement header)
Add a SOAP header which should be serialized along with the fault.

Parameters: header a SOAPHeaderElement containing some fault-relevant stuff

addHostname

public void addHostname(String hostname)
add the hostname string. If one already exists, remove it.

Parameters: hostname string name of a host

Since: Axis1.2

addHostnameIfNeeded

public void addHostnameIfNeeded()
add the hostname of the current system. This is very useful for locating faults on a cluster.

Since: Axis1.2

clearFaultDetails

public void clearFaultDetails()
Clear the fault details list.

clearFaultSubCodes

public void clearFaultSubCodes()
Clear all fault sub-codes. This is new in SOAP 1.2, ignored in SOAP 1.1.

Since: axis1.1

clearHeaders

public void clearHeaders()
Clear all fault headers.

dump

public void dump()
Dump the fault info to the log at debug level.

dumpToString

public String dumpToString()
turn the fault and details into a string, with XML escaping. subclassers: for security (cross-site-scripting) reasons, escape everything that could contain caller-supplied data.

Returns: stringified fault details

getFaultActor

public String getFaultActor()
get the fault actor

Returns: actor or null

getFaultCode

public QName getFaultCode()
Get the fault code QName.

Returns: fault code QName or null if there is none yet.

getFaultDetails

public Element[] getFaultDetails()
Get all the fault details.

Returns: an array of fault details, or null for none

getFaultNode

public String getFaultNode()
Get the fault node. This is new in SOAP 1.2

Returns:

Since: axis1.1

getFaultReason

public String getFaultReason()
This is SOAP 1.2 equivalent of {@link #getFaultString()}.

Returns: the fault String

Since: axis1.1

getFaultRole

public String getFaultRole()
This is SOAP 1.2 equivalent of {@link #getFaultActor()}.

Returns: the name of the fault actor

Since: axis1.1

getFaultString

public String getFaultString()
Get the fault string; this will never be null but may be the empty string.

Returns: a fault string

getFaultSubCodes

public QName[] getFaultSubCodes()
get the fault subcode list; only used in SOAP 1.2

Returns: null for no subcodes, or a QName array

Since: axis1.1

getHeaders

public ArrayList getHeaders()
Get the SOAP headers associated with this fault.

Returns: an ArrayList containing any headers associated with this fault

initFaultSubCodes

protected void initFaultSubCodes()
Do whatever is needed to create the fault subcodes data structure, if it is needed.

lookupFaultDetail

public Element lookupFaultDetail(QName qname)
Find a fault detail element by its qname.

Parameters: qname name of the node to look for

Returns: the matching element or null

Since: axis1.1

makeFault

public static AxisFault makeFault(Exception e)
Make an AxisFault based on a passed Exception. If the Exception is already an AxisFault, simply use that. Otherwise, wrap it in an AxisFault. If the Exception is an InvocationTargetException (which already wraps another Exception), get the wrapped Exception out from there and use that instead of the passed one.

Parameters: e the Exception to build a fault for

Returns: an AxisFault representing e

output

public void output(SerializationContext context)
Add this fault and any needed headers to the output context.

Parameters: context

Throws: Exception

printStackTrace

public void printStackTrace(PrintStream ps)
The override of the base class method prints out the fault info before the stack trace.

Parameters: ps where to print

printStackTrace

public void printStackTrace(PrintWriter pw)
The override of the base class method prints out the fault info before the stack trace.

Parameters: pw where to print

removeFaultDetail

public boolean removeFaultDetail(QName qname)
Find and remove a specified fault detail element.

Parameters: qname qualified name of detail

Returns: true if it was found and removed, false otherwise

Since: axis1.1

removeHostname

public void removeHostname()
strip out the hostname on a message. This is useful for security reasons.

setFaultActor

public void setFaultActor(String actor)
Set the fault actor.

Parameters: actor fault actor

setFaultCode

public void setFaultCode(QName code)
Set the fault code.

Parameters: code a new fault code

setFaultCode

public void setFaultCode(String code)

Deprecated: expect to see this go away after 1.1, use setFaultCodeAsString instead!

Set the fault code (as a String).

Parameters: code a new fault code

setFaultCodeAsString

public void setFaultCodeAsString(String code)
set a fault code string that is turned into a qname in the SOAP 1.1 or 1.2 namespace, depending on the current context

Parameters: code fault code

setFaultDetail

public void setFaultDetail(Element[] details)
Set the fault detail element to the arrary of details.

Parameters: details list of detail elements, can be null

setFaultDetailString

public void setFaultDetailString(String details)
set the fault details to a string element.

Parameters: details XML fragment

setFaultNode

public void setFaultNode(String node)
Set the fault node. This is new in SOAP 1.2.

Parameters: node a String representing the fault node

Since: axis1.1

setFaultReason

public void setFaultReason(String str)
This is SOAP 1.2 equivalent of {@link #setFaultString(java.lang.String)}.

Parameters: str the fault reason as a String

Since: axis1.1

setFaultRole

public void setFaultRole(String role)
This is SOAP 1.2 equivalent of {@link #setFaultActor(java.lang.String)}.

Since: axis1.1

setFaultString

public void setFaultString(String str)
Set a fault string.

Parameters: str new fault string; null is turned into ""

toString

public String toString()
Stringify this fault as the current fault string.

Returns: the fault string, possibly the empty string, but never null

writeDetails

public void writeDetails(QName qname, SerializationContext context)
Writes any exception data to the faultDetails. This can be overridden (and is) by emitted exception clases. The base implementation will attempt to serialize exception data the fault was created from an Exception and a type mapping is found for it.

Parameters: qname the QName to write this under context the SerializationContext to write this fault to

Throws: java.io.IOException if we can't write ourselves for any reason

Copyright B) 2005 Apache Web Services Project. All Rights Reserved.