1// SAX exception class.
2// http://www.saxproject.org
3// No warranty; no copyright -- use this as you will.
4// $Id: SAXParseException.java,v 1.11 2004/04/21 13:05:02 dmegginson Exp $
5
6package org.xml.sax;
7
8/**
9 * Encapsulate an XML parse 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 exception may include information for locating the error
19 * in the original XML document, as if it came from a {@link Locator}
20 * object.  Note that although the application
21 * will receive a SAXParseException as the argument to the handlers
22 * in the {@link org.xml.sax.ErrorHandler ErrorHandler} interface,
23 * the application is not actually required to throw the exception;
24 * instead, it can simply read the information in it and take a
25 * different action.</p>
26 *
27 * <p>Since this exception is a subclass of {@link org.xml.sax.SAXException
28 * SAXException}, it inherits the ability to wrap another exception.</p>
29 *
30 * @since SAX 1.0
31 * @author David Megginson
32 * @version 2.0.1 (sax2r2)
33 * @see org.xml.sax.SAXException
34 * @see org.xml.sax.Locator
35 * @see org.xml.sax.ErrorHandler
36 */
37public class SAXParseException extends SAXException {
38
39
40    //////////////////////////////////////////////////////////////////////
41    // Constructors.
42    //////////////////////////////////////////////////////////////////////
43
44
45    /**
46     * Create a new SAXParseException from a message and a Locator.
47     *
48     * <p>This constructor is especially useful when an application is
49     * creating its own exception from within a {@link org.xml.sax.ContentHandler
50     * ContentHandler} callback.</p>
51     *
52     * @param message The error or warning message.
53     * @param locator The locator object for the error or warning (may be
54     *        null).
55     * @see org.xml.sax.Locator
56     */
57    public SAXParseException (String message, Locator locator) {
58    super(message);
59    if (locator != null) {
60        init(locator.getPublicId(), locator.getSystemId(),
61         locator.getLineNumber(), locator.getColumnNumber());
62    } else {
63        init(null, null, -1, -1);
64    }
65    }
66
67
68    /**
69     * Wrap an existing exception in a SAXParseException.
70     *
71     * <p>This constructor is especially useful when an application is
72     * creating its own exception from within a {@link org.xml.sax.ContentHandler
73     * ContentHandler} callback, and needs to wrap an existing exception that is not a
74     * subclass of {@link org.xml.sax.SAXException SAXException}.</p>
75     *
76     * @param message The error or warning message, or null to
77     *                use the message from the embedded exception.
78     * @param locator The locator object for the error or warning (may be
79     *        null).
80     * @param e Any exception.
81     * @see org.xml.sax.Locator
82     */
83    public SAXParseException (String message, Locator locator,
84                  Exception e) {
85    super(message, e);
86    if (locator != null) {
87        init(locator.getPublicId(), locator.getSystemId(),
88         locator.getLineNumber(), locator.getColumnNumber());
89    } else {
90        init(null, null, -1, -1);
91    }
92    }
93
94
95    /**
96     * Create a new SAXParseException.
97     *
98     * <p>This constructor is most useful for parser writers.</p>
99     *
100     * <p>All parameters except the message are as if
101     * they were provided by a {@link Locator}.  For example, if the
102     * system identifier is a URL (including relative filename), the
103     * caller must resolve it fully before creating the exception.</p>
104     *
105     *
106     * @param message The error or warning message.
107     * @param publicId The public identifier of the entity that generated
108     *                 the error or warning.
109     * @param systemId The system identifier of the entity that generated
110     *                 the error or warning.
111     * @param lineNumber The line number of the end of the text that
112     *                   caused the error or warning.
113     * @param columnNumber The column number of the end of the text that
114     *                     cause the error or warning.
115     */
116    public SAXParseException (String message, String publicId, String systemId,
117                  int lineNumber, int columnNumber)
118    {
119    super(message);
120    init(publicId, systemId, lineNumber, columnNumber);
121    }
122
123
124    /**
125     * Create a new SAXParseException with an embedded exception.
126     *
127     * <p>This constructor is most useful for parser writers who
128     * need to wrap an exception that is not a subclass of
129     * {@link org.xml.sax.SAXException SAXException}.</p>
130     *
131     * <p>All parameters except the message and exception are as if
132     * they were provided by a {@link Locator}.  For example, if the
133     * system identifier is a URL (including relative filename), the
134     * caller must resolve it fully before creating the exception.</p>
135     *
136     * @param message The error or warning message, or null to use
137     *                the message from the embedded exception.
138     * @param publicId The public identifier of the entity that generated
139     *                 the error or warning.
140     * @param systemId The system identifier of the entity that generated
141     *                 the error or warning.
142     * @param lineNumber The line number of the end of the text that
143     *                   caused the error or warning.
144     * @param columnNumber The column number of the end of the text that
145     *                     cause the error or warning.
146     * @param e Another exception to embed in this one.
147     */
148    public SAXParseException (String message, String publicId, String systemId,
149                  int lineNumber, int columnNumber, Exception e)
150    {
151    super(message, e);
152    init(publicId, systemId, lineNumber, columnNumber);
153    }
154
155
156    /**
157     * Internal initialization method.
158     *
159     * @param publicId The public identifier of the entity which generated the exception,
160     *        or null.
161     * @param systemId The system identifier of the entity which generated the exception,
162     *        or null.
163     * @param lineNumber The line number of the error, or -1.
164     * @param columnNumber The column number of the error, or -1.
165     */
166    private void init (String publicId, String systemId,
167               int lineNumber, int columnNumber)
168    {
169    this.publicId = publicId;
170    this.systemId = systemId;
171    this.lineNumber = lineNumber;
172    this.columnNumber = columnNumber;
173    }
174
175
176    /**
177     * Get the public identifier of the entity where the exception occurred.
178     *
179     * @return A string containing the public identifier, or null
180     *         if none is available.
181     * @see org.xml.sax.Locator#getPublicId
182     */
183    public String getPublicId ()
184    {
185    return this.publicId;
186    }
187
188
189    /**
190     * Get the system identifier of the entity where the exception occurred.
191     *
192     * <p>If the system identifier is a URL, it will have been resolved
193     * fully.</p>
194     *
195     * @return A string containing the system identifier, or null
196     *         if none is available.
197     * @see org.xml.sax.Locator#getSystemId
198     */
199    public String getSystemId ()
200    {
201    return this.systemId;
202    }
203
204
205    /**
206     * The line number of the end of the text where the exception occurred.
207     *
208     * <p>The first line is line 1.</p>
209     *
210     * @return An integer representing the line number, or -1
211     *         if none is available.
212     * @see org.xml.sax.Locator#getLineNumber
213     */
214    public int getLineNumber ()
215    {
216    return this.lineNumber;
217    }
218
219
220    /**
221     * The column number of the end of the text where the exception occurred.
222     *
223     * <p>The first column in a line is position 1.</p>
224     *
225     * @return An integer representing the column number, or -1
226     *         if none is available.
227     * @see org.xml.sax.Locator#getColumnNumber
228     */
229    public int getColumnNumber ()
230    {
231    return this.columnNumber;
232    }
233
234
235    //////////////////////////////////////////////////////////////////////
236    // Internal state.
237    //////////////////////////////////////////////////////////////////////
238
239
240    /**
241     * @serial The public identifier, or null.
242     * @see #getPublicId
243     */
244    private String publicId;
245
246
247    /**
248     * @serial The system identifier, or null.
249     * @see #getSystemId
250     */
251    private String systemId;
252
253
254    /**
255     * @serial The line number, or -1.
256     * @see #getLineNumber
257     */
258    private int lineNumber;
259
260
261    /**
262     * @serial The column number, or -1.
263     * @see #getColumnNumber
264     */
265    private int columnNumber;
266
267}
268
269// end of SAXParseException.java
270