Class 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
    Author:
    Doug Davis (dug@us.ibm.com), James Snell (jasnell@us.ibm.com), Steve Loughran
    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.lang.String faultActor  
      protected QName faultCode  
      protected java.util.Vector faultDetails  
      protected java.util.ArrayList faultHeaders
      SOAP headers which should be serialized with the Fault.
      protected java.lang.String faultNode  
      protected java.lang.String faultString  
      protected java.util.Vector faultSubCode
      SOAP1.2 addition: subcodes of faults; a Vector of QNames
      protected static org.apache.commons.logging.Log log
      The Log used by this class for all logging.
      • Fields inherited from class java.rmi.RemoteException

        detail
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        AxisFault()
      No-arg constructor for building one from an XML stream.
      protected AxisFault​(java.lang.Exception target)
      Wrap an AxisFault around an existing Exception.
        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.
        AxisFault​(QName code, java.lang.String faultString, java.lang.String actor, org.w3c.dom.Element[] details)
      Make a fault in any namespace.
        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.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void addFaultDetail​(QName qname, java.lang.String body)
      Create an element of the given qname and add it to the details.
      void addFaultDetail​(org.w3c.dom.Element detail)
      Append an element to the fault detail list.
      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.
      protected void initFaultSubCodes()
      Do whatever is needed to create the fault subcodes data structure, if it is needed.
      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​(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​(java.lang.String code)
      Deprecated.
      expect to see this go away after 1.1, use setFaultCodeAsString instead!
      void setFaultCode​(QName code)
      Set the fault code.
      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, 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

        addSuppressed, fillInStackTrace, getLocalizedMessage, getStackTrace, getSuppressed, initCause, printStackTrace, setStackTrace
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • log

        protected static org.apache.commons.logging.Log log
        The Log used by this class for all logging.
      • faultCode

        protected QName faultCode
      • faultSubCode

        protected java.util.Vector faultSubCode
        SOAP1.2 addition: subcodes of faults; a Vector of QNames
      • faultString

        protected java.lang.String faultString
      • faultActor

        protected java.lang.String faultActor
      • faultDetails

        protected java.util.Vector faultDetails
      • faultNode

        protected java.lang.String faultNode
      • faultHeaders

        protected java.util.ArrayList faultHeaders
        SOAP headers which should be serialized with the Fault.
    • 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

        protected AxisFault​(java.lang.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​(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
      • initFaultSubCodes

        protected void initFaultSubCodes()
        Do whatever is needed to create the fault subcodes data structure, if it is needed.
      • 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
      • 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​(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.
        Overrides:
        toString in class java.lang.Throwable
        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.
        Overrides:
        printStackTrace in class java.lang.Throwable
        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.
        Overrides:
        printStackTrace in class java.lang.Throwable
        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,
                                 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.