001// SAX exception class.
002// http://www.saxproject.org
003// No warranty; no copyright -- use this as you will.
004// $Id: SAXParseException.java,v 1.1 2004/12/23 22:38:42 mark Exp $
005
006package org.xml.sax;
007
008/**
009 * Encapsulate an XML parse 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 exception may include information for locating the error
019 * in the original XML document, as if it came from a {@link Locator}
020 * object.  Note that although the application
021 * will receive a SAXParseException as the argument to the handlers
022 * in the {@link org.xml.sax.ErrorHandler ErrorHandler} interface,
023 * the application is not actually required to throw the exception;
024 * instead, it can simply read the information in it and take a
025 * different action.</p>
026 *
027 * <p>Since this exception is a subclass of {@link org.xml.sax.SAXException
028 * SAXException}, it inherits the ability to wrap another exception.</p>
029 *
030 * @since SAX 1.0
031 * @author David Megginson
032 * @version 2.0.1 (sax2r2)
033 * @see org.xml.sax.SAXException
034 * @see org.xml.sax.Locator
035 * @see org.xml.sax.ErrorHandler
036 */
037public class SAXParseException extends SAXException {
038
039
040    //////////////////////////////////////////////////////////////////////
041    // Constructors.
042    //////////////////////////////////////////////////////////////////////
043
044
045    /**
046     * Create a new SAXParseException from a message and a Locator.
047     *
048     * <p>This constructor is especially useful when an application is
049     * creating its own exception from within a {@link org.xml.sax.ContentHandler
050     * ContentHandler} callback.</p>
051     *
052     * @param message The error or warning message.
053     * @param locator The locator object for the error or warning (may be
054     *        null).
055     * @see org.xml.sax.Locator
056     */
057    public SAXParseException (String message, Locator locator) {
058        super(message);
059        if (locator != null) {
060            init(locator.getPublicId(), locator.getSystemId(),
061                 locator.getLineNumber(), locator.getColumnNumber());
062        } else {
063            init(null, null, -1, -1);
064        }
065    }
066
067
068    /**
069     * Wrap an existing exception in a SAXParseException.
070     *
071     * <p>This constructor is especially useful when an application is
072     * creating its own exception from within a {@link org.xml.sax.ContentHandler
073     * ContentHandler} callback, and needs to wrap an existing exception that is not a
074     * subclass of {@link org.xml.sax.SAXException SAXException}.</p>
075     *
076     * @param message The error or warning message, or null to
077     *                use the message from the embedded exception.
078     * @param locator The locator object for the error or warning (may be
079     *        null).
080     * @param e Any exception.
081     * @see org.xml.sax.Locator
082     */
083    public SAXParseException (String message, Locator locator,
084                              Exception e) {
085        super(message, e);
086        if (locator != null) {
087            init(locator.getPublicId(), locator.getSystemId(),
088                 locator.getLineNumber(), locator.getColumnNumber());
089        } else {
090            init(null, null, -1, -1);
091        }
092    }
093
094
095    /**
096     * Create a new SAXParseException.
097     *
098     * <p>This constructor is most useful for parser writers.</p>
099     *
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