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 package java.lang;
27 import java.io.*;
28 import java.util.*;
29
30 /**
31 * The {@code Throwable} class is the superclass of all errors and
32 * exceptions in the Java language. Only objects that are instances of this
33 * class (or one of its subclasses) are thrown by the Java Virtual Machine or
34 * can be thrown by the Java {@code throw} statement. Similarly, only
35 * this class or one of its subclasses can be the argument type in a
36 * {@code catch} clause.
37 *
38 * For the purposes of compile-time checking of exceptions, {@code
39 * Throwable} and any subclass of {@code Throwable} that is not also a
40 * subclass of either {@link RuntimeException} or {@link Error} are
41 * regarded as checked exceptions.
42 *
43 * <p>Instances of two subclasses, {@link java.lang.Error} and
44 * {@link java.lang.Exception}, are conventionally used to indicate
45 * that exceptional situations have occurred. Typically, these instances
46 * are freshly created in the context of the exceptional situation so
47 * as to include relevant information (such as stack trace data).
48 *
49 * <p>A throwable contains a snapshot of the execution stack of its
231
232 /** Message for trying to suppress oneself. */
233 private static final String SELF_SUPPRESSION_MESSAGE = "Self-suppression not permitted";
234
235 /** Caption for labeling causative exception stack traces */
236 private static final String CAUSE_CAPTION = "Caused by: ";
237
238 /** Caption for labeling suppressed exception stack traces */
239 private static final String SUPPRESSED_CAPTION = "Suppressed: ";
240
241 /**
242 * Constructs a new throwable with {@code null} as its detail message.
243 * The cause is not initialized, and may subsequently be initialized by a
244 * call to {@link #initCause}.
245 *
246 * <p>The {@link #fillInStackTrace()} method is called to initialize
247 * the stack trace data in the newly created throwable.
248 */
249 public Throwable() {
250 fillInStackTrace();
251 }
252
253 /**
254 * Constructs a new throwable with the specified detail message. The
255 * cause is not initialized, and may subsequently be initialized by
256 * a call to {@link #initCause}.
257 *
258 * <p>The {@link #fillInStackTrace()} method is called to initialize
259 * the stack trace data in the newly created throwable.
260 *
261 * @param message the detail message. The detail message is saved for
262 * later retrieval by the {@link #getMessage()} method.
263 */
264 public Throwable(String message) {
265 fillInStackTrace();
266 detailMessage = message;
267 }
268
269 /**
270 * Constructs a new throwable with the specified detail message and
271 * cause. <p>Note that the detail message associated with
272 * {@code cause} is <i>not</i> automatically incorporated in
273 * this throwable's detail message.
274 *
275 * <p>The {@link #fillInStackTrace()} method is called to initialize
276 * the stack trace data in the newly created throwable.
277 *
278 * @param message the detail message (which is saved for later retrieval
279 * by the {@link #getMessage()} method).
280 * @param cause the cause (which is saved for later retrieval by the
281 * {@link #getCause()} method). (A {@code null} value is
282 * permitted, and indicates that the cause is nonexistent or
283 * unknown.)
284 * @since 1.4
285 */
286 public Throwable(String message, Throwable cause) {
287 fillInStackTrace();
288 detailMessage = message;
289 this.cause = cause;
290 }
291
292 /**
293 * Constructs a new throwable with the specified cause and a detail
294 * message of {@code (cause==null ? null : cause.toString())} (which
295 * typically contains the class and detail message of {@code cause}).
296 * This constructor is useful for throwables that are little more than
297 * wrappers for other throwables (for example, {@link
298 * java.security.PrivilegedActionException}).
299 *
300 * <p>The {@link #fillInStackTrace()} method is called to initialize
301 * the stack trace data in the newly created throwable.
302 *
303 * @param cause the cause (which is saved for later retrieval by the
304 * {@link #getCause()} method). (A {@code null} value is
305 * permitted, and indicates that the cause is nonexistent or
306 * unknown.)
307 * @since 1.4
308 */
309 public Throwable(Throwable cause) {
310 fillInStackTrace();
311 detailMessage = (cause==null ? null : cause.toString());
312 this.cause = cause;
313 }
314
315 /**
316 * Constructs a new throwable with the specified detail message,
317 * cause, {@linkplain #addSuppressed suppression} enabled or
318 * disabled, and writable stack trace enabled or disabled. If
319 * suppression is disabled, {@link #getSuppressed} for this object
320 * will return a zero-length array and calls to {@link
321 * #addSuppressed} that would otherwise append an exception to the
322 * suppressed list will have no effect. If the writable stack
323 * trace is false, this constructor will not call {@link
324 * #fillInStackTrace()}, a {@code null} will be written to the
325 * {@code stackTrace} field, and subsequent calls to {@code
326 * fillInStackTrace} and {@link
327 * #setStackTrace(StackTraceElement[])} will not set the stack
328 * trace. If the writable stack trace is false, {@link
329 * #getStackTrace} will return a zero length array.
330 *
331 * <p>Note that the other constructors of {@code Throwable} treat
332 * suppression as being enabled and the stack trace as being
348 * @param writableStackTrace whether or not the stack trace should be
349 * writable
350 *
351 * @see OutOfMemoryError
352 * @see NullPointerException
353 * @see ArithmeticException
354 * @since 1.7
355 */
356 protected Throwable(String message, Throwable cause,
357 boolean enableSuppression,
358 boolean writableStackTrace) {
359 if (writableStackTrace) {
360 fillInStackTrace();
361 } else {
362 stackTrace = null;
363 }
364 detailMessage = message;
365 this.cause = cause;
366 if (!enableSuppression)
367 suppressedExceptions = null;
368 }
369
370 /**
371 * Returns the detail message string of this throwable.
372 *
373 * @return the detail message string of this {@code Throwable} instance
374 * (which may be {@code null}).
375 */
376 public String getMessage() {
377 return detailMessage;
378 }
379
380 /**
381 * Creates a localized description of this throwable.
382 * Subclasses may override this method in order to produce a
383 * locale-specific message. For subclasses that do not override this
384 * method, the default implementation returns the same result as
385 * {@code getMessage()}.
386 *
387 * @return The localized description of this throwable.
|
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 package java.lang;
27 import java.io.*;
28 import java.util.*;
29
30 import sun.misc.ThrowableTrace;
31
32 /**
33 * The {@code Throwable} class is the superclass of all errors and
34 * exceptions in the Java language. Only objects that are instances of this
35 * class (or one of its subclasses) are thrown by the Java Virtual Machine or
36 * can be thrown by the Java {@code throw} statement. Similarly, only
37 * this class or one of its subclasses can be the argument type in a
38 * {@code catch} clause.
39 *
40 * For the purposes of compile-time checking of exceptions, {@code
41 * Throwable} and any subclass of {@code Throwable} that is not also a
42 * subclass of either {@link RuntimeException} or {@link Error} are
43 * regarded as checked exceptions.
44 *
45 * <p>Instances of two subclasses, {@link java.lang.Error} and
46 * {@link java.lang.Exception}, are conventionally used to indicate
47 * that exceptional situations have occurred. Typically, these instances
48 * are freshly created in the context of the exceptional situation so
49 * as to include relevant information (such as stack trace data).
50 *
51 * <p>A throwable contains a snapshot of the execution stack of its
233
234 /** Message for trying to suppress oneself. */
235 private static final String SELF_SUPPRESSION_MESSAGE = "Self-suppression not permitted";
236
237 /** Caption for labeling causative exception stack traces */
238 private static final String CAUSE_CAPTION = "Caused by: ";
239
240 /** Caption for labeling suppressed exception stack traces */
241 private static final String SUPPRESSED_CAPTION = "Suppressed: ";
242
243 /**
244 * Constructs a new throwable with {@code null} as its detail message.
245 * The cause is not initialized, and may subsequently be initialized by a
246 * call to {@link #initCause}.
247 *
248 * <p>The {@link #fillInStackTrace()} method is called to initialize
249 * the stack trace data in the newly created throwable.
250 */
251 public Throwable() {
252 fillInStackTrace();
253 ThrowableTrace.traceThrowable(this);
254 }
255
256 /**
257 * Constructs a new throwable with the specified detail message. The
258 * cause is not initialized, and may subsequently be initialized by
259 * a call to {@link #initCause}.
260 *
261 * <p>The {@link #fillInStackTrace()} method is called to initialize
262 * the stack trace data in the newly created throwable.
263 *
264 * @param message the detail message. The detail message is saved for
265 * later retrieval by the {@link #getMessage()} method.
266 */
267 public Throwable(String message) {
268 fillInStackTrace();
269 detailMessage = message;
270 ThrowableTrace.traceThrowable(this);
271 }
272
273 /**
274 * Constructs a new throwable with the specified detail message and
275 * cause. <p>Note that the detail message associated with
276 * {@code cause} is <i>not</i> automatically incorporated in
277 * this throwable's detail message.
278 *
279 * <p>The {@link #fillInStackTrace()} method is called to initialize
280 * the stack trace data in the newly created throwable.
281 *
282 * @param message the detail message (which is saved for later retrieval
283 * by the {@link #getMessage()} method).
284 * @param cause the cause (which is saved for later retrieval by the
285 * {@link #getCause()} method). (A {@code null} value is
286 * permitted, and indicates that the cause is nonexistent or
287 * unknown.)
288 * @since 1.4
289 */
290 public Throwable(String message, Throwable cause) {
291 fillInStackTrace();
292 detailMessage = message;
293 this.cause = cause;
294 ThrowableTrace.traceThrowable(this);
295 }
296
297 /**
298 * Constructs a new throwable with the specified cause and a detail
299 * message of {@code (cause==null ? null : cause.toString())} (which
300 * typically contains the class and detail message of {@code cause}).
301 * This constructor is useful for throwables that are little more than
302 * wrappers for other throwables (for example, {@link
303 * java.security.PrivilegedActionException}).
304 *
305 * <p>The {@link #fillInStackTrace()} method is called to initialize
306 * the stack trace data in the newly created throwable.
307 *
308 * @param cause the cause (which is saved for later retrieval by the
309 * {@link #getCause()} method). (A {@code null} value is
310 * permitted, and indicates that the cause is nonexistent or
311 * unknown.)
312 * @since 1.4
313 */
314 public Throwable(Throwable cause) {
315 fillInStackTrace();
316 detailMessage = (cause==null ? null : cause.toString());
317 this.cause = cause;
318 ThrowableTrace.traceThrowable(this);
319 }
320
321 /**
322 * Constructs a new throwable with the specified detail message,
323 * cause, {@linkplain #addSuppressed suppression} enabled or
324 * disabled, and writable stack trace enabled or disabled. If
325 * suppression is disabled, {@link #getSuppressed} for this object
326 * will return a zero-length array and calls to {@link
327 * #addSuppressed} that would otherwise append an exception to the
328 * suppressed list will have no effect. If the writable stack
329 * trace is false, this constructor will not call {@link
330 * #fillInStackTrace()}, a {@code null} will be written to the
331 * {@code stackTrace} field, and subsequent calls to {@code
332 * fillInStackTrace} and {@link
333 * #setStackTrace(StackTraceElement[])} will not set the stack
334 * trace. If the writable stack trace is false, {@link
335 * #getStackTrace} will return a zero length array.
336 *
337 * <p>Note that the other constructors of {@code Throwable} treat
338 * suppression as being enabled and the stack trace as being
354 * @param writableStackTrace whether or not the stack trace should be
355 * writable
356 *
357 * @see OutOfMemoryError
358 * @see NullPointerException
359 * @see ArithmeticException
360 * @since 1.7
361 */
362 protected Throwable(String message, Throwable cause,
363 boolean enableSuppression,
364 boolean writableStackTrace) {
365 if (writableStackTrace) {
366 fillInStackTrace();
367 } else {
368 stackTrace = null;
369 }
370 detailMessage = message;
371 this.cause = cause;
372 if (!enableSuppression)
373 suppressedExceptions = null;
374 ThrowableTrace.traceThrowable(this);
375 }
376
377 /**
378 * Returns the detail message string of this throwable.
379 *
380 * @return the detail message string of this {@code Throwable} instance
381 * (which may be {@code null}).
382 */
383 public String getMessage() {
384 return detailMessage;
385 }
386
387 /**
388 * Creates a localized description of this throwable.
389 * Subclasses may override this method in order to produce a
390 * locale-specific message. For subclasses that do not override this
391 * method, the default implementation returns the same result as
392 * {@code getMessage()}.
393 *
394 * @return The localized description of this throwable.
|