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

[Andrew John Hughes]

2009/8/21 Lance J. Andersen <Lance.Andersen at sun.com>:
> 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
>>  */
>


Likewise; makes things clearer for me.
-- 
Andrew :-)

Free Java Software Engineer
Red Hat, Inc. (http://www.redhat.com)

Support Free Java!
Contribute to GNU Classpath and the OpenJDK
http://www.gnu.org/software/classpath
http://openjdk.java.net

PGP Key: 94EFD9D8 (http://subkeys.pgp.net)
Fingerprint: F8EF F1EA 401E 2E60 15FA  7927 142C 2591 94EF D9D8