1// SAX exception class.
2// http://www.saxproject.org
3// No warranty; no copyright -- use this as you will.
4// $Id: SAXException.java,v 1.7 2002/01/30 21:13:48 dbrownell Exp $
5
6package org.xml.sax;
7
8/**
9 * Encapsulate a general SAX error or warning.
10 *
11 * <blockquote>
12 * <em>This module, both source code and documentation, is in the
13 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
14 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
15 * for further information.
16 * </blockquote>
17 *
18 * <p>This class can contain basic error or warning information from
19 * either the XML parser or the application: a parser writer or
20 * application writer can subclass it to provide additional
21 * functionality.  SAX handlers may throw this exception or
22 * any exception subclassed from it.</p>
23 *
24 * <p>If the application needs to pass through other types of
25 * exceptions, it must wrap those exceptions in a SAXException
26 * or an exception derived from a SAXException.</p>
27 *
28 * <p>If the parser or application needs to include information about a
29 * specific location in an XML document, it should use the
30 * {@link org.xml.sax.SAXParseException SAXParseException} subclass.</p>
31 *
32 * @since SAX 1.0
33 * @author David Megginson
34 * @version 2.0.1 (sax2r2)
35 * @see org.xml.sax.SAXParseException
36 */
37public class SAXException extends Exception {
38
39
40    /**
41     * Create a new SAXException.
42     */
43    public SAXException ()
44    {
45    this.exception = null;
46    }
47
48
49    /**
50     * Create a new SAXException.
51     *
52     * @param message The error or warning message.
53     */
54    public SAXException (String message) {
55    super(message);
56    this.exception = null;
57    }
58
59
60    /**
61     * Create a new SAXException wrapping an existing exception.
62     *
63     * <p>The existing exception will be embedded in the new
64     * one, and its message will become the default message for
65     * the SAXException.</p>
66     *
67     * @param e The exception to be wrapped in a SAXException.
68     */
69    public SAXException (Exception e)
70    {
71    this.exception = e;
72    }
73
74
75    /**
76     * Create a new SAXException from an existing exception.
77     *
78     * <p>The existing exception will be embedded in the new
79     * one, but the new exception will have its own message.</p>
80     *
81     * @param message The detail message.
82     * @param e The exception to be wrapped in a SAXException.
83     */
84    public SAXException (String message, Exception e)
85    {
86    super(message);
87    this.exception = e;
88    }
89
90
91    /**
92     * Return a detail message for this exception.
93     *
94     * <p>If there is an embedded exception, and if the SAXException
95     * has no detail message of its own, this method will return
96     * the detail message from the embedded exception.</p>
97     *
98     * @return The error or warning message.
99     */
100    public String getMessage ()
101    {
102    String message = super.getMessage();
103
104    if (message == null && exception != null) {
105        return exception.getMessage();
106    } else {
107        return message;
108    }
109    }
110
111
112    /**
113     * Return the embedded exception, if any.
114     *
115     * @return The embedded exception, or null if there is none.
116     */
117    public Exception getException ()
118    {
119    return exception;
120    }
121
122
123    /**
124     * Override toString to pick up any embedded exception.
125     *
126     * @return A string representation of this exception.
127     */
128    public String toString ()
129    {
130    if (exception != null) {
131        return exception.toString();
132    } else {
133        return super.toString();
134    }
135    }
136
137
138
139    //////////////////////////////////////////////////////////////////////
140    // Internal state.
141    //////////////////////////////////////////////////////////////////////
142
143
144    /**
145     * @serial The embedded exception if tunnelling, or null.
146     */
147    private Exception exception;
148
149}
150
151// end of SAXException.java
152