module-info.class spec and attributes

[Peter Kriens]

I think you conflate the fact that a file is based on a textual format with the fact that it is edited. Files like the manifest and XML files are not human editable although many developers are too lazy to provide a proper front end and offer those files as human editable. They are intended for machine-machine communication with the added benefit that they are easy to verify when things go awry. Our industry learned that lesson the hard way over the past few decades.

The biggest problem with the current design is that it is very hard to make things extensible. Not only for OSGi, but also for Jigsaw in the future as the current design usurps the extension mechanism of class files itself and you cannot extend extensions in class files. If a module was defined as an entity with members, like an interface or class, we could have reused annotations:

	@VersionRange(1.8,2.0)
	@Resolution(Optional)
	import package com.acme.foo.*;
	
	@Version(1.8.8)
	module BAR implements JDK17 {
		
		@Version(1.7)
		package com.sun.misc;

		@Version(1.7)
		@Attribute(name="api",value"true")
		@Mandatory("api")
		package com.sun.impl.java.lang;

		void main(String args[] ) {
			...
		}
	}

As it is now, the class file is just a set of attributes. XML was invented for exactly this purpose, not as a human editable file, but as a file that allows different parties to integrate their information in a single file without having to worry about character sets and collisions. If Jigsaw defines a proper schema, the OSGi and others can add a namespace on each element to carry their metadata. 

Further inline:

On 30 jun 2011, at 09:09, Rémi Forax wrote:
> David,
> I think storing the module metadata as a class file is a brilliant idea.
:-)

> First you have to think that what we want is not one text file but two.
> Some module metadata are generated (the one marked synthetic in the current format)
> by the compiler and as a user I don't want to see them, edit them, etc.
Fully agree, the "binary" version is like the manifest in OSGi, not intended for human consumption with its limited line length. However, when things go awry it is very nice to be able to see them without requiring specialized tools.

> Eclipse plugins use the approach of having one file for the two purposes, be a module
> descriptor editable by a human and be a module deployment descriptor readable
> by the module runtime. As a user, the experience is painful, the file is big and a big part of the data are useless
> and sometimes you have to reconcile the state of the source and the plugin descriptor
> by hand.
That is why this method is disputed. Manifest is a binary format and you should not be edited by hand. That is why for example bndtools and maven generate the manifest.

> To summarize, we need a file which is readable/writable by a human, readable by the compiler
> and the compiler need to generate a module deployment from it that need to be readable
> by the module runtime system. Hence, it's logical to have a Java file and a class file.
Though I agree with the Java source file I fail to see why the output needs to be a Java class file as the module as currently designed does not even remotely look like a class. If it did, (a Module also has members) the story would be different.

> Also a classfile is versioned, compact, has no character encoding problem,
> is well integrated with the other files and as Alex said is more efficient than an XML file.
As the manifest will be compressed by the JAR file the efficiency gain is minimal as the binary class file compresses worse, if relevant at the first place. And if this is an issue, there are even better formats.

> Another cool point is that because the module descriptor is a Java file you know
> where to put the module doc :)
Which makes the module namespace overlap with the package namespace ... which I think will cause some nasty unnecessary constraints as a modules should encapsulate a package namespace and not be part of it.

Kind regards,

	Peter Kriens


> 
> Rémi
> 
> On 06/30/2011 04:51 AM, Alex Buckley wrote:
>> I think we're slightly missing each other here. I wasn't implying javac is unable to cache module declarations; rather that module declarations are now woven deeply into compilation because determining the visibility of _any_ type (whether available in source or class file form) is dependent on a graph of module declarations (possibly cached by the module system, but not when the world is being built from source). Jigsaw is just keeping the structure of those module declarations in source/binary forms that compilers are familiar with.
>> 
>> Alex
>> 
>> On 6/29/2011 6:00 PM, David M. Lloyd wrote:
>>> Not really.  In fact that's basically using the (apparently poor) design choices of the compiler to justify this, which I find to be exceedingly weak.
>>> 
>>> The compiler should never need to parse module information more than once per compilation, regardless of how many source files are compiled.  If it's requiring that, fix the real problem, rather than using it as justification for crap decisions elsewhere.
>>> 
>>> On 06/29/2011 07:46 PM, Alex Buckley wrote:
>>>> In the context of Project Jigsaw, javac parses module declarations every
>>>> time a source file in a modular directory structure is compiled. That's
>>>> a powerful driver for Java-like source syntax and a class file form.
>>>> 
>>>> Projects which don't put module information so close to the compiler may
>>>> well choose other forms.
>>>> 
>>>> Alex
>>>> 
>>>> On 6/29/2011 5:24 PM, David M. Lloyd wrote:
>>>>> On 06/29/2011 07:07 PM, Alex Buckley wrote:
>>>>>> (Sent this mail yesterday but I think it got lost.)
>>>>>> 
>>>>>> On 6/28/2011 2:24 PM, David Bosschaert wrote:
>>>>>>> I wonder why such a binary .class file for module declarations is
>>>>>>> really needed. Why not go for a textual file, for instance
>>>>>>> META-INF/module-info.jmod (or something like that) and declare the
>>>>>>> module declarations in there using a textual format of some sort?
>>>>>> 
>>>>>> The arguments for a binary compiled form are given at:
>>>>>> 
>>>>>> http://openjdk.java.net/projects/jigsaw/doc/draft-java-module-system-requirements-12#_C 
>>>>>> 
>>>>> 
>>>>> All of which are trivially debunkable. Yes, it is *slightly* more
>>>>> efficient to read structured binary than a text format. It is an
>>>>> insignificant difference though. We actually parse ours as XML using
>>>>> StAX, which should be somewhat more expensive than a dedicated text
>>>>> parser, and it's so fast that I'm not even able to get a significant
>>>>> measurement of the time when booting up a 100+ module project. The
>>>>> performance argument is invalid.
>>>>> 
>>>>> And constraining the module metadata to a Java-like syntax with a
>>>>> Java-like file name is just a dumb idea. There's no reason for it.
>>>>> 
>>>>> Saying that requiring a tool to modify the metadata for a module is
>>>>> somehow a good thing is pretty off the wall too. I mean just crazy.
>>>>> 
>>>>> Come down to Earth guys.
>>>>> 
>>>>>>> IMO there are multiple benefits associated keeping the textual format.
>>>>>>> People using the jar can use a simple zip tool to look inside the jar
>>>>>>> to see what its dependencies are. Additionally tools can easily be
>>>>>>> written to read the module-info.jmod file without needing to resort to
>>>>>>> classfile parsing libraries. The module information can be of use to
>>>>>>> both developer as well as deployer tools.
>>>>>>> 
>>>>>>> Finally it's probably easier to make the textual file extensible, as
>>>>>>> required by [1], without resorting to inefficient reflection-style
>>>>>>> operations.
>>>>>> 
>>>>>> I think these points are also captured in Appendix C. Could not the same
>>>>>> points have been made in favor of a textual format for class and
>>>>>> interface declarations?
>>>>> 
>>>>> Yup. But that ship has sailed. A binary format for module
>>>>> meta-information is going to be yet another annoying disaster.
>>> 
>>> 
>