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