1 /*
2 * Copyright (c) 2000, 2018, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 // SAX exception class.
27 // http://www.saxproject.org
28 // No warranty; no copyright -- use this as you will.
29 // $Id: SAXException.java,v 1.3 2004/11/03 22:55:32 jsuttor Exp $
30
31 package org.xml.sax;
32
33 import java.io.IOException;
34 import java.io.ObjectInputStream;
35 import java.io.ObjectOutputStream;
36 import java.io.ObjectStreamField;
37
38 /**
39 * Encapsulate a general SAX error or warning.
40 *
41 * <blockquote>
42 * <em>This module, both source code and documentation, is in the
43 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
44 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
45 * for further information.
46 * </blockquote>
47 *
48 * <p>This class can contain basic error or warning information from
49 * either the XML parser or the application: a parser writer or
50 * application writer can subclass it to provide additional
51 * functionality. SAX handlers may throw this exception or
52 * any exception subclassed from it.</p>
53 *
54 * <p>If the application needs to pass through other types of
55 * exceptions, it must wrap those exceptions in a SAXException
56 * or an exception derived from a SAXException.</p>
57 *
58 * <p>If the parser or application needs to include information about a
59 * specific location in an XML document, it should use the
60 * {@link org.xml.sax.SAXParseException SAXParseException} subclass.</p>
61 *
62 * @since 1.4, SAX 1.0
63 * @author David Megginson
64 * @version 2.0.1 (sax2r2)
65 * @see org.xml.sax.SAXParseException
66 */
67 public class SAXException extends Exception {
68
69
70 /**
71 * Create a new SAXException.
72 */
73 public SAXException ()
74 {
75 super();
76 }
77
78
79 /**
80 * Create a new SAXException.
81 *
82 * @param message The error or warning message.
83 */
84 public SAXException (String message) {
85 super(message);
86 }
87
88
89 /**
90 * Create a new SAXException wrapping an existing exception.
91 *
92 * <p>The existing exception will be embedded in the new
93 * one, and its message will become the default message for
94 * the SAXException.</p>
95 *
96 * @param e The exception to be wrapped in a SAXException.
97 */
98 public SAXException (Exception e)
99 {
100 super(e);
101 }
102
103
104 /**
105 * Create a new SAXException from an existing exception.
106 *
107 * <p>The existing exception will be embedded in the new
108 * one, but the new exception will have its own message.</p>
109 *
110 * @param message The detail message.
111 * @param e The exception to be wrapped in a SAXException.
112 */
113 public SAXException (String message, Exception e)
114 {
115 super(message, e);
116 }
117
118
119 /**
120 * Return a detail message for this exception.
121 *
122 * <p>If there is an embedded exception, and if the SAXException
123 * has no detail message of its own, this method will return
124 * the detail message from the embedded exception.</p>
125 *
126 * @return The error or warning message.
127 */
128 public String getMessage ()
129 {
130 String message = super.getMessage();
131 Throwable cause = super.getCause();
132
133 if (message == null && cause != null) {
134 return cause.getMessage();
135 } else {
136 return message;
137 }
138 }
139
140 /**
141 * Return the embedded exception, if any.
142 *
143 * @return The embedded exception, or null if there is none.
144 */
145 public Exception getException ()
146 {
147 Throwable cause = super.getCause();
148 if (Exception.class.isInstance(cause)) {
149 return (Exception) cause;
150 } else {
151 return null;
152 }
153 }
154
155 /**
156 * Return the cause of the exception
157 *
158 * @return Return the cause of the exception
159 */
160 public Throwable getCause() {
161 return super.getCause();
162 }
163
164 /**
165 * Override toString to pick up any embedded exception.
166 *
167 * @return A string representation of this exception.
168 */
169 public String toString ()
170 {
171 Throwable exception = getCause();
172 if (exception != null) {
173 return super.toString() + "\n" + exception.toString();
174 } else {
175 return super.toString();
176 }
177 }
178
179
180
181 //////////////////////////////////////////////////////////////////////
182 // Internal state.
183 //////////////////////////////////////////////////////////////////////
184
185 private static final ObjectStreamField[] serialPersistentFields = {
186 new ObjectStreamField( "exception", Exception.class )
187 };
188
189 /**
190 * Writes "exception" field to the stream.
191 *
192 * @param out stream used for serialization.
193 * @throws IOException thrown by <code>ObjectOutputStream</code>
194 *
195 */
196 private void writeObject(ObjectOutputStream out)
197 throws IOException
198 {
199 ObjectOutputStream.PutField fields = out.putFields();
200 fields.put("exception", getException());
201 out.writeFields();
202 }
203
204 /**
205 * Reads the "exception" field from the stream.
206 * And initializes the "exception" if it wasn't
207 * done before.
208 *
209 * @param in stream used for deserialization
210 * @throws IOException thrown by <code>ObjectInputStream</code>
211 * @throws ClassNotFoundException thrown by <code>ObjectInputStream</code>
212 */
213 private void readObject(ObjectInputStream in)
214 throws IOException, ClassNotFoundException
215 {
216 ObjectInputStream.GetField fields = in.readFields();
217 Exception exception = (Exception) fields.get("exception", null);
218 Throwable superCause = super.getCause();
219
220 // if super.getCause() and 'exception' fields present then always use
221 // getCause() value. Otherwise, use 'exception' to initialize cause
222 if (superCause == null && exception != null) {
223 initCause(exception);
224 }
225 }
226
227 // Added serialVersionUID to preserve binary compatibility
228 static final long serialVersionUID = 583241635256073760L;
229 }
230
231 // end of SAXException.java