From 12d023bd42569b18230e3bbbe3af8dab179a5351 Mon Sep 17 00:00:00 2001 From: darcy Date: Thu, 7 Jan 2010 19:42:43 -0800 Subject: [PATCH] 6915171: Clarify checked/unchecked status of Throwable and its subclasses Reviewed-by: dholmes --- src/share/classes/java/lang/Error.java | 18 +++++++++++------- src/share/classes/java/lang/Exception.java | 16 ++++++++++++---- .../classes/java/lang/RuntimeException.java | 16 +++++++++------- src/share/classes/java/lang/Throwable.java | 6 ++++++ 4 files changed, 38 insertions(+), 18 deletions(-) diff --git a/src/share/classes/java/lang/Error.java b/src/share/classes/java/lang/Error.java index c1ab7a892..a5af32668 100644 --- a/src/share/classes/java/lang/Error.java +++ b/src/share/classes/java/lang/Error.java @@ -26,27 +26,31 @@ package java.lang; /** - * An Error is a subclass of Throwable + * An {@code Error} is a subclass of {@code Throwable} * that indicates serious problems that a reasonable application * should not try to catch. Most such errors are abnormal conditions. - * The ThreadDeath error, though a "normal" condition, - * is also a subclass of Error because most applications + * The {@code ThreadDeath} error, though a "normal" condition, + * is also a subclass of {@code Error} because most applications * should not try to catch it. *

- * A method is not required to declare in its throws - * clause any subclasses of Error that might be thrown + * A method is not required to declare in its {@code throws} + * clause any subclasses of {@code Error} that might be thrown * during the execution of the method but not caught, since these * errors are abnormal conditions that should never occur. * + * That is, {@code Error} and its subclasses are regarded as unchecked + * exceptions for the purposes of compile-time checking of exceptions. + * * @author Frank Yellin * @see java.lang.ThreadDeath + * @jls3 11.2 Compile-Time Checking of Exceptions * @since JDK1.0 */ public class Error extends Throwable { static final long serialVersionUID = 4980196508277280342L; /** - * Constructs a new error with null as its detail message. + * Constructs a new error with {@code null} as its detail message. * The cause is not initialized, and may subsequently be initialized by a * call to {@link #initCause}. */ @@ -69,7 +73,7 @@ public class Error extends Throwable { /** * Constructs a new error with the specified detail message and * cause.

Note that the detail message associated with - * cause is not automatically incorporated in + * {@code cause} is not automatically incorporated in * this error's detail message. * * @param message the detail message (which is saved for later retrieval diff --git a/src/share/classes/java/lang/Exception.java b/src/share/classes/java/lang/Exception.java index 70b99ae9b..bdb1c7d36 100644 --- a/src/share/classes/java/lang/Exception.java +++ b/src/share/classes/java/lang/Exception.java @@ -26,19 +26,27 @@ package java.lang; /** - * The class Exception and its subclasses are a form of - * Throwable that indicates conditions that a reasonable + * The class {@code Exception} and its subclasses are a form of + * {@code Throwable} that indicates conditions that a reasonable * application might want to catch. * + *

The class {@code Exception} and any subclasses that are not also + * subclasses of {@link RuntimeException} are checked + * exceptions. Checked exceptions need to be declared in a + * method or constructor's {@code throws} clause if they can be thrown + * by the execution of the method or constructor and propagate outside + * the method or constructor boundary. + * * @author Frank Yellin * @see java.lang.Error + * @jls3 11.2 Compile-Time Checking of Exceptions * @since JDK1.0 */ public class Exception extends Throwable { static final long serialVersionUID = -3387516993124229948L; /** - * Constructs a new exception with null as its detail message. + * Constructs a new exception with {@code null} as its detail message. * The cause is not initialized, and may subsequently be initialized by a * call to {@link #initCause}. */ @@ -61,7 +69,7 @@ public class Exception extends Throwable { /** * Constructs a new exception with the specified detail message and * cause.

Note that the detail message associated with - * cause is not automatically incorporated in + * {@code cause} is not automatically incorporated in * this exception's detail message. * * @param message the detail message (which is saved for later retrieval diff --git a/src/share/classes/java/lang/RuntimeException.java b/src/share/classes/java/lang/RuntimeException.java index e3378485b..d510e2c58 100644 --- a/src/share/classes/java/lang/RuntimeException.java +++ b/src/share/classes/java/lang/RuntimeException.java @@ -26,22 +26,24 @@ package java.lang; /** - * RuntimeException is the superclass of those + * {@code RuntimeException} is the superclass of those * exceptions that can be thrown during the normal operation of the * Java Virtual Machine. - *

- * A method is not required to declare in its throws - * clause any subclasses of RuntimeException that might - * be thrown during the execution of the method but not caught. * + *

{@code RuntimeException} and its subclasses are unchecked + * exceptions. Unchecked exceptions do not need to be + * declared in a method or constructor's {@code throws} clause if they + * can be thrown by the execution of the method or constructor and + * propagate outside the method or constructor boundary. * * @author Frank Yellin + * @jls3 11.2 Compile-Time Checking of Exceptions * @since JDK1.0 */ public class RuntimeException extends Exception { static final long serialVersionUID = -7034897190745766939L; - /** Constructs a new runtime exception with null as its + /** Constructs a new runtime exception with {@code null} as its * detail message. The cause is not initialized, and may subsequently be * initialized by a call to {@link #initCause}. */ @@ -63,7 +65,7 @@ public class RuntimeException extends Exception { /** * Constructs a new runtime exception with the specified detail message and * cause.

Note that the detail message associated with - * cause is not automatically incorporated in + * {@code cause} is not automatically incorporated in * this runtime exception's detail message. * * @param message the detail message (which is saved for later retrieval diff --git a/src/share/classes/java/lang/Throwable.java b/src/share/classes/java/lang/Throwable.java index c4e75d250..ebc7fe7ce 100644 --- a/src/share/classes/java/lang/Throwable.java +++ b/src/share/classes/java/lang/Throwable.java @@ -34,6 +34,11 @@ import java.io.*; * this class or one of its subclasses can be the argument type in a * catch clause. * + * For the purposes of compile-time checking of exceptions, {@code + * Throwable} and any subclass of {@code Throwable} that is not also a + * subclass of either {@link RuntimeException} or {@link Error} are + * regarded as checked exceptions. + * *

Instances of two subclasses, {@link java.lang.Error} and * {@link java.lang.Exception}, are conventionally used to indicate * that exceptional situations have occurred. Typically, these instances @@ -142,6 +147,7 @@ import java.io.*; * @author unascribed * @author Josh Bloch (Added exception chaining and programmatic access to * stack trace in 1.4.) + * @jls3 11.2 Compile-Time Checking of Exceptions * @since JDK1.0 */ public class Throwable implements Serializable { -- GitLab