001// SAX exception class. 002// No warranty; no copyright -- use this as you will. 003// $Id: SAXException.java,v 1.1 2001/03/05 21:40:06 jstrachan Exp $ 004 005package 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 */ 035public class SAXException extends Exception { 036 037 038 /** 039 * Create a new SAXException. 040 * 041 * @param message The error or warning message. 042 * @see org.xml.sax.Parser#setLocale 043 */ 044 public SAXException (String message) { 045 super(message); 046 this.exception = null; 047 } 048 049 050 /** 051 * Create a new SAXException wrapping an existing exception. 052 * 053 * <p>The existing exception will be embedded in the new 054 * one, and its message will become the default message for 055 * the SAXException.</p> 056 * 057 * @param e The exception to be wrapped in a SAXException. 058 */ 059 public SAXException (Exception e) 060 { 061 super(); 062 this.exception = e; 063 } 064 065 066 /** 067 * Create a new SAXException from an existing exception. 068 * 069 * <p>The existing exception will be embedded in the new 070 * one, but the new exception will have its own message.</p> 071 * 072 * @param message The detail message. 073 * @param e The exception to be wrapped in a SAXException. 074 * @see org.xml.sax.Parser#setLocale 075 */ 076 public SAXException (String message, Exception e) 077 { 078 super(message); 079 this.exception = e; 080 } 081 082 083 /** 084 * Return a detail message for this exception. 085 * 086 * <p>If there is an embedded exception, and if the SAXException 087 * has no detail message of its own, this method will return 088 * the detail message from the embedded exception.</p> 089 * 090 * @return The error or warning message. 091 * @see org.xml.sax.Parser#setLocale 092 */ 093 public String getMessage () 094 { 095 String message = super.getMessage(); 096 097 if (message == null && exception != null) { 098 return exception.getMessage(); 099 } else { 100 return message; 101 } 102 } 103 104 105 /** 106 * Return the embedded exception, if any. 107 * 108 * @return The embedded exception, or null if there is none. 109 */ 110 public Exception getException () 111 { 112 return exception; 113 } 114 115 116 /** 117 * Override toString to pick up any embedded exception. 118 * 119 * @return A string representation of this exception. 120 */ 121 public String toString () 122 { 123 if (exception != null) { 124 return exception.toString(); 125 } else { 126 return super.toString(); 127 } 128 } 129 130 131 132 ////////////////////////////////////////////////////////////////////// 133 // Internal state. 134 ////////////////////////////////////////////////////////////////////// 135 136 137 /** 138 * @serial The embedded exception if tunnelling, or null. 139 */ 140 private Exception exception; 141 142} 143 144// end of SAXException.java