001// SAX exception class.
002// http://www.saxproject.org
003// No warranty; no copyright -- use this as you will.
004// $Id: SAXException.java,v 1.1 2004/12/23 22:38:42 mark Exp $
005
006package org.xml.sax;
007
008/**
009 * Encapsulate a general SAX error or warning.
010 *
011 * <blockquote>
012 * <em>This module, both source code and documentation, is in the
013 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
014 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
015 * for further information.
016 * </blockquote>
017 *
018 * <p>This class can contain basic error or warning information from
019 * either the XML parser or the application: a parser writer or
020 * application writer can subclass it to provide additional
021 * functionality.  SAX handlers may throw this exception or
022 * any exception subclassed from it.</p>
023 *
024 * <p>If the application needs to pass through other types of
025 * exceptions, it must wrap those exceptions in a SAXException
026 * or an exception derived from a SAXException.</p>
027 *
028 * <p>If the parser or application needs to include information about a
029 * specific location in an XML document, it should use the
030 * {@link org.xml.sax.SAXParseException SAXParseException} subclass.</p>
031 *
032 * @since SAX 1.0
033 * @author David Megginson
034 * @version 2.0.1 (sax2r2)
035 * @see org.xml.sax.SAXParseException
036 */
037public class SAXException extends Exception {
038
039
040    /**
041     * Create a new SAXException.
042     */
043    public SAXException ()
044    {
045        super();
046        this.exception = null;
047    }
048    
049    
050    /**
051     * Create a new SAXException.
052     *
053     * @param message The error or warning message.
054     */
055    public SAXException (String message) {
056        super(message);
057        this.exception = null;
058    }
059    
060    
061    /**
062     * Create a new SAXException wrapping an existing exception.
063     *
064     * <p>The existing exception will be embedded in the new
065     * one, and its message will become the default message for
066     * the SAXException.</p>
067     *
068     * @param e The exception to be wrapped in a SAXException.
069     */
070    public SAXException (Exception e)
071    {
072        super();
073        this.exception = e;
074    }
075    
076    
077    /**
078     * Create a new SAXException from an existing exception.
079     *
080     * <p>The existing exception will be embedded in the new
081     * one, but the new exception will have its own message.</p>
082     *
083     * @param message The detail message.
084     * @param e The exception to be wrapped in a SAXException.
085     */
086    public SAXException (String message, Exception e)
087    {
088        super(message);
089        this.exception = e;
090    }
091    
092    
093    /**
094     * Return a detail message for this exception.
095     *
096     * <p>If there is an embedded exception, and if the SAXException
097     * has no detail message of its own, this method will return
098     * the detail message from the embedded exception.</p>
099     *
100     * @return The error or warning message.
101     */
102    public String getMessage ()
103    {
104        String message = super.getMessage();
105        
106        if (message == null && exception != null) {
107            return exception.getMessage();
108        } else {
109            return message;
110        }
111    }
112    
113    
114    /**
115     * Return the embedded exception, if any.
116     *
117     * @return The embedded exception, or null if there is none.
118     */
119    public Exception getException ()
120    {
121        return exception;
122    }
123
124
125    /**
126     * Override toString to pick up any embedded exception.
127     *
128     * @return A string representation of this exception.
129     */
130    public String toString ()
131    {
132        if (exception != null) {
133            return exception.toString();
134        } else {
135            return super.toString();
136        }
137    }
138    
139    
140    
141    //////////////////////////////////////////////////////////////////////
142    // Internal state.
143    //////////////////////////////////////////////////////////////////////
144
145
146    /**
147     * @serial The embedded exception if tunnelling, or null.
148     */    
149    private Exception exception;
150    
151}
152
153// end of SAXException.java