001// SAX exception class.
002// No warranty; no copyright -- use this as you will.
003// $Id: SAXParseException.java,v 1.1 2001/03/05 21:40:06 jstrachan Exp $
004
005package org.xml.sax;
006
007/**
008 * Encapsulate an XML parse 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 exception will include information for locating the error
016 * in the original XML document.  Note that although the application
017 * will receive a SAXParseException as the argument to the handlers
018 * in the {@link org.xml.sax.ErrorHandler ErrorHandler} interface, 
019 * the application is not actually required to throw the exception; 
020 * instead, it can simply read the information in it and take a 
021 * different action.</p>
022 *
023 * <p>Since this exception is a subclass of {@link org.xml.sax.SAXException 
024 * SAXException}, it inherits the ability to wrap another exception.</p>
025 *
026 * @since SAX 1.0
027 * @author David Megginson, 
028 *         <a href="mailto:sax@megginson.com">sax@megginson.com</a>
029 * @version 2.0
030 * @see org.xml.sax.SAXException
031 * @see org.xml.sax.Locator
032 * @see org.xml.sax.ErrorHandler
033 */
034public class SAXParseException extends SAXException {
035    
036    
037    //////////////////////////////////////////////////////////////////////
038    // Constructors.
039    //////////////////////////////////////////////////////////////////////
040
041
042    /**
043     * Create a new SAXParseException from a message and a Locator.
044     *
045     * <p>This constructor is especially useful when an application is
046     * creating its own exception from within a {@link org.xml.sax.ContentHandler
047     * ContentHandler} callback.</p>
048     *
049     * @param message The error or warning message.
050     * @param locator The locator object for the error or warning (may be
051     *        null).
052     * @see org.xml.sax.Locator
053     * @see org.xml.sax.Parser#setLocale 
054     */
055    public SAXParseException (String message, Locator locator) {
056        super(message);
057        if (locator != null) {
058            init(locator.getPublicId(), locator.getSystemId(),
059                 locator.getLineNumber(), locator.getColumnNumber());
060        } else {
061            init(null, null, -1, -1);
062        }
063    }
064    
065    
066    /**
067     * Wrap an existing exception in a SAXParseException.
068     *
069     * <p>This constructor is especially useful when an application is
070     * creating its own exception from within a {@link org.xml.sax.ContentHandler
071     * ContentHandler} callback, and needs to wrap an existing exception that is not a
072     * subclass of {@link org.xml.sax.SAXException SAXException}.</p>
073     *
074     * @param message The error or warning message, or null to
075     *                use the message from the embedded exception.
076     * @param locator The locator object for the error or warning (may be
077     *        null).
078     * @param e Any exception.
079     * @see org.xml.sax.Locator
080     * @see org.xml.sax.Parser#setLocale
081     */
082    public SAXParseException (String message, Locator locator,
083                              Exception e) {
084        super(message, e);
085        if (locator != null) {
086            init(locator.getPublicId(), locator.getSystemId(),
087                 locator.getLineNumber(), locator.getColumnNumber());
088        } else {
089            init(null, null, -1, -1);
090        }
091    }
092    
093    
094    /**
095     * Create a new SAXParseException.
096     *
097     * <p>This constructor is most useful for parser writers.</p>
098     *
099     * <p>If the system identifier is a URL, the parser must resolve it
100     * fully before creating the exception.</p>
101     *
102     * @param message The error or warning message.
103     * @param publicId The public identifer of the entity that generated
104     *                 the error or warning.
105     * @param systemId The system identifer of the entity that generated
106     *                 the error or warning.
107     * @param lineNumber The line number of the end of the text that
108     *                   caused the error or warning.
109     * @param columnNumber The column number of the end of the text that
110     *                     cause the error or warning.
111     * @see org.xml.sax.Parser#setLocale
112     */
113    public SAXParseException (String message, String publicId, String systemId,
114                              int lineNumber, int columnNumber)
115    {
116        super(message);
117        init(publicId, systemId, lineNumber, columnNumber);
118    }
119    
120    
121    /**
122     * Create a new SAXParseException with an embedded exception.
123     *
124     * <p>This constructor is most useful for parser writers who
125     * need to wrap an exception that is not a subclass of
126     * {@link org.xml.sax.SAXException SAXException}.</p>
127     *
128     * <p>If the system identifier is a URL, the parser must resolve it
129     * fully before creating the exception.</p>
130     *
131     * @param message The error or warning message, or null to use
132     *                the message from the embedded exception.
133     * @param publicId The public identifer of the entity that generated
134     *                 the error or warning.
135     * @param systemId The system identifer of the entity that generated
136     *                 the error or warning.
137     * @param lineNumber The line number of the end of the text that
138     *                   caused the error or warning.
139     * @param columnNumber The column number of the end of the text that
140     *                     cause the error or warning.
141     * @param e Another exception to embed in this one.
142     * @see org.xml.sax.Parser#setLocale
143     */
144    public SAXParseException (String message, String publicId, String systemId,
145                              int lineNumber, int columnNumber, Exception e)
146    {
147        super(message, e);
148        init(publicId, systemId, lineNumber, columnNumber);
149    }
150
151
152    /**
153     * Internal initialization method.
154     *
155     * @param publicId The public identifier of the entity which generated the exception,
156     *        or null.
157     * @param systemId The system identifier of the entity which generated the exception,
158     *        or null.
159     * @param lineNumber The line number of the error, or -1.
160     * @param columnNumber The column number of the error, or -1.
161     */
162    private void init (String publicId, String systemId,
163                       int lineNumber, int columnNumber)
164    {
165        this.publicId = publicId;
166        this.systemId = systemId;
167        this.lineNumber = lineNumber;
168        this.columnNumber = columnNumber;
169    }
170    
171    
172    /**
173     * Get the public identifier of the entity where the exception occurred.
174     *
175     * @return A string containing the public identifier, or null
176     *         if none is available.
177     * @see org.xml.sax.Locator#getPublicId
178     */
179    public String getPublicId ()
180    {
181        return this.publicId;
182    }
183    
184    
185    /**
186     * Get the system identifier of the entity where the exception occurred.
187     *
188     * <p>If the system identifier is a URL, it will be resolved
189     * fully.</p>
190     *
191     * @return A string containing the system identifier, or null
192     *         if none is available.
193     * @see org.xml.sax.Locator#getSystemId
194     */
195    public String getSystemId ()
196    {
197        return this.systemId;
198    }
199    
200    
201    /**
202     * The line number of the end of the text where the exception occurred.
203     *
204     * @return An integer representing the line number, or -1
205     *         if none is available.
206     * @see org.xml.sax.Locator#getLineNumber
207     */
208    public int getLineNumber ()
209    {
210        return this.lineNumber;
211    }
212    
213    
214    /**
215     * The column number of the end of the text where the exception occurred.
216     *
217     * <p>The first column in a line is position 1.</p>
218     *
219     * @return An integer representing the column number, or -1
220     *         if none is available.
221     * @see org.xml.sax.Locator#getColumnNumber
222     */
223    public int getColumnNumber ()
224    {
225        return this.columnNumber;
226    }
227    
228    
229    
230    //////////////////////////////////////////////////////////////////////
231    // Internal state.
232    //////////////////////////////////////////////////////////////////////
233
234
235    /**
236     * @serial The public identifier, or null.
237     * @see #getPublicId
238     */    
239    private String publicId;
240
241
242    /**
243     * @serial The system identifier, or null.
244     * @see #getSystemId
245     */
246    private String systemId;
247
248
249    /**
250     * @serial The line number, or -1.
251     * @see #getLineNumber
252     */
253    private int lineNumber;
254
255
256    /**
257     * @serial The column number, or -1.
258     * @see #getColumnNumber
259     */
260    private int columnNumber;
261    
262}
263
264// end of SAXParseException.java