Code review request for checked/unchecked exception clarifications
David Holmes - Sun Microsystems
David.Holmes at Sun.COM
Fri Jan 8 03:09:29 UTC 2010
Hi Joe,
This looks fine to me.
One minor consistency nit, sometimes you refer to "subclasses of" and
sometimes "subclass of" eg:
+ * <p>The class {@code Exception} and any subclasses that are not also
+ * subclasses of {@link RuntimeException} are <em>checked
+ * exceptions</em>.
+ * 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.
For consistency you could use the same wording for Exception as you do
for Throwable.
Cheers,
David
Joe Darcy said the following on 01/08/10 12:41:
> Hello.
>
> Please review the patch below to clarify which throwables are regarded
> as checked and unchecked exceptions.
>
> Thanks,
>
> -Joe
>
> --- old/src/share/classes/java/lang/Error.java 2010-01-07
> 18:35:40.000000000 -0800
> +++ new/src/share/classes/java/lang/Error.java 2010-01-07
> 18:35:40.000000000 -0800
> @@ -26,27 +26,31 @@
> package java.lang;
>
> /**
> - * An <code>Error</code> is a subclass of <code>Throwable</code>
> + * 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 <code>ThreadDeath</code> error, though a "normal" condition,
> - * is also a subclass of <code>Error</code> 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.
> * <p>
> - * A method is not required to declare in its <code>throws</code>
> - * clause any subclasses of <code>Error</code> 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 <code>null</code> 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 @@
> /**
> * Constructs a new error with the specified detail message and
> * cause. <p>Note that the detail message associated with
> - * <code>cause</code> is <i>not</i> automatically incorporated in
> + * {@code cause} is <i>not</i> automatically incorporated in
> * this error's detail message.
> *
> * @param message the detail message (which is saved for later
> retrieval
> --- old/src/share/classes/java/lang/Exception.java 2010-01-07
> 18:35:41.000000000 -0800
> +++ new/src/share/classes/java/lang/Exception.java 2010-01-07
> 18:35:41.000000000 -0800
> @@ -26,19 +26,27 @@
> package java.lang;
>
> /**
> - * The class <code>Exception</code> and its subclasses are a form of
> - * <code>Throwable</code> 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.
> *
> + * <p>The class {@code Exception} and any subclasses that are not also
> + * subclasses of {@link RuntimeException} are <em>checked
> + * exceptions</em>. 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 <code>null</code> 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 @@
> /**
> * Constructs a new exception with the specified detail message and
> * cause. <p>Note that the detail message associated with
> - * <code>cause</code> is <i>not</i> automatically incorporated in
> + * {@code cause} is <i>not</i> automatically incorporated in
> * this exception's detail message.
> *
> * @param message the detail message (which is saved for later
> retrieval
> --- old/src/share/classes/java/lang/RuntimeException.java 2010-01-07
> 18:35:42.000000000 -0800
> +++ new/src/share/classes/java/lang/RuntimeException.java 2010-01-07
> 18:35:42.000000000 -0800
> @@ -26,22 +26,24 @@
> package java.lang;
>
> /**
> - * <code>RuntimeException</code> 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.
> - * <p>
> - * A method is not required to declare in its <code>throws</code>
> - * clause any subclasses of <code>RuntimeException</code> that might
> - * be thrown during the execution of the method but not caught.
> *
> + * <p>{@code RuntimeException} and its subclasses are <em>unchecked
> + * exceptions</em>. Unchecked exceptions do <em>not</em> 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 <code>null</code> 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 @@
> /**
> * Constructs a new runtime exception with the specified detail
> message and
> * cause. <p>Note that the detail message associated with
> - * <code>cause</code> is <i>not</i> automatically incorporated in
> + * {@code cause} is <i>not</i> automatically incorporated in
> * this runtime exception's detail message.
> *
> * @param message the detail message (which is saved for later
> retrieval
> --- old/src/share/classes/java/lang/Throwable.java 2010-01-07
> 18:35:43.000000000 -0800
> +++ new/src/share/classes/java/lang/Throwable.java 2010-01-07
> 18:35:43.000000000 -0800
> @@ -34,6 +34,11 @@
> * this class or one of its subclasses can be the argument type in a
> * <code>catch</code> 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.
> + *
> * <p>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 @@
> * @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 {
More information about the core-libs-dev
mailing list