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 a general SAX 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 class can contain basic error or warning information from
016: * either the XML parser or the application: a parser writer or
017: * application writer can subclass it to provide additional
018: * functionality. SAX handlers may throw this exception or
019: * any exception subclassed from it.</p>
020: *
021: * <p>If the application needs to pass through other types of
022: * exceptions, it must wrap those exceptions in a SAXException
023: * or an exception derived from a SAXException.</p>
024: *
025: * <p>If the parser or application needs to include information about a
026: * specific location in an XML document, it should use the
027: * {@link org.xml.sax.SAXParseException SAXParseException} subclass.</p>
028: *
029: * @since SAX 1.0
030: * @author David Megginson,
031: * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
032: * @version 2.0
033: * @see org.xml.sax.SAXParseException
034: */
035: public class SAXException extends Exception {
036:
037: /**
038: * Create a new SAXException.
039: *
040: * @param message The error or warning message.
041: * @see org.xml.sax.Parser#setLocale
042: */
043: public SAXException(String message) {
044: super (message);
045: this .exception = null;
046: }
047:
048: /**
049: * Create a new SAXException wrapping an existing exception.
050: *
051: * <p>The existing exception will be embedded in the new
052: * one, and its message will become the default message for
053: * the SAXException.</p>
054: *
055: * @param e The exception to be wrapped in a SAXException.
056: */
057: public SAXException(Exception e) {
058: super ();
059: this .exception = e;
060: }
061:
062: /**
063: * Create a new SAXException from an existing exception.
064: *
065: * <p>The existing exception will be embedded in the new
066: * one, but the new exception will have its own message.</p>
067: *
068: * @param message The detail message.
069: * @param e The exception to be wrapped in a SAXException.
070: * @see org.xml.sax.Parser#setLocale
071: */
072: public SAXException(String message, Exception e) {
073: super (message);
074: this .exception = e;
075: }
076:
077: /**
078: * Return a detail message for this exception.
079: *
080: * <p>If there is an embedded exception, and if the SAXException
081: * has no detail message of its own, this method will return
082: * the detail message from the embedded exception.</p>
083: *
084: * @return The error or warning message.
085: * @see org.xml.sax.Parser#setLocale
086: */
087: public String getMessage() {
088: String message = super .getMessage();
089:
090: if (message == null && exception != null) {
091: return exception.getMessage();
092: } else {
093: return message;
094: }
095: }
096:
097: /**
098: * Return the embedded exception, if any.
099: *
100: * @return The embedded exception, or null if there is none.
101: */
102: public Exception getException() {
103: return exception;
104: }
105:
106: /**
107: * Override toString to pick up any embedded exception.
108: *
109: * @return A string representation of this exception.
110: */
111: public String toString() {
112: if (exception != null) {
113: return exception.toString();
114: } else {
115: return super .toString();
116: }
117: }
118:
119: //////////////////////////////////////////////////////////////////////
120: // Internal state.
121: //////////////////////////////////////////////////////////////////////
122:
123: /**
124: * @serial The embedded exception if tunnelling, or null.
125: */
126: private Exception exception;
127:
128: }
129:
130: // end of SAXException.java
|