001: // SAX exception class.
002: // No warranty; no copyright -- use this as you will.
003: // $Id$
004:
005: package org.xml.sax;
006:
007: /**
008: * Encapsulate an XML parse error or warning.
009: *
010: * <blockquote>
011: * <em>This module, both source code and documentation, is in the
012: * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
013: * </blockquote>
014: *
015: * <p>This exception will include information for locating the error
016: * in the original XML document. Note that although the application
017: * will receive a SAXParseException as the argument to the handlers
018: * in the {@link org.xml.sax.ErrorHandler ErrorHandler} interface,
019: * the application is not actually required to throw the exception;
020: * instead, it can simply read the information in it and take a
021: * different action.</p>
022: *
023: * <p>Since this exception is a subclass of {@link org.xml.sax.SAXException
024: * SAXException}, it inherits the ability to wrap another exception.</p>
025: *
026: * @since SAX 1.0
027: * @author David Megginson,
028: * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
029: * @version 2.0
030: * @see org.xml.sax.SAXException
031: * @see org.xml.sax.Locator
032: * @see org.xml.sax.ErrorHandler
033: */
034: public class SAXParseException extends SAXException {
035:
036: //////////////////////////////////////////////////////////////////////
037: // Constructors.
038: //////////////////////////////////////////////////////////////////////
039:
040: /**
041: * Create a new SAXParseException from a message and a Locator.
042: *
043: * <p>This constructor is especially useful when an application is
044: * creating its own exception from within a {@link org.xml.sax.ContentHandler
045: * ContentHandler} callback.</p>
046: *
047: * @param message The error or warning message.
048: * @param locator The locator object for the error or warning (may be
049: * null).
050: * @see org.xml.sax.Locator
051: * @see org.xml.sax.Parser#setLocale
052: */
053: public SAXParseException(String message, Locator locator) {
054: super (message);
055: if (locator != null) {
056: init(locator.getPublicId(), locator.getSystemId(), locator
057: .getLineNumber(), locator.getColumnNumber());
058: } else {
059: init(null, null, -1, -1);
060: }
061: }
062:
063: /**
064: * Wrap an existing exception in a SAXParseException.
065: *
066: * <p>This constructor is especially useful when an application is
067: * creating its own exception from within a {@link org.xml.sax.ContentHandler
068: * ContentHandler} callback, and needs to wrap an existing exception that is not a
069: * subclass of {@link org.xml.sax.SAXException SAXException}.</p>
070: *
071: * @param message The error or warning message, or null to
072: * use the message from the embedded exception.
073: * @param locator The locator object for the error or warning (may be
074: * null).
075: * @param e Any exception.
076: * @see org.xml.sax.Locator
077: * @see org.xml.sax.Parser#setLocale
078: */
079: public SAXParseException(String message, Locator locator,
080: Exception e) {
081: super (message, e);
082: if (locator != null) {
083: init(locator.getPublicId(), locator.getSystemId(), locator
084: .getLineNumber(), locator.getColumnNumber());
085: } else {
086: init(null, null, -1, -1);
087: }
088: }
089:
090: /**
091: * Create a new SAXParseException.
092: *
093: * <p>This constructor is most useful for parser writers.</p>
094: *
095: * <p>If the system identifier is a URL, the parser must resolve it
096: * fully before creating the exception.</p>
097: *
098: * @param message The error or warning message.
099: * @param publicId The public identifer of the entity that generated
100: * the error or warning.
101: * @param systemId The system identifer of the entity that generated
102: * the error or warning.
103: * @param lineNumber The line number of the end of the text that
104: * caused the error or warning.
105: * @param columnNumber The column number of the end of the text that
106: * cause the error or warning.
107: * @see org.xml.sax.Parser#setLocale
108: */
109: public SAXParseException(String message, String publicId,
110: String systemId, int lineNumber, int columnNumber) {
111: super (message);
112: init(publicId, systemId, lineNumber, columnNumber);
113: }
114:
115: /**
116: * Create a new SAXParseException with an embedded exception.
117: *
118: * <p>This constructor is most useful for parser writers who
119: * need to wrap an exception that is not a subclass of
120: * {@link org.xml.sax.SAXException SAXException}.</p>
121: *
122: * <p>If the system identifier is a URL, the parser must resolve it
123: * fully before creating the exception.</p>
124: *
125: * @param message The error or warning message, or null to use
126: * the message from the embedded exception.
127: * @param publicId The public identifer of the entity that generated
128: * the error or warning.
129: * @param systemId The system identifer of the entity that generated
130: * the error or warning.
131: * @param lineNumber The line number of the end of the text that
132: * caused the error or warning.
133: * @param columnNumber The column number of the end of the text that
134: * cause the error or warning.
135: * @param e Another exception to embed in this one.
136: * @see org.xml.sax.Parser#setLocale
137: */
138: public SAXParseException(String message, String publicId,
139: String systemId, int lineNumber, int columnNumber,
140: Exception e) {
141: super (message, e);
142: init(publicId, systemId, lineNumber, columnNumber);
143: }
144:
145: /**
146: * Internal initialization method.
147: *
148: * @param publicId The public identifier of the entity which generated the exception,
149: * or null.
150: * @param systemId The system identifier of the entity which generated the exception,
151: * or null.
152: * @param lineNumber The line number of the error, or -1.
153: * @param columnNumber The column number of the error, or -1.
154: */
155: private void init(String publicId, String systemId, int lineNumber,
156: int columnNumber) {
157: this .publicId = publicId;
158: this .systemId = systemId;
159: this .lineNumber = lineNumber;
160: this .columnNumber = columnNumber;
161: }
162:
163: /**
164: * Get the public identifier of the entity where the exception occurred.
165: *
166: * @return A string containing the public identifier, or null
167: * if none is available.
168: * @see org.xml.sax.Locator#getPublicId
169: */
170: public String getPublicId() {
171: return this .publicId;
172: }
173:
174: /**
175: * Get the system identifier of the entity where the exception occurred.
176: *
177: * <p>If the system identifier is a URL, it will be resolved
178: * fully.</p>
179: *
180: * @return A string containing the system identifier, or null
181: * if none is available.
182: * @see org.xml.sax.Locator#getSystemId
183: */
184: public String getSystemId() {
185: return this .systemId;
186: }
187:
188: /**
189: * The line number of the end of the text where the exception occurred.
190: *
191: * @return An integer representing the line number, or -1
192: * if none is available.
193: * @see org.xml.sax.Locator#getLineNumber
194: */
195: public int getLineNumber() {
196: return this .lineNumber;
197: }
198:
199: /**
200: * The column number of the end of the text where the exception occurred.
201: *
202: * <p>The first column in a line is position 1.</p>
203: *
204: * @return An integer representing the column number, or -1
205: * if none is available.
206: * @see org.xml.sax.Locator#getColumnNumber
207: */
208: public int getColumnNumber() {
209: return this .columnNumber;
210: }
211:
212: //////////////////////////////////////////////////////////////////////
213: // Internal state.
214: //////////////////////////////////////////////////////////////////////
215:
216: /**
217: * @serial The public identifier, or null.
218: * @see #getPublicId
219: */
220: private String publicId;
221:
222: /**
223: * @serial The system identifier, or null.
224: * @see #getSystemId
225: */
226: private String systemId;
227:
228: /**
229: * @serial The line number, or -1.
230: * @see #getLineNumber
231: */
232: private int lineNumber;
233:
234: /**
235: * @serial The column number, or -1.
236: * @see #getColumnNumber
237: */
238: private int columnNumber;
239:
240: }
241:
242: // end of SAXParseException.java
|