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: SAXException.java,v 1.7 2002/01/30 21:13:48 dbrownell Exp $
      5 
      6 package org.xml.sax;
      7 
      8 /**
      9  * Encapsulate a general SAX 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 class can contain basic error or warning information from
     19  * either the XML parser or the application: a parser writer or
     20  * application writer can subclass it to provide additional
     21  * functionality.  SAX handlers may throw this exception or
     22  * any exception subclassed from it.</p>
     23  *
     24  * <p>If the application needs to pass through other types of
     25  * exceptions, it must wrap those exceptions in a SAXException
     26  * or an exception derived from a SAXException.</p>
     27  *
     28  * <p>If the parser or application needs to include information about a
     29  * specific location in an XML document, it should use the
     30  * {@link org.xml.sax.SAXParseException SAXParseException} subclass.</p>
     31  *
     32  * @since SAX 1.0
     33  * @author David Megginson
     34  * @version 2.0.1 (sax2r2)
     35  * @see org.xml.sax.SAXParseException
     36  */
     37 public class SAXException extends Exception {
     38 
     39 
     40     /**
     41      * Create a new SAXException.
     42      */
     43     public SAXException ()
     44     {
     45     this.exception = null;
     46     }
     47 
     48 
     49     /**
     50      * Create a new SAXException.
     51      *
     52      * @param message The error or warning message.
     53      */
     54     public SAXException (String message) {
     55     super(message);
     56     this.exception = null;
     57     }
     58 
     59 
     60     /**
     61      * Create a new SAXException wrapping an existing exception.
     62      *
     63      * <p>The existing exception will be embedded in the new
     64      * one, and its message will become the default message for
     65      * the SAXException.</p>
     66      *
     67      * @param e The exception to be wrapped in a SAXException.
     68      */
     69     public SAXException (Exception e)
     70     {
     71     this.exception = e;
     72     }
     73 
     74 
     75     /**
     76      * Create a new SAXException from an existing exception.
     77      *
     78      * <p>The existing exception will be embedded in the new
     79      * one, but the new exception will have its own message.</p>
     80      *
     81      * @param message The detail message.
     82      * @param e The exception to be wrapped in a SAXException.
     83      */
     84     public SAXException (String message, Exception e)
     85     {
     86     super(message);
     87     this.exception = e;
     88     }
     89 
     90 
     91     /**
     92      * Return a detail message for this exception.
     93      *
     94      * <p>If there is an embedded exception, and if the SAXException
     95      * has no detail message of its own, this method will return
     96      * the detail message from the embedded exception.</p>
     97      *
     98      * @return The error or warning message.
     99      */
    100     public String getMessage ()
    101     {
    102     String message = super.getMessage();
    103 
    104     if (message == null && exception != null) {
    105         return exception.getMessage();
    106     } else {
    107         return message;
    108     }
    109     }
    110 
    111 
    112     /**
    113      * Return the embedded exception, if any.
    114      *
    115      * @return The embedded exception, or null if there is none.
    116      */
    117     public Exception getException ()
    118     {
    119     return exception;
    120     }
    121 
    122 
    123     /**
    124      * Override toString to pick up any embedded exception.
    125      *
    126      * @return A string representation of this exception.
    127      */
    128     public String toString ()
    129     {
    130     if (exception != null) {
    131         return exception.toString();
    132     } else {
    133         return super.toString();
    134     }
    135     }
    136 
    137 
    138 
    139     //////////////////////////////////////////////////////////////////////
    141     // Internal state.
    142     //////////////////////////////////////////////////////////////////////
    143 
    144 
    145     /**
    146      * @serial The embedded exception if tunnelling, or null.
    147      */
    148     private Exception exception;
    149 
    150 }
    151 
    152 // end of SAXException.java
    153