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