View Javadoc

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.5 2004/03/19 20:17:54 maartenc Exp $
5   
6   package 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   */
37  public 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      * Returns the identifier for the exception which is being reported.
237      *
238      * @return URI identifying the exception.  SAX standardizes the *
239      * identifiers for errors relating to the specifications that it
240      * relies * on for XML parsing (including <em>XML</em> and *
241      * <em>Namespaces in XML</em>).  * See <a
242      * href="package-summary.html#exceptions">the <em>org.xml.sax</em>
243      * * package summary</a> for more information.
244      *
245      * @since SAX 2.1
246      */
247     public String getExceptionId ()
248     {
249 	return exceptionId;
250     }
251     
252     
253     /***
254      * Assigns the identifier for the exception which is being reported,
255      * if none has yet been assigned.
256      *
257      * @param id URI identifying the exception.  SAX standardizes the
258      * * identifiers for errors relating to the specifications that it
259      * relies * on for XML parsing (including <em>XML</em> and *
260      * <em>Namespaces in XML</em>).  * See <a
261      * href="package-summary.html#exceptions">the <em>org.xml.sax</em>
262      * * package summary</a> for more information.
263      * @exception IllegalStateException If the ID was already assigned.
264      *
265      * @since SAX 2.1
266      */
267     public void setExceptionId (String id)
268     {
269 	if (exceptionId == null)
270 	    exceptionId = id;
271 	else
272 	    throw new IllegalStateException ();
273     }
274     
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 
310     /***
311      * @serial URI identifying the exception, or null
312      * @see #getExceptionId
313      */
314     private String	exceptionId;
315     
316 }
317 
318 // end of SAXParseException.java