1
2
3
4
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
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
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