[jsr294-modularity-eg] FW: Superpackage Strawman

[Eugene Vigdorchik]

Hello Experts,
 
Just a few points to consider:
First of of all the rules for determining superpackage file location should be a part of JLS, so that all tools/compilers should
agree on them.
Since this place is to be visible from the classes that import the class from superpackage, I would suggest the set of directories
of all packages common to all classes making up a superpackage transitively. That is for classes Foo.Bar.A and Foo.Bar.B
consistuting a superpackage, the superpackage file should be either in the default package or in Foo or in Bar.
 
Next it seems that having only the possibility to export classes/subpackages is not enough, it should be possible to hide otherwise
exported classes. Thus already having a package in the superpackage the user should be able to hide a certain class in it without
listing all the classes left explicitly in the superpackage.
 
Finally, probably we could come up with a better name for superpackages, since this one is sometimes used to denote a parent
package.
 
Eugene.


  _____  

From: Java Community Process JSR #294 Expert List [mailto:JSR-294-EG at JCP.ORG] On Behalf Of Andreas Sterbenz
Sent: Saturday, March 17, 2007 5:44 AM
To: JSR-294-EG at JCP.ORG
Subject: Superpackage Strawman



Strawman Proposal for JSR 294 Superpackages


Draft 2007-03-16

This is a straw-man proposal for JSR 294 Superpackages written by Andreas Sterbenz and Alex Buckley. It is based on the concepts
described by Gilad Bracha in the JSR submission and the JSR 277 whitepaper by Gilad Bracha and Michal Cierniak. 

As described in the JSR  <http://jcp.org/en/jsr/detail?id=294> 294 submission (Improved Modularity Support in the Java Programming
Language), we propose to address two problems: information hiding and separate compilation. This document describes a proposal for
information hiding using a new entity called superpackage. Separate compilation will be the topic of another document. 


Problem Statement

The current Java mechanisms for information hiding work fine for projects that fit into a single package. Types that are
implementation details can be declared with default (aka package private) access to hide them from code outside the project.
However, if a project is too large to fit into a single package, Java does not provide a suitable encapsulation mechanism. A type
has to be declared public to access it from the different packages of the project, but that also makes it available to packages
outside the project. 

Note: 

These concepts are sometimes referred to as a development module. It is a different - although related - problem to that of
deployment modules, which are the purview of JSR 277. JSR 294 is intended to be independent of the deployment mechanism and can be
used with JAR files and existing ClassLoaders, JSR 277 modules, or other deployment methods. 


Goals

The following design goals were considered when addressing the problem of information hiding described above: 

1.	The access control model defined by the JLS and JVMS is the appropriate unit to extend in order to accommodate projects
larger than a single Java package. 

2.	The extensions to the access control model should be simple and consistent with the existing model. 

3.	Access control information for an entity larger than a single Java package should be declared in Java source files so it can
be processed and enforced by javac. 

4.	The new model should to serve as the basis for deployment modules, but it should also be usable on its own without requiring
modifications to the deployment mechanisms. 

5.	Existing projects should be able to take advantage of the new access control mechanisms by making minimal changes to Java
source files. 


Superpackages

The solution is a new entity called superpackage. A superpackage can be thought of as a named collection of one or more packages or
superpackages and their types. Public types can be declared as exported to make them accessible outside the superpackage. Public
types in a superpackage that are not exported are accessible only to other types in the superpackage. A type can be a member of at
most one superpackage. 

A superpackage is declared in a Java source file. It defines: 


*	superpackage name 

*	members, a list of packages and superpackages 

*	exported members, a list of classes and superpackages 

*	metadata in the form of annotations 

A superpackage contained within another superpackage is called a nested superpackage. Please refer to the section below for
explanation and rationale. 

This source file is processed by a Java compiler similarly to other source files. The result of the compilation is a .superpackage
file, analogous to a .class file. The format of the superpackage file is TBD. 


Note: in earlier discussions the superpackage file was called a module file. The proposed name was changed to avoid confusion with
the Module Archive format defined by JSR 277. 


Example

As an illustration, we define a simple superpackage. Note that the syntax is tentative and certain to evolve. 

File example/foo/myapp/super-package.java: 


// Declare the superpackage

superpackage example.foo.myapp {



    // all types in the listed packages are members of this superpackage

    member package example.foo.myapp, example.foo.myapp.processing;



    // list of exported types

    export example.foo.myapp.Main, example.foo.myapp.Helper;



}

File example/foo/myapp/Main.java 

package example.foo.myapp;



public class Main {

    public Main() { ... }

}

File example/foo/myapp/Parser.java 

package example.foo.myapp;



public class Parser {

    public Parser() { ... }

}

[Other files omitted] 

Explanation

The superpackage source file (example/foo/myapp/super-package.java) defines the members of the superpackage example.foo.myapp as the
packages example.foo.myapp and example.foo.myapp.processing. 

The exported types are example.foo.myapp.Main and example.foo.myapp.Helper. These are the only types that are accessible outside the
superpackage example.foo.myapp. The class example.foo.myapp.Parser is a public non-exported class. That means that it is not
accessible by types outside the superpackage example.foo.myapp. The list of exported types may include * wildcards to export an
entire package. The wildcard is expanded by the Java compiler to full list of type names. 


As with the existing Java access control mechanisms, the superpackage access control is enforced by the Java compiler at compilation
time and the Java virtual machine at runtime (JVMS
<http://java.sun.com/docs/books/vmspec/2nd-edition/html/ConstantPool.doc.html#75929> 5.4.4). 


Note that this proposal avoids having the source of each Java type declare its superpackage membership. This approach was chosen in
order to make it easier to migrate existing Java source code to superpackages. However, Java class files that are part of a
superpackage will contain an appropriate attribute that indicates the name of the superpackage. It is assumed that the Java compiler
is able to determine superpackage membership from the superpackage source file or in some other way, for example using commandline
arguments. 


Runtime aspects

A superpackage file is reified at runtime using a reflective API in the style of java.lang.Class. This class java.lang.Superpackage
allows retrieval of the information declared in the superpackage source file, such as the names of exported types. A method
getSuperpackage() is added to java.lang.Class, which returns the superpackage object associated with a class, or null if the class
is not a member of a superpackage. 

A superpackage file is loaded via a ClassLoader. A superpackage is always defined by the same ClassLoader as its member classes. 


Nested Superpackages

A superpackage can include other superpackages as its members. A superpackage that is a member of another superpackage is called a
nested superpackage. The superpackage containing it is called its enclosing superpackage. Nested superpackage are useful in large
projects where information hiding between internal components is desired. The nesting scheme is recursive with no practical limit on
the level of nesting. Note that it is expected that a superpackage and all its nested superpackages will form one deployment unit. 

A nested superpackage is declared by listing the name of the enclosing superpackage in its superpackage source file, and by the
enclosing superpackage listing the nested superpackage as a member. 


The enclosing superpackage can declare a nested superpackages as exported. If exported, the exported types of the nested
superpackage are accessible outside the enclosing superpackage. If not exported, the exported types of the nested superpackage are
accessible to other types in the enclosing superpackage but not outside the enclosing superpackage. 


Example

We declare a superpackage example.bar.lib which contains the package example.bar.lib and the nested superpackages
example.bar.lib.net and example.bar.lib.xml. 

The type example.bar.lib.Table is exported by example.bar.lib and therefore accessible by other code. The nested superpackage
example.bar.lib.net is also declared as exported. This means that all types it exports - example.bar.lib.net.* - are also accessible
to code outside the example.bar.lib superpackage. 


The nested superpackage example.bar.lib.xml is not exported by example.bar.lib. This means that the exported types from
example.bar.lib.xml are accessible to code in example.bar.lib - including its nested superpackage example.bar.lib.net - but they are
not accessible to code outside of example.bar.lib. 


File example/bar/lib/super-package.java: 


// Declare the superpackage

superpackage example.bar.lib {



    // member packages

    member package example.bar.lib;



    // member superpackages

    member superpackage example.bar.lib.net, example.bar.lib.xml;



    // list of exported types

    export example.bar.lib.Table;



    export superpackage example.bar.lib.net;



}

File example/bar/lib/net/super-package.java: 

// First nested superpackage

superpackage example.bar.lib.net member example.bar.lib {



    // member packages

    member package example.bar.lib.net, example.bar.lib.http;



    // list of exported types

    export example.bar.lib.net.*;



}

File example/bar/lib/xml/super-package.java: 

// Second nested superpackage

superpackage example.bar.lib.xml member example.bar.lib {



    // member packages

    member package example.bar.lib.xml, example.bar.lib.xml.internal;



    // list of exported types

    export example.bar.lib.xml.*;



}

  _____  

-------------- next part --------------
An HTML attachment was scrubbed...
URL: /pipermail/attachments/20070411/4101e29c/attachment.html