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    
006    package 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     */
037    public 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