Home | History | Annotate | Download | only in sax 
      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.11 2004/04/21 13:05:02 dmegginson 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     //////////////////////////////////////////////////////////////////////
     42     // Constructors.
     43     //////////////////////////////////////////////////////////////////////
     44 
     45 
     46     /**
     47      * Create a new SAXParseException from a message and a Locator.
     48      *
     49      * <p>This constructor is especially useful when an application is
     50      * creating its own exception from within a {@link org.xml.sax.ContentHandler
     51      * ContentHandler} callback.</p>
     52      *
     53      * @param message The error or warning message.
     54      * @param locator The locator object for the error or warning (may be
     55      *        null).
     56      * @see org.xml.sax.Locator
     57      */
     58     public SAXParseException (String message, Locator locator) {
     59     super(message);
     60     if (locator != null) {
     61         init(locator.getPublicId(), locator.getSystemId(),
     62          locator.getLineNumber(), locator.getColumnNumber());
     63     } else {
     64         init(null, null, -1, -1);
     65     }
     66     }
     67 
     68 
     69     /**
     70      * Wrap an existing exception in a SAXParseException.
     71      *
     72      * <p>This constructor is especially useful when an application is
     73      * creating its own exception from within a {@link org.xml.sax.ContentHandler
     74      * ContentHandler} callback, and needs to wrap an existing exception that is not a
     75      * subclass of {@link org.xml.sax.SAXException SAXException}.</p>
     76      *
     77      * @param message The error or warning message, or null to
     78      *                use the message from the embedded exception.
     79      * @param locator The locator object for the error or warning (may be
     80      *        null).
     81      * @param e Any exception.
     82      * @see org.xml.sax.Locator
     83      */
     84     public SAXParseException (String message, Locator locator,
     85                   Exception e) {
     86     super(message, e);
     87     if (locator != null) {
     88         init(locator.getPublicId(), locator.getSystemId(),
     89          locator.getLineNumber(), locator.getColumnNumber());
     90     } else {
     91         init(null, null, -1, -1);
     92     }
     93     }
     94 
     95 
     96     /**
     97      * Create a new SAXParseException.
     98      *
     99      * <p>This constructor is most useful for parser writers.</p>
    100      *
    101      * <p>All parameters except the message are as if
    102      * they were provided by a {@link Locator}.  For example, if the
    103      * system identifier is a URL (including relative filename), the
    104      * caller must resolve it fully before creating the exception.</p>
    105      *
    106      *
    107      * @param message The error or warning message.
    108      * @param publicId The public identifier of the entity that generated
    109      *                 the error or warning.
    110      * @param systemId The system identifier of the entity that generated
    111      *                 the error or warning.
    112      * @param lineNumber The line number of the end of the text that
    113      *                   caused the error or warning.
    114      * @param columnNumber The column number of the end of the text that
    115      *                     cause the error or warning.
    116      */
    117     public SAXParseException (String message, String publicId, String systemId,
    118                   int lineNumber, int columnNumber)
    119     {
    120     super(message);
    121     init(publicId, systemId, lineNumber, columnNumber);
    122     }
    123 
    124 
    125     /**
    126      * Create a new SAXParseException with an embedded exception.
    127      *
    128      * <p>This constructor is most useful for parser writers who
    129      * need to wrap an exception that is not a subclass of
    130      * {@link org.xml.sax.SAXException SAXException}.</p>
    131      *
    132      * <p>All parameters except the message and exception are as if
    133      * they were provided by a {@link Locator}.  For example, if the
    134      * system identifier is a URL (including relative filename), the
    135      * caller must resolve it fully before creating the exception.</p>
    136      *
    137      * @param message The error or warning message, or null to use
    138      *                the message from the embedded exception.
    139      * @param publicId The public identifier of the entity that generated
    140      *                 the error or warning.
    141      * @param systemId The system identifier of the entity that generated
    142      *                 the error or warning.
    143      * @param lineNumber The line number of the end of the text that
    144      *                   caused the error or warning.
    145      * @param columnNumber The column number of the end of the text that
    146      *                     cause the error or warning.
    147      * @param e Another exception to embed in this one.
    148      */
    149     public SAXParseException (String message, String publicId, String systemId,
    150                   int lineNumber, int columnNumber, Exception e)
    151     {
    152     super(message, e);
    153     init(publicId, systemId, lineNumber, columnNumber);
    154     }
    155 
    156 
    157     /**
    158      * Internal initialization method.
    159      *
    160      * @param publicId The public identifier of the entity which generated the exception,
    161      *        or null.
    162      * @param systemId The system identifier of the entity which generated the exception,
    163      *        or null.
    164      * @param lineNumber The line number of the error, or -1.
    165      * @param columnNumber The column number of the error, or -1.
    166      */
    167     private void init (String publicId, String systemId,
    168                int lineNumber, int columnNumber)
    169     {
    170     this.publicId = publicId;
    171     this.systemId = systemId;
    172     this.lineNumber = lineNumber;
    173     this.columnNumber = columnNumber;
    174     }
    175 
    176 
    177     /**
    178      * Get the public identifier of the entity where the exception occurred.
    179      *
    180      * @return A string containing the public identifier, or null
    181      *         if none is available.
    182      * @see org.xml.sax.Locator#getPublicId
    183      */
    184     public String getPublicId ()
    185     {
    186     return this.publicId;
    187     }
    188 
    189 
    190     /**
    191      * Get the system identifier of the entity where the exception occurred.
    192      *
    193      * <p>If the system identifier is a URL, it will have been resolved
    194      * fully.</p>
    195      *
    196      * @return A string containing the system identifier, or null
    197      *         if none is available.
    198      * @see org.xml.sax.Locator#getSystemId
    199      */
    200     public String getSystemId ()
    201     {
    202     return this.systemId;
    203     }
    204 
    205 
    206     /**
    207      * The line number of the end of the text where the exception occurred.
    208      *
    209      * <p>The first line is line 1.</p>
    210      *
    211      * @return An integer representing the line number, or -1
    212      *         if none is available.
    213      * @see org.xml.sax.Locator#getLineNumber
    214      */
    215     public int getLineNumber ()
    216     {
    217     return this.lineNumber;
    218     }
    219 
    220 
    221     /**
    222      * The column number of the end of the text where the exception occurred.
    223      *
    224      * <p>The first column in a line is position 1.</p>
    225      *
    226      * @return An integer representing the column number, or -1
    227      *         if none is available.
    228      * @see org.xml.sax.Locator#getColumnNumber
    229      */
    230     public int getColumnNumber ()
    231     {
    232     return this.columnNumber;
    233     }
    234 
    235 
    236     //////////////////////////////////////////////////////////////////////
    238     // Internal state.
    239     //////////////////////////////////////////////////////////////////////
    240 
    241 
    242     /**
    243      * @serial The public identifier, or null.
    244      * @see #getPublicId
    245      */
    246     private String publicId;
    247 
    248 
    249     /**
    250      * @serial The system identifier, or null.
    251      * @see #getSystemId
    252      */
    253     private String systemId;
    254 
    255 
    256     /**
    257      * @serial The line number, or -1.
    258      * @see #getLineNumber
    259      */
    260     private int lineNumber;
    261 
    262 
    263     /**
    264      * @serial The column number, or -1.
    265      * @see #getColumnNumber
    266      */
    267     private int columnNumber;
    268 
    269 }
    270 
    271 // end of SAXParseException.java
    272