Core review request for 6378701 "(enum) Unclear purpose of EnumConstantNotPresentException "

[Lance J. Andersen]

Hi Joe,

The changes are fine and make things clearer.

Regards
Lance

Joseph D. Darcy wrote:
> Hello.
>
> Please review the patch below is clarify the use of certain exception 
> types to address bug 6378701 "(enum) Unclear purpose of 
> EnumConstantNotPresentException."  Five exceptions/errors can be 
> thrown by the methods of the AnnotatedElement interface; those methods 
> are used to retrieve annotations reflectively.  I've added cross 
> references between the AnnotatedElement intefaces and the throwables 
> it may throw.
>
> -Joe
>
> --- 
> old/src/share/classes/java/lang/EnumConstantNotPresentException.java    
> 2009-08-21 00:43:31.000000000 -0700
> +++ 
> new/src/share/classes/java/lang/EnumConstantNotPresentException.java    
> 2009-08-21 00:43:30.000000000 -0700
> @@ -28,8 +28,12 @@
> /**
>  * Thrown when an application tries to access an enum constant by name
>  * and the enum type contains no constant with the specified name.
> + * This exception can be thrown by the {@linkplain
> + * java.lang.reflect.AnnotatedElement API used to read annotations
> + * reflectively}.
>  *
>  * @author  Josh Bloch
> + * @see     java.lang.reflect.AnnotatedElement
>  * @since   1.5
>  */
> public class EnumConstantNotPresentException extends RuntimeException {
> --- old/src/share/classes/java/lang/TypeNotPresentException.java    
> 2009-08-21 00:43:32.000000000 -0700
> +++ new/src/share/classes/java/lang/TypeNotPresentException.java    
> 2009-08-21 00:43:31.000000000 -0700
> @@ -35,8 +35,12 @@
>  * <p>Note that this exception may be used when undefined type variables
>  * are accessed as well as when types (e.g., classes, interfaces or
>  * annotation types) are loaded.
> + * In particular, this exception can be thrown by the {@linkplain
> + * java.lang.reflect.AnnotatedElement API used to read annotations
> + * reflectively}.
>  *
>  * @author  Josh Bloch
> + * @see     java.lang.reflect.AnnotatedElement
>  * @since 1.5
>  */
> public class TypeNotPresentException extends RuntimeException {
> --- 
> old/src/share/classes/java/lang/annotation/AnnotationFormatError.java    
> 2009-08-21 00:43:32.000000000 -0700
> +++ 
> new/src/share/classes/java/lang/annotation/AnnotationFormatError.java    
> 2009-08-21 00:43:32.000000000 -0700
> @@ -28,8 +28,12 @@
> /**
>  * Thrown when the annotation parser attempts to read an annotation
>  * from a class file and determines that the annotation is malformed.
> + * This error can be thrown by the {@linkplain
> + * java.lang.reflect.AnnotatedElement API used to read annotations
> + * reflectively}.
>  *
>  * @author  Josh Bloch
> + * @see     java.lang.reflect.AnnotatedElement
>  * @since   1.5
>  */
> public class AnnotationFormatError extends Error {
> --- 
> old/src/share/classes/java/lang/annotation/AnnotationTypeMismatchException.java    
> 2009-08-21 00:43:33.000000000 -0700
> +++ 
> new/src/share/classes/java/lang/annotation/AnnotationTypeMismatchException.java    
> 2009-08-21 00:43:33.000000000 -0700
> @@ -30,8 +30,12 @@
>  * Thrown to indicate that a program has attempted to access an 
> element of
>  * an annotation whose type has changed after the annotation was compiled
>  * (or serialized).
> + * This exception can be thrown by the {@linkplain
> + * java.lang.reflect.AnnotatedElement API used to read annotations
> + * reflectively}.
>  *
>  * @author  Josh Bloch
> + * @see     java.lang.reflect.AnnotatedElement
>  * @since 1.5
>  */
> public class AnnotationTypeMismatchException extends RuntimeException {
> --- 
> old/src/share/classes/java/lang/annotation/IncompleteAnnotationException.java    
> 2009-08-21 00:43:34.000000000 -0700
> +++ 
> new/src/share/classes/java/lang/annotation/IncompleteAnnotationException.java    
> 2009-08-21 00:43:33.000000000 -0700
> @@ -30,8 +30,12 @@
>  * an annotation type that was added to the annotation type definition 
> after
>  * the annotation was compiled (or serialized).  This exception will 
> not be
>  * thrown if the new element has a default value.
> + * This exception can be thrown by the {@linkplain
> + * java.lang.reflect.AnnotatedElement API used to read annotations
> + * reflectively}.
>  *
>  * @author  Josh Bloch
> + * @see     java.lang.reflect.AnnotatedElement
>  * @since 1.5
>  */
> public class IncompleteAnnotationException extends RuntimeException {
> --- old/src/share/classes/java/lang/reflect/AnnotatedElement.java    
> 2009-08-21 00:43:34.000000000 -0700
> +++ new/src/share/classes/java/lang/reflect/AnnotatedElement.java    
> 2009-08-21 00:43:34.000000000 -0700
> @@ -50,6 +50,11 @@
>  * java.lang.annotation.AnnotationTypeMismatchException} or an
>  * {@link java.lang.annotation.IncompleteAnnotationException}.
>  *
> + * @see java.lang.EnumConstantNotPresentException
> + * @see java.lang.TypeNotPresentException
> + * @see java.lang.annotation.AnnotationFormatError
> + * @see java.lang.annotation.AnnotationTypeMismatchException
> + * @see java.lang.annotation.IncompleteAnnotationException
>  * @since 1.5
>  * @author Josh Bloch
>  */