[jsr294-modularity-eg] Updated API document

[Bryan Atsatt]

How are the directives in a module-info.class made available?

How does a compiler validate a module compilation unit?

How does a compiler resolve dependencies in a module compilation unit?

// Bryan

Alex Buckley wrote:
> I've updated the API doc based on feedback. The major difference from 
> Bryan's is in how annotations are represented; there is commentary in 
> the HTML to explain why the API is the way it is.
>
> Alex
>
> ------------------------------------------------------------------------
>
>
>   API changes for Modules
>
> Module-private access control is governed by /runtime modules/. User 
> code is responsible for generating objects that act as runtime 
> modules. See |java.lang.RuntimeModule|. A class is associated with a 
> |j.l.RuntimeModule| when the class is defined. (No skipping ahead to 
> |defineClass| please.)
>
> Module-level annotations reside in a ClassFile that contains a module 
> declaration. User code is responsible for finding such a ClassFile. 
> The VM is responsible for parsing its bytes. See the static method 
> |ClassLoader.defineModule|. The VM throws a |ClassFormatError| if an 
> ill-formed byte array is presented, or else generates an 
> |AnnotatedElement| from which module-level annotations can be read. 
> See |java.lang.reflect.Module|.
>
> A |j.l.r.Module| encapsulates both a runtime module and module-level 
> annotations. This is because a class should reveal module information 
> exclusively via |java.lang.reflect| entities. See |Class.getModule|. 
> Because |j.l.r.Module| ends up wrapping a runtime module object, 
> |ClassLoader.defineModule| takes a runtime module as well as 
> module-info.class bytes.
>
> A class is associated with a |j.l.r.Module| when the class is defined. 
> See |Class.defineClass(..., Module, ...)|. The |moduleControlsAccess| 
> flag indicates whether the VM should defer to the supplied 
> |j.l.RuntimeModule.hasModuleAccess| method when a module-private 
> member of this class is accessed, or should perform a == comparison of 
> the requesting class's |j.l.RuntimeModule| with this class's 
> |j.l.RuntimeModule|.
>
> When using |ClassLoader.defineModule|, user code can associate 
> different module-info.class bytes (typically from different deployment 
> artifacts) with the same runtime module object. Thus, classes in 
> different deployment modules may reveal different module-level 
> annotations (i.e. |Class.getModule| will return different 
> |j.l.r.Module| objects) but be able to access each other's 
> module-private members (the VM sees the same runtime module associated 
> with each class).
>
> ------------------------------------------------------------------------
> public interface java.lang.RuntimeModule {
>   boolean hasModuleAccess(RuntimeModule other);
> }
>
> public final class java.lang.reflect.Module implements AnnotatedElement {
>   public RuntimeModule getRuntimeModule();
>
>   public String getName();
>     // Result is module name from ClassFile.this_class decoded from internal form
>   public String toString();
>     // Prefix is result of getName(), followed by module-system-specific data
>
>   public <T extends Annotation> T getAnnotation(Class<T> annotationClass);
>   public Annotation[] getAnnotations();
>   public Annotation[] getDeclaredAnnotations();
>   public boolean isAnnotationPresent(Class<? extends Annotation> annotationClass);
> }
>
> public abstract class java.lang.ClassLoader { 
>   protected final Class<?> defineClass(String name, byte[] b, int off, int len,
>                                        ProtectionDomain protectionDomain,
>                                        java.lang.reflect.Module m,
>                                        boolean moduleControlsAccess);
>
>   protected final Class<?> defineClass(String name, ByteBuffer b,
>                                        ProtectionDomain protectionDomain,
>                                        java.lang.reflect.Module m,
>                                        boolean moduleControlsAccess);
>
>   static protected final Module defineModule(byte[] bytes, RuntimeModule rm) throws ClassFormatError;
> }
>
> public class java.lang.Class {
>   java.lang.reflect.Module getModule();
> }
>
>   
> ------------------------------------------------------------------------
>
> _______________________________________________
> jsr294-modularity-eg mailing list
> jsr294-modularity-eg at cs.oswego.edu
> http://cs.oswego.edu/mailman/listinfo/jsr294-modularity-eg
>   
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://cs.oswego.edu/pipermail/jsr294-modularity-eg/attachments/20090715/23558e47/attachment.html>