ModuleInfo extends AnnotatedElement

[joe.darcy at oracle.com]

Hello.

On 4/20/2010 2:33 PM, Mandy Chung wrote:
> The current API only supports to read annotations of a module when the 
> module has been installed by using the java.lang.reflect.Module API 
> (that extends AnnotatedElement).   There are cases that one would want 
> to read the annotations from module-info while the module is being 
> installed.  For example, a module can include some annotation to 
> specify the installation requirement that can be used to determine if 
> the module installation should continue based on the system 
> configuration.  It is an opportunity to eliminate  transfers of the 
> entire module and its dependencies if not needed.
>
> We need to provide an API to read the annotations from module-info but 
> the module may not be installed or downloaded at all.
>
> One proposal is to extend java.lang.module.ModuleInfo to extend 
> AnnotatedElement:
>
> http://cr.openjdk.java.net/~mchung/jigsaw/annotations/api/java/lang/module/ModuleInfo.html 
>
>
> It will not load any classes referenced by annotations for this 
> ModuleInfo until the getAnnotation or other method specified in the 
> AnnotatedElement interface is called (since those classes might not 
> exist or be found by the class loader).  In other word, this change 
> will not affect the current module loading/resolution.   It will use 
> the current module class loader to find classes to construct the 
> Annotation objects.   If the type of an annotation's element cannot be 
> found,  it will result in a TypeNotPresentException in the current 
> proposed specification.  TypeNotPresentException is an unchecked 
> exception and perhaps it'd be better to throw a checked exception.
>
> Any comment, opinion?
>
> Joe, your feedback would be helpful.

Mandy and I spoke about this issue.

In this situation, I recommend using a type other than the core 
reflection type to model the module, as is already being proposed with 
ModuleInfo.  Additionally, I recommend that ModuleInfo just implement a 
selected subset of the methods of AnnotatedElement, say, 
isAnnotationPresent and getAnnotation, and *not* implement the full 
interface.

This is part of the approach taken by JSR 269 to address a similar 
situation of reading annotations from contexts that are not necessarily 
at runtime after all the relevant classes are loaded.  In JSR 269, types 
are defined to allow annotations to be read fully at arm's length 
(javax.lang.model.element.AnnotationMirror, etc.), but that is very 
tedious to program to so as a knowing violation of certainly reflective 
API design principles, a getAnnotation(Class) method is included too:

http://java.sun.com/javase/6/docs/api/javax/lang/model/element/Element.html#getAnnotation(java.lang.Class)

While this method is "inspired by" the getAnnotation method from 
AnnotatedElement, this version of getAnnotation comes with a caveat:

> /Note:/ This method is unlike others in this and related interfaces. 
> It operates on runtime reflective information --- representations of 
> annotation types currently loaded into the VM --- rather than on the 
> representations defined by and used throughout these interfaces. 
> Consequently, calling methods on the returned annotation object can 
> throw many of the exceptions that can be thrown when calling methods 
> on an annotation object returned by core reflection. This method is 
> intended for callers that are written to operate on a known, fixed set 
> of annotation types. 

Dealing with annotation types whose methods are declared to return Class 
objects is problematic in this mixed environment and should be avoided.

Also note that implementing AnnotatedElement implies certain 
implementation restrictions, such as only returning annotation objects 
that are serializable.

-Joe