org.apache.axis
Class AxisFault

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          java.io.IOException
              java.rmi.RemoteException
                  org.apache.axis.AxisFault

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

NoEndPointException

public class AxisFault

extends java.rmi.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

See Also:

Serialized Form

Field Summary

Fields inherited from class java.rmi.RemoteException

detail

Constructor Summary

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

AxisFault(QName code, QName[] subcodes, java.lang.String faultString, java.lang.String actor, java.lang.String node, org.w3c.dom.Element[] details)
Make a fault in any namespace.

AxisFault(QName code, java.lang.String faultString, java.lang.String actor, org.w3c.dom.Element[] details)
Make a fault in any namespace.

AxisFault(java.lang.String message)
create a simple axis fault from the message.

AxisFault(java.lang.String code, java.lang.String faultString, java.lang.String actor, org.w3c.dom.Element[] details)
Make a fault in the Constants.NS_URI_AXIS namespace.

AxisFault(java.lang.String message, java.lang.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

void	addFaultDetail(org.w3c.dom.Element detail) Append an element to the fault detail list.
void	addFaultDetail(QName qname, java.lang.String body) Create an element of the given qname and add it to the details.
void	addFaultDetailString(java.lang.String detail) add a string tag to the fault details.
void	addFaultSubCode(QName code) Add a fault sub-code.
void	addFaultSubCodeAsString(java.lang.String code) Add a fault sub-code with the local name code and namespace Constants.NS_URI_AXIS.
void	addHeader(SOAPHeaderElement header) Add a SOAP header which should be serialized along with the fault.
void	addHostname(java.lang.String hostname) add the hostname string.
void	addHostnameIfNeeded() add the hostname of the current system.
void	clearFaultDetails() Clear the fault details list.
void	clearFaultSubCodes() Clear all fault sub-codes.
void	clearHeaders() Clear all fault headers.
void	dump() Dump the fault info to the log at debug level.
java.lang.String	dumpToString() turn the fault and details into a string, with XML escaping.
java.lang.String	getFaultActor() get the fault actor
QName	getFaultCode() Get the fault code QName.
org.w3c.dom.Element[]	getFaultDetails() Get all the fault details.
java.lang.String	getFaultNode() Get the fault node.
java.lang.String	getFaultReason() This is SOAP 1.2 equivalent of getFaultString().
java.lang.String	getFaultRole() This is SOAP 1.2 equivalent of getFaultActor().
java.lang.String	getFaultString() 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
java.util.ArrayList	getHeaders() Get the SOAP headers associated with this fault.
org.w3c.dom.Element	lookupFaultDetail(QName qname) Find a fault detail element by its qname.
static AxisFault	makeFault(java.lang.Exception e) Make an AxisFault based on a passed Exception.
void	output(org.apache.axis.encoding.SerializationContext context) Add this fault and any needed headers to the output context.
void	printStackTrace(java.io.PrintStream ps) The override of the base class method prints out the fault info before the stack trace.
void	printStackTrace(java.io.PrintWriter pw) The override of the base class method prints out the fault info before the stack trace.
boolean	removeFaultDetail(QName qname) Find and remove a specified fault detail element.
void	removeHostname() strip out the hostname on a message.
void	setFaultActor(java.lang.String actor) Set the fault actor.
void	setFaultCode(QName code) Set the fault code.
void	setFaultCode(java.lang.String code) Deprecated. expect to see this go away after 1.1, use setFaultCodeAsString instead!
void	setFaultCodeAsString(java.lang.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
void	setFaultDetail(org.w3c.dom.Element[] details) Set the fault detail element to the arrary of details.
void	setFaultDetailString(java.lang.String details) set the fault details to a string element.
void	setFaultNode(java.lang.String node) Set the fault node.
void	setFaultReason(java.lang.String str) This is SOAP 1.2 equivalent of setFaultString(java.lang.String).
void	setFaultRole(java.lang.String role) This is SOAP 1.2 equivalent of setFaultActor(java.lang.String).
void	setFaultString(java.lang.String str) Set a fault string.
java.lang.String	toString() Stringify this fault as the current fault string.
void	writeDetails(QName qname, org.apache.axis.encoding.SerializationContext context) Writes any exception data to the faultDetails.

Methods inherited from class java.rmi.RemoteException

getCause, getMessage

Methods inherited from class java.lang.Throwable

fillInStackTrace, getLocalizedMessage, getStackTrace, initCause, printStackTrace, setStackTrace

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AxisFault

public AxisFault(java.lang.String code,
                 java.lang.String faultString,
                 java.lang.String actor,
                 org.w3c.dom.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,
                 java.lang.String faultString,
                 java.lang.String actor,
                 org.w3c.dom.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,
                 java.lang.String faultString,
                 java.lang.String actor,
                 java.lang.String node,
                 org.w3c.dom.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

public AxisFault(java.lang.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(java.lang.String message,
                 java.lang.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

makeFault

public static AxisFault makeFault(java.lang.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

clearFaultDetails

public void clearFaultDetails()

Clear the fault details list.

dump

public void dump()

Dump the fault info to the log at debug level.

dumpToString

public java.lang.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

setFaultCode

public void setFaultCode(QName code)

Set the fault code.

Parameters:

code - a new fault code

setFaultCode

public void setFaultCode(java.lang.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(java.lang.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

getFaultCode

public QName getFaultCode()

Get the fault code QName.

Returns:

fault code QName or null if there is none yet.

addFaultSubCodeAsString

public void addFaultSubCodeAsString(java.lang.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

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

clearFaultSubCodes

public void clearFaultSubCodes()

Clear all fault sub-codes. This is new in SOAP 1.2, ignored in SOAP 1.1.

Since:

axis1.1

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

setFaultString

public void setFaultString(java.lang.String str)

Set a fault string.

Parameters:

str - new fault string; null is turned into ""

getFaultString

public java.lang.String getFaultString()

Get the fault string; this will never be null but may be the empty string.

Returns:

a fault string

setFaultReason

public void setFaultReason(java.lang.String str)

This is SOAP 1.2 equivalent of setFaultString(java.lang.String).

Parameters:

str - the fault reason as a String

Since:

axis1.1

getFaultReason

public java.lang.String getFaultReason()

This is SOAP 1.2 equivalent of getFaultString().

Returns:

the fault String

Since:

axis1.1

setFaultActor

public void setFaultActor(java.lang.String actor)

Set the fault actor.

Parameters:

actor - fault actor

getFaultActor

public java.lang.String getFaultActor()

get the fault actor

Returns:

actor or null

getFaultRole

public java.lang.String getFaultRole()

This is SOAP 1.2 equivalent of getFaultActor().

Returns:

the name of the fault actor

Since:

axis1.1

setFaultRole

public void setFaultRole(java.lang.String role)

This is SOAP 1.2 equivalent of setFaultActor(java.lang.String).

Since:

axis1.1

getFaultNode

public java.lang.String getFaultNode()

Get the fault node. This is new in SOAP 1.2

Returns:

Since:

axis1.1

setFaultNode

public void setFaultNode(java.lang.String node)

Set the fault node. This is new in SOAP 1.2.

Parameters:

node - a String representing the fault node

Since:

axis1.1

setFaultDetail

public void setFaultDetail(org.w3c.dom.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(java.lang.String details)

set the fault details to a string element.

Parameters:

details - XML fragment

addFaultDetailString

public void addFaultDetailString(java.lang.String detail)

add a string tag to the fault details.

Parameters:

detail - XML fragment

addFaultDetail

public void addFaultDetail(org.w3c.dom.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,
                           java.lang.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

getFaultDetails

public org.w3c.dom.Element[] getFaultDetails()

Get all the fault details.

Returns:

an array of fault details, or null for none

lookupFaultDetail

public org.w3c.dom.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

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

output

public void output(org.apache.axis.encoding.SerializationContext context)
            throws java.lang.Exception

Add this fault and any needed headers to the output context.

Parameters:

context -

Throws:

java.lang.Exception

toString

public java.lang.String toString()

Stringify this fault as the current fault string.

Returns:

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

printStackTrace

public void printStackTrace(java.io.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(java.io.PrintWriter pw)

The override of the base class method prints out the fault info before the stack trace.

Parameters:

pw - where to print

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

getHeaders

public java.util.ArrayList getHeaders()

Get the SOAP headers associated with this fault.

Returns:

an ArrayList containing any headers associated with this fault

clearHeaders

public void clearHeaders()

Clear all fault headers.

writeDetails

public void writeDetails(QName qname,
                         org.apache.axis.encoding.SerializationContext context)
                  throws java.io.IOException

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

addHostnameIfNeeded

public void addHostnameIfNeeded()

add the hostname of the current system. This is very useful for locating faults on a cluster.

Since:

Axis1.2

addHostname

public void addHostname(java.lang.String hostname)

add the hostname string. If one already exists, remove it.

Parameters:

hostname - string name of a host

Since:

Axis1.2

removeHostname

public void removeHostname()

strip out the hostname on a message. This is useful for security reasons.