View Javadoc
1   /*
2    * Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  // SAX exception class.
27  // http://www.saxproject.org
28  // No warranty; no copyright -- use this as you will.
29  // $Id: SAXParseException.java,v 1.2 2004/11/03 22:55:32 jsuttor Exp $
30  
31  package org.xml.sax;
32  
33  /**
34   * Encapsulate an XML parse error or warning.
35   *
36   * <blockquote>
37   * <em>This module, both source code and documentation, is in the
38   * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
39   * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>;
40   * for further information.
41   * </blockquote>
42   *
43   * <p>This exception may include information for locating the error
44   * in the original XML document, as if it came from a {@link Locator}
45   * object.  Note that although the application
46   * will receive a SAXParseException as the argument to the handlers
47   * in the {@link org.xml.sax.ErrorHandler ErrorHandler} interface,
48   * the application is not actually required to throw the exception;
49   * instead, it can simply read the information in it and take a
50   * different action.</p>
51   *
52   * <p>Since this exception is a subclass of {@link org.xml.sax.SAXException
53   * SAXException}, it inherits the ability to wrap another exception.</p>
54   *
55   * @since SAX 1.0
56   * @author David Megginson
57   * @version 2.0.1 (sax2r2)
58   * @see org.xml.sax.SAXException
59   * @see org.xml.sax.Locator
60   * @see org.xml.sax.ErrorHandler
61   */
62  public class SAXParseException extends SAXException {
63  
64  
65      //////////////////////////////////////////////////////////////////////
66      // Constructors.
67      //////////////////////////////////////////////////////////////////////
68  
69  
70      /**
71       * Create a new SAXParseException from a message and a Locator.
72       *
73       * <p>This constructor is especially useful when an application is
74       * creating its own exception from within a {@link org.xml.sax.ContentHandler
75       * ContentHandler} callback.</p>
76       *
77       * @param message The error or warning message.
78       * @param locator The locator object for the error or warning (may be
79       *        null).
80       * @see org.xml.sax.Locator
81       */
82      public SAXParseException (String message, Locator locator) {
83          super(message);
84          if (locator != null) {
85              init(locator.getPublicId(), locator.getSystemId(),
86                   locator.getLineNumber(), locator.getColumnNumber());
87          } else {
88              init(null, null, -1, -1);
89          }
90      }
91  
92  
93      /**
94       * Wrap an existing exception in a SAXParseException.
95       *
96       * <p>This constructor is especially useful when an application is
97       * creating its own exception from within a {@link org.xml.sax.ContentHandler
98       * ContentHandler} callback, and needs to wrap an existing exception that is not a
99       * subclass of {@link org.xml.sax.SAXException SAXException}.</p>
100      *
101      * @param message The error or warning message, or null to
102      *                use the message from the embedded exception.
103      * @param locator The locator object for the error or warning (may be
104      *        null).
105      * @param e Any exception.
106      * @see org.xml.sax.Locator
107      */
108     public SAXParseException (String message, Locator locator,
109                               Exception e) {
110         super(message, e);
111         if (locator != null) {
112             init(locator.getPublicId(), locator.getSystemId(),
113                  locator.getLineNumber(), locator.getColumnNumber());
114         } else {
115             init(null, null, -1, -1);
116         }
117     }
118 
119 
120     /**
121      * Create a new SAXParseException.
122      *
123      * <p>This constructor is most useful for parser writers.</p>
124      *
125      * <p>All parameters except the message are as if
126      * they were provided by a {@link Locator}.  For example, if the
127      * system identifier is a URL (including relative filename), the
128      * caller must resolve it fully before creating the exception.</p>
129      *
130      *
131      * @param message The error or warning message.
132      * @param publicId The public identifier of the entity that generated
133      *                 the error or warning.
134      * @param systemId The system identifier of the entity that generated
135      *                 the error or warning.
136      * @param lineNumber The line number of the end of the text that
137      *                   caused the error or warning.
138      * @param columnNumber The column number of the end of the text that
139      *                     cause the error or warning.
140      */
141     public SAXParseException (String message, String publicId, String systemId,
142                               int lineNumber, int columnNumber)
143     {
144         super(message);
145         init(publicId, systemId, lineNumber, columnNumber);
146     }
147 
148 
149     /**
150      * Create a new SAXParseException with an embedded exception.
151      *
152      * <p>This constructor is most useful for parser writers who
153      * need to wrap an exception that is not a subclass of
154      * {@link org.xml.sax.SAXException SAXException}.</p>
155      *
156      * <p>All parameters except the message and exception are as if
157      * they were provided by a {@link Locator}.  For example, if the
158      * system identifier is a URL (including relative filename), the
159      * caller must resolve it fully before creating the exception.</p>
160      *
161      * @param message The error or warning message, or null to use
162      *                the message from the embedded exception.
163      * @param publicId The public identifier of the entity that generated
164      *                 the error or warning.
165      * @param systemId The system identifier of the entity that generated
166      *                 the error or warning.
167      * @param lineNumber The line number of the end of the text that
168      *                   caused the error or warning.
169      * @param columnNumber The column number of the end of the text that
170      *                     cause the error or warning.
171      * @param e Another exception to embed in this one.
172      */
173     public SAXParseException (String message, String publicId, String systemId,
174                               int lineNumber, int columnNumber, Exception e)
175     {
176         super(message, e);
177         init(publicId, systemId, lineNumber, columnNumber);
178     }
179 
180 
181     /**
182      * Internal initialization method.
183      *
184      * @param publicId The public identifier of the entity which generated the exception,
185      *        or null.
186      * @param systemId The system identifier of the entity which generated the exception,
187      *        or null.
188      * @param lineNumber The line number of the error, or -1.
189      * @param columnNumber The column number of the error, or -1.
190      */
191     private void init (String publicId, String systemId,
192                        int lineNumber, int columnNumber)
193     {
194         this.publicId = publicId;
195         this.systemId = systemId;
196         this.lineNumber = lineNumber;
197         this.columnNumber = columnNumber;
198     }
199 
200 
201     /**
202      * Get the public identifier of the entity where the exception occurred.
203      *
204      * @return A string containing the public identifier, or null
205      *         if none is available.
206      * @see org.xml.sax.Locator#getPublicId
207      */
208     public String getPublicId ()
209     {
210         return this.publicId;
211     }
212 
213 
214     /**
215      * Get the system identifier of the entity where the exception occurred.
216      *
217      * <p>If the system identifier is a URL, it will have been resolved
218      * fully.</p>
219      *
220      * @return A string containing the system identifier, or null
221      *         if none is available.
222      * @see org.xml.sax.Locator#getSystemId
223      */
224     public String getSystemId ()
225     {
226         return this.systemId;
227     }
228 
229 
230     /**
231      * The line number of the end of the text where the exception occurred.
232      *
233      * <p>The first line is line 1.</p>
234      *
235      * @return An integer representing the line number, or -1
236      *         if none is available.
237      * @see org.xml.sax.Locator#getLineNumber
238      */
239     public int getLineNumber ()
240     {
241         return this.lineNumber;
242     }
243 
244 
245     /**
246      * The column number of the end of the text where the exception occurred.
247      *
248      * <p>The first column in a line is position 1.</p>
249      *
250      * @return An integer representing the column number, or -1
251      *         if none is available.
252      * @see org.xml.sax.Locator#getColumnNumber
253      */
254     public int getColumnNumber ()
255     {
256         return this.columnNumber;
257     }
258 
259     /**
260      * Override toString to provide more detailed error message.
261      *
262      * @return A string representation of this exception.
263      */
264     public String toString() {
265         StringBuilder buf = new StringBuilder(getClass().getName());
266         String message = getLocalizedMessage();
267         if (publicId!=null)    buf.append("publicId: ").append(publicId);
268         if (systemId!=null)    buf.append("; systemId: ").append(systemId);
269         if (lineNumber!=-1)    buf.append("; lineNumber: ").append(lineNumber);
270         if (columnNumber!=-1)  buf.append("; columnNumber: ").append(columnNumber);
271 
272        //append the exception message at the end
273         if (message!=null)     buf.append("; ").append(message);
274         return buf.toString();
275     }
276 
277     //////////////////////////////////////////////////////////////////////
278     // Internal state.
279     //////////////////////////////////////////////////////////////////////
280 
281 
282     /**
283      * @serial The public identifier, or null.
284      * @see #getPublicId
285      */
286     private String publicId;
287 
288 
289     /**
290      * @serial The system identifier, or null.
291      * @see #getSystemId
292      */
293     private String systemId;
294 
295 
296     /**
297      * @serial The line number, or -1.
298      * @see #getLineNumber
299      */
300     private int lineNumber;
301 
302 
303     /**
304      * @serial The column number, or -1.
305      * @see #getColumnNumber
306      */
307     private int columnNumber;
308 
309     // Added serialVersionUID to preserve binary compatibility
310     static final long serialVersionUID = -5651165872476709336L;
311 }
312 
313 // end of SAXParseException.java