module-info.class spec and attributes

Alex Buckley alex.buckley at oracle.com
Fri Jun 24 18:01:19 PDT 2011


Since attachments seem to be scrubbed, here is the text of the proposal, 
obviously without links to the requirements document.


ClassFile changes for Java Modules

Binary form of a module declaration (a.k.a. module-info.class)
A compilation unit that contains a module declaration (and potentially 
additional arbitrary content) is compiled to a ClassFile structure like 
any other compilation unit.

By convention, the name of a compilation unit that contains a module 
declaration is module-info.java, echoing the package-info.java 
convention for a compilation unit that contains solely a package 
declaration. Consequently, by convention, the name for the compiled form 
of a module declaration is module-info.class.

A new flag in the ClassFile.access_flags item, ACC_MODULE (0x0800), 
indicates that the ClassFile represents a module rather than a class or 
interface. Note that this flag plays a similar role to ACC_INTERFACE 
(0x0200), and does not describe accessibility of a class or interface.

If ACC_MODULE is set in ClassFile.access_flags, then no other flag in 
ClassFile.access_flags may be set, and the following rules apply to the 
rest of the ClassFile structure:

     * major_version, minor_version: >=52.0 (Java SE 8 and above)
     * this_class: [Module's name in internal form (JVMS 4.2.1)]/module-info

       (Traditionally, if this_class indicates "P/Q/R", then the 
ClassFile can be expected to live in a file R.class in a directory P/Q 
representing a package. This explains why "/module-info" is a suffix in 
this_class above: if this_class indicates "P/Q/module-info", then the 
ClassFile can be expected to live in a file module-info.class in a 
directory P/Q representing a module. The "real name" of the module, 
shorn of "/module-info", can be obtained from the Module attribute.)
     * super_class, interfaces_count, fields_count, methods_count: 0
     * attributes: One Module attribute must be present, to record the 
name and version of the module. At most one of each of the 
ModuleRequires, ModuleProvides, ModulePermits, ModuleExports, 
ModuleClass, and ModuleData attributes may be present. Except for these 
attributes and Synthetic, SourceFile, SourceDebugExtension, and 
Deprecated, none of the pre-defined attributes in JVMS 4.7 may appear.

The CONSTANT_ModuleId_info structure

The CONSTANT_ModuleId_info structure in the constant pool is used to 
represent a pair of a module name and a module version.

CONSTANT_ModuleId_info {
   u1 tag;
     // 19
   u2 name_index;
     // Points to a CONSTANT_Utf8_info representing module name in 
internal form (JVMS 4.2.1)
   u2 version_index;
     // Optionally points to a CONSTANT_Utf8_info representing module 
version
}

If the version_index item is 0 (as opposed to pointing to a 
CONSTANT_Utf8_info structure which holds the string "0"), then no module 
version is present.

If the version_index item is not 0, then a module version is present. 
There is no required structure or semantics for the underlying UTF8 
string which represents a module version.

The Module attribute

Module_attribute {
   u2 attribute_name_index;
   u4 attribute_length;
   u2 module_id_index;
}

The items of the Module_attribute structure are as follows:

attribute_name_index
     The value of the attribute_name_index item must be a valid index 
into the constant_pool table. The constant_pool entry at that index must 
be a CONSTANT_Utf8_info structure representing the string "Module".
attribute_length
     The value of the attribute_length item must be 2.
module_id_index
     The value of the module_id_index item must be a valid index into 
the constant_pool table. The constant_pool entry at that index must be a 
CONSTANT_ModuleId_info structure representing the name and version of 
the module represented by this ClassFile.
     The name must be equal to the module name indicated by the 
ClassFile.this_class item without the "/module-info" suffix.

The ModuleRequires attribute

ModuleRequires_attribute {
   u2 attribute_name_index;
   u4 attribute_length;
   u2 requires_length;
   { u2 requires_index; u1 flags; } requires_table[requires_length];
}

attribute_name_index
     The value of the attribute_name_index item must be a valid index 
into the constant_pool table. The constant_pool entry at that index must 
be a CONSTANT_Utf8_info structure representing the string "ModuleRequires".
attribute_length
     The value of the attribute_length item is the length of the 
attribute excluding the initial six bytes.
requires_length
     The value of the requires_length indicates the number of entries in 
the requires_table.
requires_table
     Each requires_index must be a valid index into the constant_pool 
table. The constant_pool entry at that index must be a 
CONSTANT_ModuleId_info structure representing the target module on which 
this module depends.
     The value of the associated flags item is as follows:

         * 0x01 indicates this dependency on the target module is optional.
         * 0x02 indictates the target module's types must be loaded by 
the same defining classloader as the types of the module represented by 
this ClassFile.

     A module name may be referenced by at most one entry in a 
requires_table.

The ModulePermits attribute

ModulePermits_attribute {
   u2 attribute_name_index;
   u4 attribute_length;
   u2 permits_length;
   { u2 permits_index } permits_table[permits_length];
}

attribute_name_index
     The value of the attribute_name_index item must be a valid index 
into the constant_pool table. The constant_pool entry at that index must 
be a CONSTANT_Utf8_info structure representing the string "ModulePermits".
attribute_length
     The value of the attribute_length item is the length of the 
attribute excluding the initial six bytes.
permits_length
     The value of the permits_length indicates the number of entries in 
the permits_table.
permits_table
     The value of each permits_index in this item must be a valid index 
into the constant_pool table. The constant_pool entry at that index must 
be a CONSTANT_ModuleId_info structure representing a module which is 
permitted to have a dependency on the module represented by this ClassFile.
     (It is possible that a module system uses only the name of the 
permitted module, not its version, in determining visibility.)
     A module name may be referenced by at most one entry in a 
permits_table.

The ModuleProvides attribute

ModuleProvides_attribute {
   u2 attribute_name_index;
   u4 attribute_length;
   u2 provides_length;
   { u2 provides_index; } provides_table[provides_length];
}

attribute_name_index
     The value of the attribute_name_index item must be a valid index 
into the constant_pool table. The constant_pool entry at that index must 
be a CONSTANT_Utf8_info structure representing the string "ModuleProvides".
attribute_length
     The value of the attribute_length item is the length of the 
attribute excluding the initial six bytes.
provides_length
     The value of the provides_length indicates the number of entries in 
the provides_table.
provides_table
     The value of each provides_index in this item must be a valid index 
into the constant_pool table. The constant_pool entry at that index must 
be a CONSTANT_ModuleId_info structure representing a module that is an 
alias for the module represented by this ClassFile.
     A module name may be referenced by at most one entry in a 
provides_table.

The ModuleExports attribute

ModuleExports_attribute {
   u2 attribute_name_index;
   u4 attribute_length;
   u2 exports_length;
   { u2 exports_index; u1 export_kind; u2 source_index; } 
exports_table[exports_length];
}

attribute_name_index
     The value of the attribute_name_index item must be a valid index 
into the constant_pool table. The constant_pool entry at that index must 
be a CONSTANT_Utf8_info structure representing the string "ModuleExports".
attribute_length
     The value of the attribute_length item is the length of the 
attribute excluding the initial six bytes.
exports_length
     The value of the exports_length indicates the number of entries in 
the exports_table.
exports_table
     The value of each export_index in this item must be a valid index 
into the constant_pool table. The constant_pool entry at that index must 
be a CONSTANT_Utf8_info structure representing an entity to be exported 
by the module represented by this ClassFile.
     The value of the associated export_kind item indicates the kind of 
entity to be exported, as follows:

         * 0x01 indicates the entity is a class or interface; it is the 
entity to be exported.
         * 0x02 indicates the entity is a class or interface; it and its 
member types are the entities to be exported.
         * 0x04 indicates the entity is a package; the member top-level 
classes and interfaces (and their member types) of this package are the 
entities to be exported.
         * 0x08 indicates the entity is a package; the member top-level 
classes and interfaces (and their member types) of this package and all 
its subpackages (recursively) are the entities to be exported.

     The value of the associated source_index item must be a valid index 
into the constant_pool table where the entry is a CONSTANT_ModuleId_info 
structure representing the module which declared the exported entity. 
(In most cases, where the exported entity is declared in the current 
module, source_index will simply point to the same constant pool entry 
as the Module attribute. But where the exported entity is re-exported, 
source_index may assist resolution and diagnostics.)

The ModuleClass attribute

ModuleClass_attribute {
   u2 attribute_name_index;
   u4 attribute_length;
   u2 main_class_index;
}

attribute_name_index
     The value of the attribute_name_index item must be a valid index 
into the constant_pool table. The constant_pool entry at that index must 
be a CONSTANT_Utf8_info structure representing the string "ModuleClass".
attribute_length
     The value of the attribute_length item is 2.
main_class_index
     The value of the main_class_index item must be a valid index into 
the constant_pool table. The constant_pool entry at that index must be a 
CONSTANT_Class_info structure representing the name of the class which 
is the entrypoint to the module represented by this ClassFile.

The ModuleData attribute

ModuleExtension_attribute {
   u2 attribute_name_index;
   u4 attribute_length;
   u2 data_index;
}

attribute_name_index
     The value of the attribute_name_index item must be a valid index 
into the constant_pool table. The constant_pool entry at that index must 
be a CONSTANT_Utf8_info structure representing the string "ModuleData".
attribute_length
     The value of the attribute_length item is 2.
data_index
     The value of the main_class item must be a valid index into the 
constant_pool table. The constant_pool entry at that index must be a 
CONSTANT_Utf8_info structure representing the content, other than the 
module declaration, of the compilation unit that declared the module 
represented by this ClassFile.



More information about the jigsaw-dev mailing list