JSR-277: Java Module System

Sun Microsystems, Inc.
JSR-277: Java
TM
Module System
JSR-277 Expert Group

Specification Lead: Stanley M. Ho, Sun Microsystems, Inc. Date: October 2, 2006 Please send comments to: jsr-277-comments@jcp.org
FT A R D Y L R A E
Java Module System, Early Draft
JSR-000277 Java(tm) Module System Specification ("Specification") Version: 0.121 Status: Early Draft Review Release: 2 October 2006 Copyright 2006 Sun Microsystems, Inc. 4150 Network Circle, Santa Clara, California 95054, U.S.A All rights reserved.
NOTICE The Specification is protected by copyright and the information described therein may be protected by one or more U.S. patents, foreign patents, or pending applications. Except as provided under the following license, no part of the Specification may be reproduced in any form by any means without the prior written authorization of Sun Microsystems, Inc. ("Sun") and its licensors, if any. Any use of the Specification and the information described therein will be governed by the terms and conditions of this Agreement. Subject to the terms and conditions of this license, including your compliance with Paragraphs 1, 2 and 3 below, Sun hereby grants you a fully-paid, non-exclusive, non-transferable, limited license (without the right to sublicense) under Sun's intellectual property rights to: 1.Review the Specification for the purposes of evaluation. This includes: (i) developing implementations of the Specification for your internal, non-commercial use; (ii) discussing the Specification with any third party; and (iii) excerpting brief portions of the Specification in oral or written communications which discuss the Specification provided that such excerpts do not in the aggregate constitute a significant portion of the Technology. 2.Distribute implementations of the Specification to third parties for their testing and evaluation use, provided that any such implementation: (i) does not modify, subset, superset or otherwise extend the Licensor Name Space, or include any public or protected packages, classes, Java interfaces, fields or methods within the Licensor Name Space other than those required/authorized by the Specification or Specifications being implemented; (ii)is clearly and prominently marked with the word "UNTESTED" or "EARLY ACCESS" or "INCOMPATIBLE" or "UNSTABLE" or "BETA" in any list of available builds and in proximity to every link initiating its download, where the list or link is under Licensee's control; and (iii)includes the following notice: "This is an implementation of an early-draft specification developed under the Java Community Process (JCP) and is made available for testing and evaluation purposes only. The code is not compatible with any specification of the JCP." The grant set forth above concerning your distribution of implementations of the specification is contingent upon your agreement to terminate development and distribution of your "early draft" implementation as soon as feasible following final completion of the specification. If you fail to do so, the foregoing grant shall be considered null and void.
ii
10/2/06
No provision of this Agreement shall be understood to restrict your ability to make and distribute to third parties applications written to the Specification. Other than this limited license, you acquire no right, title or interest in or to the Specification or any other Sun intellectual property, and the Specification may only be used in accordance with the license terms set forth herein. This license will expire on the earlier of: (a) two (2) years from the date of Release listed above; (b) the date on which the final version of the Specification is publicly released; or (c) the date on which the Java Specification Request (JSR) to which the Specification corresponds is withdrawn. In addition, this license will terminate immediately without notice from Sun if you fail to comply with any provision of this license. Upon termination, you must cease use of or destroy the Specification. "Licensor Name Space" means the public class or interface declarations whose names begin with "java", "javax", "com.sun" or their equivalents in any subsequent naming convention adopted by Sun through the Java Community Process, or any recognized successors or replacements thereof TRADEMARKS No right, title, or interest in or to any trademarks, service marks, or trade names of Sun or Sun's licensors is granted hereunder. Sun, Sun Microsystems, the Sun logo, Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. DISCLAIMER OF WARRANTIES THE SPECIFICATION IS PROVIDED "AS IS" AND IS EXPERIMENTAL AND MAY CONTAIN DEFECTS OR DEFICIENCIES WHICH CANNOT OR WILL NOT BE CORRECTED BY SUN. SUN MAKES NO REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE OR THAT ANY PRACTICE OR IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADE SECRETS OR OTHER RIGHTS. This document does not represent any commitment to release or implement any portion of the Specification in any product. THE SPECIFICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION THEREIN; THESE CHANGES WILL BE INCORPORATED INTO NEW VERSIONS OF THE SPECIFICATION, IF ANY. SUN MAY MAKE IMPROVEMENTS AND/OR CHANGES TO THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THE SPECIFICATION AT ANY TIME. Any use of such changes in the Specification will be governed by the then-current license for the applicable version of the Specification. LIMITATION OF LIABILITY TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, LOST REVENUE, PROFITS OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF OR RELATED TO ANY FURNISHING, PRACTICING, MODIFYING OR ANY USE OF THE SPECIFICATION, EVEN IF SUN AND/OR ITS LICENSORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
iii
10/2/06
You will hold Sun (and its licensors) harmless from any claims based on your use of the Specification for any purposes other than the limited right of evaluation as described above, and from any claims that later versions or releases of any Specification furnished to you are incompatible with the Specification provided to you under this license. RESTRICTED RIGHTS LEGEND If this Software is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime contractor or subcontractor (at any tier), then the Government's rights in the Software and accompanying documentation shall be only as set forth in this license; this is in accordance with 48 C.F.R. 227.7201 through 227.7202-4 (for Department of Defense (DoD) acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for non-DoD acquisitions). REPORT You may wish to report any ambiguities, inconsistencies or inaccuracies you may find in connection with your evaluation of the Specification ("Feedback"). To the extent that you provide Sun with any Feedback, you hereby: (i) agree that such Feedback is provided on a non-proprietary and non-confidential basis, and (ii) grant Sun a perpetual, non-exclusive, worldwide, fully paid-up, irrevocable license, with the right to sublicense through multiple levels of sublicensees, to incorporate, disclose, and use without limitation the Feedback for any purpose related to the Specification and future versions, implementations, and test suites thereof. GENERAL TERMS Any action related to this Agreement will be governed by California law and controlling U.S. federal law. The U.N. Convention for the International Sale of Goods and the choice of law rules of any jurisdiction will not apply. The Specification is subject to U.S. export control laws and may be subject to export or import regulations in other countries. Licensee agrees to comply strictly with all such laws and regulations and acknowledges that it has the responsibility to obtain such licenses to export, re-export or import as may be required after delivery to Licensee. This Agreement is the parties' entire agreement relating to its subject matter. It supersedes all prior or contemporaneous oral or written communications, proposals, conditions, representations and warranties and prevails over any conflicting or additional terms of any quote, order, acknowledgment, or other communication between the parties relating to its subject matter during the term of this Agreement. No modification to this Agreement will be binding, unless in writing and signed by an authorized representative of each party.
iv
10/2/06
Sun Microsystems Inc

Preface ........................................................................................................................... 5 Chapter 1 Introduction.................................................................................................................... 7 1.1 Background...................................................................................................... 7 1.2 Overall Architecture ........................................................................................ 8 1.3 Simplicity ........................................................................................................ 8 1.4 Reflective API ................................................................................................. 8 1.5 Development Module and Deployment Module ............................................. 9 1.6 Multiple Languages ......................................................................................... 9 1.7 JSR-277 Expert Group .................................................................................... 9 1.8 Acknowledgements ......................................................................................... 10 1.9 Document Conventions ................................................................................... 10 Fundamentals ................................................................................................................. 11 2.1 What is a Module?........................................................................................... 11 2.2 Module Name .................................................................................................. 12 2.3 Module Version ............................................................................................... 13 2.4 Module Identity ............................................................................................... 13 2.5 Module Metadata............................................................................................. 13 2.6 Module Export................................................................................................. 14 2.7 Module Import................................................................................................. 16 2.7.1 Import with version constraint .......................................................... 16 2.7.2 Import policy..................................................................................... 17 2.8 Distribution Format ......................................................................................... 18 2.9 Repository ....................................................................................................... 19 2.10 Security............................................................................................................ 19 2.11 Multi-Threading .............................................................................................. 19 2.12 Platform Binding ............................................................................................. 20 2.13 Classloading .................................................................................................... 20 2.14 Legacy JAR Files ............................................................................................ 20 2.15 Native Libraries ............................................................................................... 21 2.16 Executable Module.......................................................................................... 21 2.17 Modules from the Java Runtime Environment................................................ 21 2.18 Tools Support................................................................................................... 22 Note on Development Module....................................................................................... 23 3.1 Source Code..................................................................................................... 23 3.2 Compiling a Development Module ................................................................. 24 3.3 Integration between JSR-277 and JSR-294..................................................... 25 3.4 Decorating a Development Module................................................................. 25
Chapter 2
Chapter 3
October 2, 2006 1:34 am
Sun Microsystems Inc.

Chapter 4
Scenarios ........................................................................................................................ 27 4.1 Scenario 1: Creating New Modules................................................................. 27 4.1.1 Develop the library............................................................................ 27 4.1.2 Develop the application..................................................................... 29 4.1.3 Trying it out....................................................................................... 30 4.2 Scenario 2: Adding Bug Fixes......................................................................... 30 4.2.1 Develop the library............................................................................ 30 4.2.2 Trying it out....................................................................................... 31 4.3 Scenario 3: Adding New Features ................................................................... 32 4.3.1 Develop the library............................................................................ 32 4.3.2 Trying it out....................................................................................... 33 4.4 Scenario 4: Making Incompatible Changes..................................................... 34 4.4.1 Develop the library............................................................................ 34 4.4.2 Develop the application..................................................................... 35 4.4.3 Trying it out....................................................................................... 36 Versioning ...................................................................................................................... 39 5.1 Version ............................................................................................................. 39 5.1.1 Versioning Policy .............................................................................. 42 5.2 Version Range.................................................................................................. 43 5.3 Version Constraint ........................................................................................... 45 Distribution Format........................................................................................................ 47 6.1 Overview ......................................................................................................... 47 6.2 File Contents.................................................................................................... 48 6.2.1 Metadata ............................................................................................ 48 6.2.2 Resources .......................................................................................... 48 6.2.3 Native Libraries................................................................................. 48 6.2.4 Legacy JAR Files .............................................................................. 49 6.3 Types of Module Archive ................................................................................ 49 6.4 Note on Manifest ............................................................................................. 50 6.5 Signed JAM File .............................................................................................. 51 6.6 Packed JAM file .............................................................................................. 51 Repository ...................................................................................................................... 53 7.1 Overview ......................................................................................................... 53 7.2 Construction..................................................................................................... 55 7.3 Initialization and Shutdown............................................................................. 55 7.4 Search .............................................................................................................. 55 7.5 Install Module Definition ................................................................................ 56 7.6 Uninstall Module Definition............................................................................ 57 7.7 Reload Module Definitions ............................................................................. 57 7.8 Repository Interchange Format ....................................................................... 58
Chapter 5
Chapter 6
Chapter 7
10/2/06

7.9 7.10 7.11 7.12 Chapter 8
Insulating Module Definitions......................................................................... 59 Local Repository ............................................................................................. 60 URL Repository .............................................................................................. 60 Notes to Repository Implementors.................................................................. 62
Runtime Support ............................................................................................................ 65 8.1 Execution......................................................................................................... 65 8.1.1 Module System Start-up.................................................................... 65 8.1.2 Initialization of Module Instances..................................................... 66 8.1.3 Creation of New Module Instances................................................... 68 8.1.4 Module System Shutdown ................................................................ 68 8.2 Resolving......................................................................................................... 68 8.2.1 Preparation ........................................................................................ 69 8.2.2 Validation .......................................................................................... 71 8.2.3 Scenarios ........................................................................................... 71 8.3 Classloading .................................................................................................... 75 8.3.1 Search Order ..................................................................................... 75 8.3.2 Classes and Resources Visibility....................................................... 76 8.3.3 Classes and Protection Domain......................................................... 77 8.3.4 Classloading Requirements for Java SE 7 ........................................ 77 Migration ....................................................................................................................... 79 9.1 Dependencies of Modules on Legacy JAR Files............................................. 79 9.2 Dependencies of Legacy JAR Files on Modules............................................. 80 9.3 Dependencies of Legacy JAR Files on Extensions ......................................... 80 9.4 User Defined Class Loaders ............................................................................ 82 9.5 Limitations....................................................................................................... 82 Related Documents ........................................................................................................ 83 Glossary ......................................................................................................................... 85 Application Programming Interface .............................................................................. 91 A.1 java.lang.Class (Changes only) ....................................................................... 92 A.2 java.lang.module.ImportDependency.............................................................. 92 A.3 java.lang.module.ImportPolicy ....................................................................... 93 A.4 java.lang.module.ImportPolicyError ............................................................... 94 A.5 java.lang.module.LocalRepository.................................................................. 95 A.6 java.lang.module.Module ................................................................................ 96 A.7 java.lang.module.ModuleDefFormatException .............................................. 98 A.8 java.lang.module.ModuleDefNotFoundException.......................................... 99 A.9 java.lang.module.ModuleDefinition................................................................ 100
Chapter 9
Chapter 10 Chapter 11 Appendix A
October 2, 2006 1:34 am

A.10 A.11 A.12 A.13 A.14 A.15 A.16 A.17 A.18 A.19 A.20 A.21 A.22 A.23 A.24 A.25 A.26 A.27 A.28 A.29 A.30 A.31 A.32 A.33 A.34 A.35 A.36 A.37 A.38 Appendix B
java.lang.module.ModuleDefinitionContent ................................................... 104 java.lang.module.ModuleFileFormatError ...................................................... 106 java.lang.module.ModuleSystemPermission................................................... 107 java.lang.module.Query................................................................................... 109 java.lang.module.Repository ........................................................................... 112 java.lang.module.RepositoryCircularityError ................................................. 118 java.lang.module.RepositoryFactory ............................................................... 119 java.lang.module.ResolveError ....................................................................... 120 java.lang.module.URLRepository ................................................................... 121 java.lang.module.ValidationException ............................................................ 123 java.lang.module.Version ................................................................................ 124 java.lang.module.VersionFormatException..................................................... 127 java.lang.module.annotation.ExportResources ............................................... 128 java.lang.module.annotation.ImportPolicyClass ............................................. 129 java.lang.module.annotation.MainClass.......................................................... 130 java.lang.module.annotation.ModuleAttribute ................................................ 131 java.lang.module.annotation.ModuleAttributes .............................................. 132 java.lang.module.annotation.NativeLibraryPath ............................................. 133 java.lang.module.annotation.NativeLibraryPaths ........................................... 134 java.lang.module.annotation.PlatformBinding ................................................ 135 java.lang.module.annotation.ReexportResources............................................ 136 java.lang.module.annotation.SearchPath......................................................... 137 java.lang.module.annotation.SkipValidation ................................................... 138 java.lang.module.annotation.Version............................................................... 139 java.lang.module.annotation.VersionConstraint .............................................. 140 java.lang.module.spi.ModuleDefinitionProvider ............................................ 141 java.lang.module.spi.ModuleProvider............................................................. 144 java.lang.module.spi.RepositoryProvider........................................................ 145 Schema: URL Repository Metadata ................................................................ 147
Frequently Asked Questions (FAQ)............................................................................... 149 B.1 Why does the versioning scheme look familiar?............................................. 149 B.2 What should I be aware in migration from an existing versioning scheme?... 149 B.3 Will module developers need to write the import policy manually?............... 150 B.4 Why are the exports lists for classes and resources separate? ......................... 150 B.5 Why is the JAM file format based on the JAR file format? ............................ 150 B.6 Can a JAM file be used as a plain JAR file in older releases? ........................ 151 B.7 Does the system recognize the JAM file as a physical representation of a module definition no matter what I do?151 B.8 Why isnt the Class-Path manifest entry recognized in JAM? ........................ 151 B.9 What kind of errors would be caught by shallow validation? ......................... 151 B.10 When do we want to do a deep validation? ..................................................... 152
10/2/06

B.11 When do we need to instantiate a new module instance explicitly? ............... 152 B.12 How scalable is the URL repository?.............................................................. 152 B.13 Why does the URL repository require the module file to be hosted separately from the module archive?152 Appendix C Expert Group Work Items.............................................................................................. 153 C.1 Submodules ..................................................................................................... 153 C.2 Distribution Format for Multiple Module Definitions .................................... 153 C.3 Internationalization.......................................................................................... 154 C.4 Contractual Dependency ................................................................................. 154 C.5 Missing Dependency Prediction...................................................................... 154 C.6 More Explicit Lifecycle................................................................................... 154 C.7 Interoperability with Other Module Systems .................................................. 154 C.8 Monitoring and Management Support............................................................. 154 C.9 Locking Strategy for Initializing Module Instances ........................................ 155 C.10 Tearing Down Module Instances..................................................................... 155 C.11 Import Policy Override.................................................................................... 155 C.12 Refactoring and Refining Abstractions ........................................................... 155 Revision History ............................................................................................................ 157 D.1 Early Draft ....................................................................................................... 157
Appendix D
October 2, 2006 1:34 am

Preface
This is an Early Draft of the Java Module System specification. This draft is made available to the community for the purpose of giving insight into the work in progress of the JSR-277 Expert Group and to gather constructive feedback on the directions we are taking and the open issues indicated in this draft. This draft covers many areas of the Java Module System, but it is by no means complete. Because of the volume of interest in the Java Module System, we cannot normally respond individually to reviewer comments, but we do carefully read and consider all inputs. Feedback to the Expert Group can be sent to jsr-277-comments@jcp.org.
October 2, 2006 1:33 am

Preface Java Module System, Early Draft
10/2/06

Background Java Module System, Early Draft Introduction
Ch apt er 1
Introduction
Java Module System is an architecture for the development and the deployment of module-based applications and libraries. Applications and libraries written as Java modules are easy to develop and deploy, with first class modularity, packaging, and deployment support in the Java platform.
1.1 Background
Java Archives (JARs) are widely used as both the distribution format and the execution format for Java applications. The JAR file format dates back to the mid-1990s, and it has not scaled particularly well in either of these roles. JAR files are hard to distribute, hard to version, and hard to reference in general. Distributing a simple Java application is considered to be a complicated task by many developers because it often involves creating a native installer to package multiple JAR files into a distribution unit, and it sometimes involves converting the application into a Java applet or JNLP (Java Network Launching Protocol) application for web-based deployment. The versioning support in the JAR file format is for expressing dependencies on Java extensions (a.k.a optional packages), but not the version of the JAR file itself. There is also no reliable mechanism for expressing, resolving, and enforcing the dependency of one JAR file upon another. Referencing a JAR file, moreover, involves specifying it in the classpath. Since the path of a JAR file may change during deployment, developers are forced to fix up all the references to the deployed JAR files as part of the
October 2, 2006 1:33 am

Introduction Java Module System, Early Draft Overall Architecture
deployment process. Developers also find it quite difficult to deploy installed Java extensions because they can easily run into issues like versioning conflict and namespace collision. Java extensions can currently only be installed into a specific Java Runtime Environment (JRE); it is basically impossible to arrange for an installed extension to be shared across multiple JRE installations. The overall goal of the Java Module System is to define a solution that addresses the above issues.
1.2 Overall Architecture

The Java Module System defines an architecture with the following components:
A distribution format (i.e., a Java module) and its metadata as a unit of delivery for packaging
collections of Java classes and related resources. The metadata contains information about the module, classes and resources within the module, and its dependencies upon other modules. The metadata also includes list of exports to restrict classes and resources from being exposed outside the module unintentionally.
A versioning scheme that defines how a module declares its own version as well its versioned
dependencies upon other modules.
A repository for storing, discovering, and retrieving modules with versioning and isolation
support.
Runtime support in the application launcher and the class loaders for discovering, loading, and
integrity checking of modules.
The Java Module System is compatible with Java SE 7 or later.
1.3 Simplicity
The Java Module System is designed to be relatively simple to understand and use. As a general design principle, the focus is on making simple things easy, while making complex things possible. Developers should be able to learn the basic Java module concepts very quickly so that they can start writing and using simple modules with very little effort and then slowly progress to build more sophisticated module-based applications.
1.4 Reflective API

The problems confronting the modularity issues in the Java platform are extremely broad and varied. To
10/2/06

Development Module and Deployment Module Java Module System, Early Draft Introduction
address this very wide spectrum of needs, concepts around modularity are reified via a reflective API, allowing modules to be manipulated using the full power of a general purpose programming language.
1.5 Development Module and Deployment Module

A Java module is generally written as a development module in a programming language in the Java platform, and is ultimately compiled and packaged together with classes and other resources as a deployment module for distribution. The development module is defined in JSR-294: Improved Modularity Support in the Java Programming Language [20]. It covers the language extensions in support of information hiding and separate compilation in the Java programming language, and the runtime support in the Java virtual machine (JVM). The deployment module is defined in JSR-277: Java Module System (i.e. this specification). It covers the versioning scheme, the distribution format, the repository, and the runtime support in the JVM. JSR-277 depends on JSR-294, but not vice versa.
1.6 Multiple Languages

The Java platform is increasingly seen as supporting diverse programming languages. The Java Module System is not specific to the Java programming language, although there are APIs available in that context. Programs in any language running on the JVM would ultimately be represented by classes and any language specific resources. All of these are then packaged into a deployment module, regardless of the source language. Each language should be able to surface the APIs defined by the Java Module System, and modules developed in one language should be usable in another language in the Java platform.
1.7 JSR-277 Expert Group

The JSR-277 specification work is being conducted as part of JSR-277 under the Java Community Process Program. This specification is the result of the collaborative work of the members of the JSR-277 Expert Group. These experts include the present and former expert group members: Apache Software Foundation: Geir Magnusson Jr., Brett Porter; BEA: Andy Piper; Google: Michal Cierniak; IBM: Glyn Normington; Intel: Wayne Carr, Vladimir Strigun; Ironflare AB: Hani Suleiman; Jayasoft: Xavier Hanin; JBoss: Adrian Brock; Oracle: Bryan Atsatt; SAP AG: Georgi Danov; SAS Institute: Gordon Hirsch; Sun Microsystems: Stanley M. Ho; David W. Bock; Richard S. Hall; Stuart Halloway; Doug Lea; Daniel Pierce Leuck; Ted Neward; Samuel Pullara; Jason van Zyl.
October 2, 2006 1:33 am

Introduction Java Module System, Early Draft Acknowledgements
1.8 Acknowledgements
Many people have provided invaluable technical input in the development of the JSR-277 specification: Google: Joshua Bloch, Neal Gafter; Sun Microsystems: Gilad Bracha, David Bristor, Danny Coward, Jesse Glick, Chet Haase, Graham Hamilton, David Holmes, Peter Kessler, Karen Kinnear, Joseph Kowalski, Jeff Nisewanger, Mark Reinhold, Bill Shannon, Andreas Sterbenz, Jaroslav Tulach.
1.9 Document Conventions

The regular Times font is used for information that is prescriptive by the JSR-277 specification. The italic Times font is used for paragraphs that contain descriptive information, such as notes describing typical use, or notes clarifying the text with prescriptive specification. The Courier font is used for code examples.
10/2/06
10

What is a Module? Java Module System, Early Draft Fundamentals
Ch apt er 2
Fundamentals
2.1 What is a Module?

The notion of module is heavily overloaded, and it often has different meanings in different contexts. Lets start with an initial statement and then refine it: A Java module is a unit of encapsulation. It is generally written as a development module in a programming language in the Java platform, and is ultimately compiled into metadata and packaged together with classes and other resources as a deployment module. Throughout this specification, any mention of module will refer to the deployment module unless explicitly stated otherwise. In the context of the deployment module, there is also a further distinction between module definitions and module instances. A module definition is a unit of reuse, versioning, packaging, and deployment in the module system. It identifies a logical module, and specifies what classes and resources are provided by the module, and what the module imports and exports. The classes in the module definition could be from one or more Java packages. A module definition is inherently stateless, and is properly understood as a mathematical abstraction. Such a module definition may be instantiated creating a module instance at run time.
11
October 2, 2006 1:33 am

Fundamentals Java Module System, Early Draft Module Name
By default, the same module instance created from a module definition should be used to maximize sharing. However, multiple instances of a module definition can exist simultaneously in a Java virtual machine (JVM) process to support other potential usages, e.g, the ability to specify a particular, well-tested version of a module for private use. Each instance has its own copies of the classes defined by the module, each with their own independent static state. Each instance can be interconnected with other module instances that provide it with elements that it imports. Hence, each module instance creates a distinct namespace at run time. A useful intuition is that module definitions are analogous to classes, and module instances to objects. Both module definitions and module instances are reified via a reflective API at the level of the Java programming language and Java virtual machine, thus allowing modules to be manipulated using the full power of a general purpose programming language. This API constitutes a lingua franca for tools and VMs to manage modules.
At runtime, a module definition is represented by a ModuleDefinition object, and a module instance is represented by a Module object. A module archive identifies the physical representation of a module definition. It contains metadata, classes, and resources that are part of the module. A module archive is inherently self-contained, and it does not reference any resource externally. The correspondence between a module archive and a module definition is always one-to-one. Hence, a module archive deployed in the module system would yield a module definition at run time.
2.2 Module Name

Each module has a name that is a case-sensitive string. The name must be the fully qualified name of the module, according to Sections 6.2 and 6.7 of the Java Language Specification (JLS) [10]. The name is part of the identity of a module, and it is specified in the metadata of the module definition. To minimize conflicts between modules developed by different vendors, the name should follow the reverse domain name convention. The naming convention is not enforced by the module system, however. Example: Module names org.foo.xml com.wombat.webservice
10/2/06
12

Module Version Java Module System, Early Draft Fundamentals
2.3 Module Version

Each module has a version. The version must follow the versioning scheme described in Chapter 5: V ersioning. The module version is specified in the metadata of the module definition, and it is part of the modules identity. If the version is not present, the default is 0.0.0.0-default. Example: Module versions 1.0 2.3.4 3.2.1.9 5.6.7.8-b30-alpha
2.4 Module Identity

The identity of a module definition is represented by a modules name and version. Two ModuleDefinition objects are logically equivalent if their names and their versions are equal respectively. On the other hand, two Module objects are logically equivalent if their object identities are equal.
2.5 Module Metadata

Each module is self-describing through its metadata in the module definition. The metadata provides information about the module, including the name, the version, the imports that define its dependencies upon other modules, and the exports that define what classes and resources are visible to other modules. The metadata can be thought of as a tuple: (name, extensible-metadata, imports, class-exports, members[1]) where name: extensible-metadata: imports: class-exports: members: Name of the module. Version, main class, attributes, resource export list, etc. Imported modules. Class export list. List of classes that belong to the module membership.
The name, imports, class-exports, and members elements are mandatory, and the extensible-metadata element is optional.
[1]
The module membership is required by JSR-294 to enforce access control at the module level in the JVM. See Chapter 3.
13
October 2, 2006 1:33 am

Fundamentals Java Module System, Early Draft Module Export
Example: Content of the metadata in a module definition ( name= com.wombat.webservice extensible-metadata= [@Version(1.0)] imports= [ImportModule(org.foo.xml, @VersionConstraint(1.3.0)), ImportModule(org.foo.soap, @VersionConstraint(2.0.0+))] class-exports= [com.wombat.webservice.MainApp] members= [com.wombat.webservice.MainApp, com.wombat.webservice.PrivateClassA, com.wombat.webservice.PrivateInterfaceB]
The metadata is extensible through module attributes. Each module attribute is essentially a name-value pair of case-sensitive strings. Module attributes are generally defined and used by components at a higher layer on top of the module system. For instance, java.util.ServiceLoader [22] may define a service provider attribute for modules that contain service providers. If a module contains service providers, it should have the service provider attribute in its metadata. When a service is requested through java.util.ServiceLoader at run time, the system can then discover the available service providers from the modules in the repository. The format of the metadata will be defined in JSR-294: Improved Modularity Support in the Java Programming Language. See Chapter 3: Note on Development Module for more information.
2.6 Module Export

Each module has exports that define what classes and resources are visible externally to other modules.
10/2/06
14

Module Export Java Module System, Early Draft Fundamentals
This mechanism restricts classes and resources from being exposed outside the module unintentionally at build-time and at run time. For instance, one common use case is to prevent unwanted usage of the private APIs in the implementation. The export lists for classes and resources are separate. The class export list is for defining what classes are visible to other modules at build-time and after the module is interconnected at run time. The resource export list is for defining what resources are visible to other modules at run time after the module is interconnected. Both export lists are specified in the metadata of the module definition. Recall that the metadata can be thought of as a tuple: (name, extensible-metadata, imports, class-exports, members) The class export list is specified in the exports element of the metadata. Conceptually, a class export list can be thought of as follows: [type-1, type-2, .. type-n] where type-n is the name of the type to be exported from the module. Example: Class export list [com.wombat.webservice.ClassA, com.wombat.webservice.InterfaceB, com.wombat.webservice.ClassC] Export of an enclosing class does not imply export of its nested classes. The enclosing class and the nested classes must be exported separately. Example: Class export list, with enclosing class and nested classes [com.wombat.webservice.ClassA, com.wombat.webservice.ClassA$X, com.wombat.webservice.ClassA$Y] The resource export list is specified in the extensible-metadata element of the metadata. A resource is data, usually in the form of image, audio, text, etc. Conceptually, a resource export list can be thought of as follows: @ExportResources({resource-1, resource-2, .. resource-n}) where resource-n is the corresponding path of the resource to be exported from the module. Example: Resource export list // Export some graphics from the module. @ExportResources({icons/graphics1.jpg, icons/graphics2.jpg})
15
October 2, 2006 1:33 am

Fundamentals Java Module System, Early Draft Module Import
Moreover, a simple wildcard convention is supported in declaring exported resources in the metadata:
A path with a trailing /* matches all files contained in that directory. A path with a trailing /** matches all files in the directory, and recursively all files in subdirectories contained in that directory. Example: Resource export list with wildcard // Export all files under the icons directory, and // all files under the META-INF directory and // sub-directories. @ExportResources({icons/*, META-INF/**}) Import of a module does not imply re-export of classes and resources from the imported module. Classes that are re-exported from an imported module must be listed in the class export list of the importing module. Similarly, resources that are re-exported from an imported module must be listed in the resource export list of the importing module. Note that it is very important to evolve a modules exports compatibly between versions. When a new class or a new resource is exported in a version of a module, other importing modules may introduce dependency on it. Any incompatible change in the exports in future version of the module may cause some importing modules to break. Due to the implications on compatibility, the decision to determine the list of exports in a module should be made carefully. Besides, the degree of changes in the exports has direct influence on the module version under the versioning policy. For more specific information, see Section 5.1.1.
2.7 Module Import

Each module has imports that define its dependencies upon other modules. In this early draft, explicit module dependency is the only form of dependency supported in the imports. In an explicit module dependency, a module imports another module entirely based on a module name and a version constraint. The imports are specified in the imports element of the metadata.
2.7.1 Import with version constraint

An import can be thought of as: ImportModule(name, version-constraint) where name is the name of the imported module, and version-constraint is the versioning requirement constraining the import dependency. A version constraint is a version, a version range, or a combination of both. If no version constraint is present, the default is 0.0.0.0+. Details about the version constraint is described in Section 5.3.
10/2/06
16

Module Import Java Module System, Early Draft Fundamentals
Example: Import module with version constraint // Import the highest version of com.wombat.webservice ImportModule(com.wombat.webservice) // Import org.foo.xml version 1.3.0 precisely ImportModule(org.foo.xml, @VersionConstraint(1.3.0)) // Import org.foo.soap 2.0.0 or later ImportModule(org.foo.soap, @VersionConstraint(2.0.0+)) The version constraint is sufficient to express versioning requirements that are simple. However, for specialized or more complete customization, the import policy should be used to express the requirements instead.
2.7.2 Import policy

The import policy is a mechanism for a module instance to interconnect its imported modules with custom requirements through a piece of Java code. It is responsible for ensuring that instances of the associated module definition are indeed ready to use. The import policy is invoked when a module instance is initializing, and can test for arbitrary requirements. A typical requirement would be that a given import must be of a specific version or range of versions, but more elaborate conditions (e.g. arbitrary version range, version exclusion, platform dependency, module attribute matching, etc.) can be expressed, as the import policy is a method written in a general purpose programming language, and has access to all relevant metadata concerning the module instance it is validating. Example: Custom import policy // // Suppose the module definition imports org.foo.xml and // org.foo.soap respectively. // public class CustomImportPolicy extends ImportPolicy { // The module to be constructed private Module self; // Create an instance of the import policy. public CustomImportPolicy(Module self) this.self = self; } public void prepare() { // Lookup the repository. ModuleDefinition mdef = self.getModuleDefinition(); Repository repos = mdef.getRepository(); // Import org.foo.xml version 1.0.0 ModuleDefinition xml = repos.find(org.foo.xml, Query.parse(1.0.0));
17
October 2, 2006 1:33 am

Fundamentals Java Module System, Early Draft Distribution Format
ModuleDefinition soap = null; // Import org.foo.soap 2.3.4 on Linux. // Import org.foo.soap 3.0+ on other platforms. if (System.getProperty(os.name).equals(Linux)) soap = repos.find(org.foo.soap, Query.parse(2.3.4)); else soap = repos.find(org.foo.soap, Query.parse(3.0+)); // Interconnect all imported modules. self.addImports(xml.getInstance()); self.addImports(soap.getInstance());
Each module has zero or one import policy class specified in the extensible-metadata element of the metadata. Conceptually, an import policy class in the metadata can be thought of as follows: @ImportPolicyClass(import-policy-class) where import-policy-class is the name of the import policy class. Example: Import policy class in the module metadata @ImportPolicyClass(CustomImportPolicy) If a module has an import policy class, the class must be packaged in the module archive. Also, the import policy class can only depends on classes transitively from the core platform module or from the module itself. Please refer to Section 8.2.1.1 for the requirements on the import policy class. When a module instance is initializing at run time and if it has provided an import policy class, the module system will load and execute the code to interconnect the dependent modules. Otherwise, the module system will interconnect the dependent modules based on the version constraints in the imports. See Section 8.2.1 for more details.
2.8 Distribution Format

A module archive identifies the physical representation of a module definition. Each module archive contains metadata, classes, and resources. Some module archives also contain legacy JAR files and native libraries. The file format of the module archive is called JAM (JAva Module), and it is based on the JAR file format. A JAM file is essentially a jar file that contains a METADATA.module file under the MODULE-INF directory. During module development, a developer typically writes and compiles the metadata of the module definition and the Java code; he then packages the metadata, the classes, and other resources into a module archive for distribution.
10/2/06
18

Repository Java Module System, Early Draft Fundamentals
Details about the module archive are described in Chapter 6: Distribution Format.
2.9 Repository
The repository is a mechanism that enables side-by-side deployment of the module definitions in the module system. It offers capabilities such as storing, discovering, and retrieving module definitions of multiple versions. During module development, applications and libraries are built as module definitions and packaged as module archives for distribution. To deploy these applications and libraries on a new system, the module archives should be deployed into the repository for the module definitions to be discovered by the module system. The repository is described in details in Chapter 7: Repository.
2.10 Security
Modules are subjected to the standard Java security model. The standard Java security model has neither been extended nor relaxed for modules. Specifically, when a module runs as part of an untrusted applet then it will be subjected to the standard applet security sandbox and wont be allowed to read or write arbitrary files, or connect to arbitrary network hosts. However, when a module runs as part of a standard-alone Java application, or as part of a trusted (signed) applet, then it will be treated as a normal Java application and allowed normal access to files and network hosts. Although each module has a class export list to restrict types from being visible outside the module unintentionally at run time, it is still possible for a module to leak non-exported types to other modules dynamically, i.e. Java reflection can be used by code in other modules to discover the true type of an object that is passed via its public superclass or interface. Type leakage is an existing issue in the Java platform, and modules are subjected to the same rule. Even the private types in a module could be leaked out, the JVM will enforce access control in the development module (to be defined in JSR-294 [20]) when the methods of the types are invoked or the fields of the types are accessed through Java reflection. This is consistent with the existing Java reflection behavior in the Java platform - private types could be visible but they are not accessible. If a security manager is present, invocation on some of the APIs provided by the module system is checked with ModuleSystemPermission. For more information, see Section A.12.
2.11 Multi-Threading
A module should assume that it is running in a multi-threaded environment and that several different
19
October 2, 2006 1:33 am

Fundamentals Java Module System, Early Draft Platform Binding
threads may be simultaneously calling methods on the exported classes in the module if it is imported. It is the responsibility of each module developer to make sure that their modules behave properly under the multi-threaded condition they are expected to be used.
2.12 Platform Binding

Some modules are written specifically for a particular platform. Each platform-specific module must indicate its platform dependency by specifying the platform binding in the metadata of the module definition. See Section A.29. A module should have the same name and version across all platforms. Each platform-specific module with the same name and version should also export the same APIs, so the importing modules can declare dependency on the module in a generic way. At runtime, when a module definition is searched in the repository, the repository would simply return the appropriate platform-specific module based on the platform and the architecture of the system. If the platform binding of a module definition matches the platform and the architecture of the system, the module definition is instantiable. If the platform binding of a module definition does not match the platform and the architecture of the system, no module instance can be created by instantiating the module definition. If a module definition has no platform binding, it is then instantiable on all platforms.
2.13 Classloading
A single Java virtual machine (JVM) can access many modules. Within this JVM, modules can hide classes from other modules, as well as share classes with other modules. The mechanism to hide and share classes is the Java class loader that loads classes from a subset of the module-space using well-defined rules. Each module instance is associated with a class loader instance (i.e. module class loader). That class loader forms a class loading delegation network with other modules. For more information, classloading in the module system is described in Section 8.3.
2.14 Legacy JAR Files

A module definition may leverage existing classes and resources from a legacy JAR file by embedding the legacy JAR file in the module archive. See Section 6.2.4. The class export list may list the classes in the legacy JAR files embedded in the module archive; the resource export list may also list the resources contained in the embedded legacy JAR files. In addition, legacy JAR file can be brought to the module system directly by migrating it as a simple module archive. See Section 6.3 and Section B.6.
10/2/06
20

Native Libraries Java Module System, Early Draft Fundamentals
2.15 Native Libraries

A module definition may make use of native libraries, and these native libraries are packaged as resources in the module archive. See Section 6.2.3. This would operate as follows: When code in a module definition calls System.loadLibrary(), the call gets forwarded to the defining class loader of the calling class. The loader, in this case, knows how to locate the named library among the resources of its module definition. Note however that in general, one cannot support multiple instances of a given native library in a running process unless the underlying operating system supports it.
2.16 Executable Module

Each executable module has a main class, and it can be invoked by the Java runtime directly. When a module is executed, the launcher will instantiate a module instance from the module definition in the repository. After the module instance is fully initialized, the main class is then loaded from the class loader of the module instance and invoked accordingly. The main class can be specified in the metadata of the module definition, or the Main-Class: attribute of the manifest in the module archive. If the main class is present in both, the one in the metadata takes precedence. Example: Execute modules using Java launcher // Launch the highest version of com.wombat.webservice java -module com.wombat.webservice // Launch com.wombat.webservice version 1.2.0 or later java -module com.wombat.webservice:1.2.0+ Note that no significance should be attached to the new -module option in the launcher, which in the actual implementation is likely to differ from whats shown here.
2.17 Modules from the Java Runtime Environment

This specification defines the enabling technology for modularization, but it does not prescribe any approach on modularizing the Java Runtime internally. In other words, vendors will continue to have the freedom to innovate on how to best implement their JREs. The Java Runtime is required to expose a set of standard module definitions to the module system:
A core platform module definition for all public classes exported from the core SE platform
(i.e. public APIs in java.*, javax.*, etc.).
21
October 2, 2006 1:33 am

Fundamentals Java Module System, Early Draft Tools Support
A separate module definition for each bundled extension (e.g. CORBA, JAXP, etc.) that can be
overridden by the Endorsed Standards Override Mechanism.
A classpath module definition that exports all classes available from the application classloader typically returned by ClassLoader.getSystemClassLoader(). These are the classes on the application classpath and the extension classpath.
The actual name and version of the module definitions exposed from the JRE are expected to be defined in the Java SE 7 Expert Group, thus they are not described in this specification. It is possible that some JRE vendors may decide to modularize the core SE platform APIs further as multiple module definitions. However, the Java Runtime is still required to make a core platform module definition available to export the public APIs in the core SE platform entirely. It is also possible that some JRE vendors may decide to expose vendor-specific APIs as module definitions, e.g. com.sun.*. Example: Import the core platform module definition // Requires Java SE 7 or later. Lets assume the name of the // core platform module definition is java.se for now. // ImportModule(java.se, @VersionConstraint(1.7+)) // Requires Java SE 8 or later, thus the importing module // cant run on Java SE 7. // ImportModule(java.se, @VersionConstraint(1.8+)) Example: Import a vendor-specific module definition // Requires Suns Java2D APIs in Java SE 7. Lets assume the // name of the module definition is com.sun.java2d for now. // ImportModule(com.sun.java2d, @VersionConstraint(1.7.0)) When the metadata of the module definition is generated, the compiler would add the core platform module definition to the first of the import list in the metadata unless the core platform module definition has been manually declared in the import list. Hence, each module definition would import the core platform module definition by default.
2.18 Tools Support

Tools are considered implementation details, hence they are not specified in this specification. Nevertheless, we do anticipate many higher level tools and frameworks will build upon the module system to provide greater convenience and ease of use.
10/2/06
22

Source Code Java Module System, Early Draft Note on Development Module
Ch apt er 3
Note on Development Module
The development module will be defined in JSR-294: Improved Modularity Support in the Java Programming Language [20], and it is currently in progress. To help illustrate how the development module and the deployment module are integrated together in this specification, we use a pseudo approach to describe the development module. This chapter briefly describes the pseudo development module. Note that no significance should be attached to the form of the source code or the artifacts for the development module, which is likely to differ a good deal from whats shown here.
3.1 Source Code

We assume a development module is declared through a super package construct in the Java programming language: Example: Development module @Version(1.0) super package com.wombat.webservice { // imported module(s) @VersionConstraint(1.0+) // module annotation // module name
23
October 2, 2006 1:33 am

Note on Development Module Java Module System, Early Draft Compiling a Development Module
import org.foo.xml; @VersionConstraint(2.0+) import org.foo.soap; // exported class(es) export x.y.z.ClassA; export x.y.z.InterfaceB; // module membership x.y.z.ClassA; x.y.z.InterfaceB; x.y.z.ClassC; x.y.z.*;[2] ....
The pseudo development module above illustrates several properties:
Each development module has a name. A development module imports another development module by name. A development module exports classes from one or more Java packages. A development module defines the membership that consists of classes from one or more Java
packages.
A development module can be decorated through annotations.

Note that the Java programming language and virtual machine do not directly support a notion of versioning for classes or packages. We do not anticipate that the development module will offer such support either. Instead, this specification defines standard annotation types (e.g. Version, VersionConstraint) that can be used to decorate development modules. From the perspective of the language and the VM, the annotation has no specific semantic significance. However, the annotation will be preserved in the artifact after compilation per existing Java programming language semantics.
3.2 Compiling a Development Module

Compilation of a development module results in two kinds of binary artifacts. The first kind is familiar: the traditional class files, one for each class or interface in the source code. The second kind is new: this is the module file, which defines the members of a module. The JVM requires an authoritative source for module membership and module exports so that it can enforce runtime access control. The module file also provides the dependency information necessary for separate compilation. A module file can be thought of as a tuple:
[2]
A wildcard convention is expected to be defined in JSR-294 in declaring exported classes and module membership in development modules.
10/2/06
24

Integration between JSR-277 and JSR-294 Java Module System, Early Draft Note on Development Module
(name, extensible-metadata, imports, class-exports, members) The class-exports and members elements consist of zero or more type names. In contrast, the imports element consists of zero or more module name. The information in the module file is necessary for maintaining the development module semantics. Example: Module file METADATA.module: ( name= com.wombat.webservice extensible-metadata= [@Version(1.0)[3]] imports= [ImportModule(org.foo.xml, @VersionConstraint(1.0+)), ImportModule(org.foo.soap, @VersionConstraint(2.0+))] class-exports= [x.y.z.ClassA, x.y.z.InterfaceB] members= [x.y.z.ClassA, x.y.z.InterfaceB, x.y.z.ClassC][4] )
3.3 Integration between JSR-277 and JSR-294

There are many overlaps between the information in the development module and the deployment module, such as the name, the imports, and the exports. To allow better integration between the development module and the deployment module, we expect to design the module file to serve two roles: 1. It serves as an authoritative source for module membership and module exports that is necessary for maintaining the development module semantics. 2. It serves as the metadata of the module definition in the context of the deployment module. In other words, one of the artifacts after the compilation of a development module is the metadata of a module definition. The particular format of the module file (i.e. module definitions metadata) will be defined in JSR-294 [20].
3.4 Decorating a Development Module

This specification defines a set of metadata annotation types in the java.lang.module.annotation package that can be used to decorate development modules. Please refer to Appendix A.22 to A.33 for more details.
[3] [4] The metadata annotation types are under the java.lang.module.annotation package although they are not expanded in the examples. The wildcards in a development module are expected to be expanded by the compiler when the module file is generated.
25
October 2, 2006 1:33 am

Note on Development Module Java Module System, Early Draft Decorating a Development Module
Example: Decorate the development module with standard annotation types @Version(1.2.3) @ExportResources({ icons/graphics1.jpg, icons/graphics2.jpg, META-INF/**}) @ModuleAttributes({ @ModuleAttribute(name=org.opensource.license, value=GPL), @ModuleAttribute(name=java.magic.number, value=CAFEBABE)}) @PlatformBinding(platform=windows, arch=x86) @ImportPolicyClass(org.foo.xml.ImportPolicy) @MainClass(org.foo.xml.Main) super package org.foo.xml { // imported module(s) import org.w3c.dom.domLevel3; // exported class(es) export org.foo.xml.Main; // module membership org.foo.xml.Main; org.foo.xml.ImportPolicy; x.y.z.ClassA; x.y.z.InterfaceB; x.y.z.ClassC;
Example: Module file generated from the development module METADATA.module: ( name= org.foo.xml extensible-metadata= [@Version(1.2.3), @ExportResources({ icons/graphics1.jpg, icons/graphics2.jpg, META-INF/**}), @ModuleAttributes({ @ModuleAttribute(name=org.opensource.license, value=GPL), @ModuleAttribute(name=java.magic.number, value=CAFEBABE)}), @PlatformBinding(platform=windows, arch=x86), @ImportPolicyClass(org.foo.xml.ImportPolicy), @MainClass(org.foo.xml.Main)] imports= [ImportModule(org.w3c.dom.domLevel3)] class-exports= [org.foo.xml.Main] members= [org.foo.xml.Main, org.foo.xml.ImportPolicy, x.y.z.ClassA, x.y.z.InterfaceB, x.y.z.ClassC] )
10/2/06
26

Scenario 1: Creating New Modules Java Module System, Early Draft Scenarios
Ch apt er 4
Scenarios
To help illustrate how Java modules are developed and function, this chapter walks through a few sample scenarios. It is intended to show some ways modules may be used, but not to describe all possibilities. No significance should be attached to the form of the source code, the artifacts for the development module, or the command line options in the tools, which are likely to differ a good deal from whats shown here.
4.1 Scenario 1: Creating New Modules

In this scenario, a developer constructs two simple modules. One is a utility library, and the other is an application that depends on the utility library.
4.1.1 Develop the library

1. 2. The developer writes a number of Java classes that are part of the utility library. The developer writes a development module for the utility library, and specifies information such as the modules name, the modules to be imported, the classes to be exported, and the module membership. He also annotates the development module to specify additional information about the module definition, such as the modules version, etc.
27
October 2, 2006 1:33 am

Scenarios Java Module System, Early Draft Scenario 1: Creating New Modules
@Version(1.0.0) super package com.sun.cool.library { // module name // exported class(es) export com.sun.cool.library.ClassA; export com.sun.cool.library.InterfaceB; // module membership com.sun.cool.library.ClassA; com.sun.cool.library.InterfaceB; com.sun.cool.library.PrivateClassC; com.sun.cool.library.abc.moreStuff; } 3. // no import
The developer compiles the source files using the compiler. The compilation results in a module file and several class files. Specifically, one class file is generated for each class and interface in the source code, and one module file is generated for each development module. Recall that a module file is the metadata of a module definition, and it can be thought of as a tuple: (name, extensible-metadata, imports, exports, members) Below illustrates the content of the generated module file: METADATA.module: ( name= com.sun.cool.library extensible-metadata= [@Version(1.0.0)] imports= [] class-exports= [com.sun.cool.library.ClassA, com.sun.cool.library.InterfaceB] members= [com.sun.cool.library.ClassA, com.sun.cool.library.InterfaceB, com.sun.cool.library.PrivateClassC, com.sun.cool.library.abc.moreStuff] )
4.
The developer packages the module file, the classes and other resources into a module archive. com.sun.cool.library-1.0.0.jam: /META-INF/MANIFEST.MF /MODULE-INF/METADATA.module /com/sun/cool/library/ClassA.class /com/sun/cool/library/InterfaceB.class /com/sun/cool/library/PrivateClassC.class /com/sun/cool/library/abc/moreStuff.class /icons/coolgraphics1.jpg /icons/coolgraphics2.jpg /icons/coolgraphics3.jpg /icons/coolgraphics4.jpg
10/2/06
28

Scenario 1: Creating New Modules Java Module System, Early Draft Scenarios
4.1.2 Develop the application

1. 2. The developer writes a number of Java classes that compose the application. The developer writes a development module for the application. Since the application is executable, he also annotates the development module by specifying the main class among other information, including the requirement on the versioned dependency in the import. @Version(1.0.0) @MainClass(com.sun.cool.app.MainApp) super package com.sun.cool.app { // module name // imported module(s) @VersionConstraint(1.[0+]) // 1.0.0 <= x < 2.0.0 import com.sun.cool.library; // exported class(es) export com.sun.cool.app.MainApp; // module membership com.sun.cool.app.MainApp; com.sun.cool.app.PrivateClassA; com.sun.cool.app.PrivateInterfaceB; com.sun.cool.app.PrivateClassC; com.sun.cool.app.otherPrivateStuff;
} 3.
The developer compiles the source files using the compiler. Since there is a versioning requirement specified with the import, the compiler uses com.sun.cool.library that is greater than or equal to 1.0.0 within the 1.0 family (i.e. 1.0.0 <= x < 2.0.0) for compilation. Note that if no versioning requirement is specified, some compilers may automatically inject version constraints for the imports based on the versions of the imported modules used in the compilation. For example, if version 2.3.4 of com.sun.cool.library is the highest version in the repository and the developer provides no versioning requirement, the compiler may inject version constraints like 2.3.4+ in the imports in the module file. Some compilers may also choose to not inject any version constraint in the module file. We expect therell be some guidelines available for the compiler vendors to follow. Further, developer tools (IDEs etc.) may provide other way to configure how version constraints are generated. For instance, per-project setting may provide a versioning policy that when applied to the version number of the module found in the repository would produce a version constraint.
4.
The compilation results in a module file and several class files. The content of the generated module file is shown below: METADATA.module: ( name= com.sun.cool.app extensible-metadata= [@Version(1.0.0) @MainClass(com.sun.cool.app.MainApp)]
29
October 2, 2006 1:33 am

Scenarios Java Module System, Early Draft Scenario 2: Adding Bug Fixes
) 5.
imports= [ImportModule(com.sun.cool.library, @VersionConstraint(1.[0.0+]))] class-exports= [com.sun.cool.app.MainApp] members= [com.sun.cool.app.MainApp, com.sun.cool.app.PrivateClassA, com.sun.cool.app.PrivateInterfaceB, com.sun.cool.app.PrivateClassC, com.sun.cool.app.otherPrivateStuff]
The developer packages the module file, the classes and other resources into a module archive. com.sun.cool.app-1.0.0.jam: /META-INF/MANIFEST.MF /MODULE-INF/METADATA.module /com/sun/cool/app/MainApp.class /com/sun/cool/app/PrivateClassA.class /com/sun/cool/app/PrivateInterfaceB.class /com/sun/cool/app/PrivateClassC.class /com/sun/cool/app/otherPrivateStuff.class
4.1.3 Trying it out

1. 2. The developer deploys the application and the library into the repository of the module system. The developer then runs the application using the launcher. e.g., java -module com.sun.cool.app 3. The launcher finds the highest version of com.sun.cool.app in the repository to be 1.0.0, and it creates a module instance from this module definition. When the module instance is initializing and resolving its imports, the module system interconnects it with a module instance of com.sun.cool.library. After the module instance of com.sun.cool.app is initialized, the launcher loads and invokes the main class from the module class loader. The result is a running application that uses the utility library.
4.
4.2 Scenario 2: Adding Bug Fixes

In this scenario, the developer has received reports on a critical bug in the utility library, and he decides to develop and deliver a fix to his customers.

1. The developer identifies the bug in the utility library, and puts the fix in the source code.
10/2/06
30

Scenario 2: Adding Bug Fixes Java Module System, Early Draft Scenarios
2.
Because the change is a bug fix that doesnt affect compatibility, the developer follows the versioning policy and updates the version of the development module to 1.0.0.1. @Version(1.0.0.1) super package com.sun.cool.library { // module name // exported class(es) export com.sun.cool.library.ClassA; export com.sun.cool.library.InterfaceB; // module membership com.sun.cool.library.ClassA; com.sun.cool.library.InterfaceB; com.sun.cool.library.PrivateClassC; com.sun.cool.library.abc.moreStuff; } // no import
3.
The developer compiles the source files with the fix, and the compilation results in a module file and several class files. The content of the generated module file is shown below: METADATA.module: ( name= com.sun.cool.library extensible-metadata= [@Version(1.0.0.1)] imports= [] class-exports= [com.sun.cool.library.ClassA, com.sun.cool.library.InterfaceB] members= [com.sun.cool.library.ClassA, com.sun.cool.library.InterfaceB, com.sun.cool.library.PrivateClassC, com.sun.cool.library.abc.moreStuff] )
4.
The developer packages the module file, the classes and other resources into a module archive. com.sun.cool.library-1.0.0.1.jam: /META-INF/MANIFEST.MF /MODULE-INF/METADATA.module /com/sun/cool/library/ClassA.class /com/sun/cool/library/InterfaceB.class /com/sun/cool/library/PrivateClassC.class /com/sun/cool/library/abc/moreStuff.class /icons/coolgraphics1.jpg /icons/coolgraphics2.jpg /icons/coolgraphics3.jpg /icons/coolgraphics4.jpg
4.2.2 Trying it out

1. The developer deploys the new library (i.e. com.sun.cool.library 1.0.0.1) into the
31
October 2, 2006 1:33 am

Scenarios Java Module System, Early Draft Scenario 3: Adding New Features
repository. The repository already has com.sun.cool.library 1.0.0 installed. 2. 3.
com.sun.cool.app
1.0.0
and
The developer executes the application using the launcher. The launcher finds com.sun.cool.app in the repository, and it creates a module instance from this module definition. When the module instance is initializing and resolving its imports, the module system interconnects it with a module instance of com.sun.cool.library 1.0.0.1. After the module instance of com.sun.cool.app is fully initialized, the launcher loads and invokes the main class from the module class loader. The result is a running application that uses the new utility library which contains the fix. The application itself has not been changed.
4.
4.3 Scenario 3: Adding New Features

In this scenario, the developer decides to make several changes to the utility library:
Add a new feature to the library. Improve the performance of an existing feature by leveraging an open source project. The open
source project is a legacy library (i.e. not a module), and it will be bundled as an embedded legacy JAR file.
Export a few graphic files as resources from the module.

1. The developer writes a few Java classes for the new feature, and refactors a number of Java classes for the existing features in the library. The developer is confident that the changes should not introduce incompatibility, so he updates the version of the development module to 1.1.0 to reflect the magnitude of the changes. @Version(1.1.0) @ExportResources({ icons/coolgraphics1.jpg, icons/coolgraphics2.jpg}) super package com.sun.cool.library { // module name // exported class(es) export com.sun.cool.library.ClassA; export com.sun.cool.library.InterfaceB; export com.sun.cool.library.FeatureXClass; // module membership com.sun.cool.library.ClassA; com.sun.cool.library.InterfaceB; com.sun.cool.library.PrivateClassC; com.sun.cool.library.FeatureXClass;
10/2/06
2.
32

Scenario 3: Adding New Features Java Module System, Early Draft Scenarios
com.sun.cool.library.morePrivateClass; com.sun.cool.library.abc.moreStuff; } 3. // no import
The developer compiles the source files, and the compilation results in a module file and multiple class files. METADATA.module: ( name= com.sun.cool.library extensible-metadata= [@Version(1.1.0), @ExportResources({ icons/coolgraphics1.jpg, icons/coolgraphics2.jpg})] imports= [] class-exports= [com.sun.cool.library.ClassA, com.sun.cool.library.InterfaceB, com.sun.cool.library.FeatureXClass] members= [com.sun.cool.library.ClassA, com.sun.cool.library.InterfaceB, com.sun.cool.library.PrivateClassC, com.sun.cool.library.FeatureXClass, com.sun.cool.library.morePrivateClass, com.sun.cool.library.abc.moreStuff] )
4.
The developer packages the module file, the classes, and other resources (including the open source project as a legacy JAR file) into a module archive for distribution. com.sun.cool.library-1.1.0.jam: /META-INF/MANIFEST.MF /MODULE-INF/METADATA.module /MODULE-INF/lib/open-source-project.jar /com/sun/cool/library/ClassA.class /com/sun/cool/library/InterfaceB.class /com/sun/cool/library/PrivateClassC.class /com/sun/cool/library/FeatureXClass.class /com/sun/cool/library/morePrivateClass.class /com/sun/cool/library/abc/moreStuff.class /icons/coolgraphics1.jpg /icons/coolgraphics2.jpg /icons/coolgraphics3.jpg /icons/coolgraphics4.jpg
4.3.2 Trying it out

1. The developer deploys the new library (i.e. com.sun.cool.library 1.1.0) into the repository. The repository already has com.sun.cool.app 1.0.0 and com.sun.cool.library 1.0.0.1 and 1.0.0 installed previously.
33
October 2, 2006 1:33 am

Scenarios Java Module System, Early Draft Scenario 4: Making Incompatible Changes
2. 3.
The developer runs the application using the launcher. The launcher finds com.sun.cool.app from the repository, and it creates a module instance from this module definition. When the module instance is initializing and resolving its imports, the module system interconnects it with a module instance of com.sun.cool.library 1.1.0. After the module instance of com.sun.cool.app is fully initialized, the launcher loads and invokes the main class from the module class loader. The result is a running application that uses the new utility library which provides the new feature and the performance improvement. The application itself has not been changed.
4.
4.4 Scenario 4: Making Incompatible Changes

In this scenario, the developer decides to rewrite most of the utility library. Because the changes are not backwardly compatible, he also decides to update the application accordingly.

1. 2. The developer writes a number of Java classes that are part of the utility library. Since the changes introduce incompatibility, the developer follows the versioning policy and updates the version number to 2.0.0 to indicate the significant of the changes. @Version(2.0.0) @ExportResources({ icons/cleanGraphics1.jpg, icons/cleanGraphics2.jpg}) super package com.sun.cool.library { // module name // exported class(es) export com.sun.cool.library.ClassX; export com.sun.cool.library.InterfaceY; // module membership com.sun.cool.library.ClassX; com.sun.cool.library.InterfaceY; com.sun.cool.library.PrivateClassZ; com.sun.cool.library.morePrivateClass; com.sun.cool.library.def.moreStuff; } 3. // no import
The developer compiles the source files, and the compilation results in a module file and several class files. METADATA.module: ( name= com.sun.cool.library extensible-metadata=
10/2/06
34

Scenario 4: Making Incompatible Changes Java Module System, Early Draft Scenarios
) 4.
[@Version(2.0.0), @ExportResources({ icons/cleanGraphics1.jpg, icons/cleanGraphics2.jpg})] imports= [] class-exports= [com.sun.cool.library.ClassX, com.sun.cool.library.InterfaceY] members= [com.sun.cool.library.ClassX, com.sun.cool.library.InterfaceY, com.sun.cool.library.PrivateClassZ, com.sun.cool.library.morePrivateClass, com.sun.cool.library.def.moreStuff]
The developer packages the module file, the classes and other resources into a module archive. com.sun.cool.library-2.0.0.jam: /META-INF/MANIFEST.MF /MODULE-INF/METADATA.module /com/sun/cool/library/ClassX.class /com/sun/cool/library/InterfaceY.class /com/sun/cool/library/PrivateClassZ.class /com/sun/cool/library/morePrivateClass.class /com/sun/cool/library/def/moreStuff.class /icons/cleanGraphics1.jpg /icons/cleanGraphics2.jpg
4.4.2 Develop the application

1. 2. The developer updates a number of Java classes in the application to use the new utility library. Since the changes involve adding new features to the application, the developer follows the versioning policy and update the version number to 1.1.0. He also specifies a version constraint with the import to prevent the application from accidentally using an older and incompatible version of com.sun.cool.library. @Version(1.1.0) @MainClass(com.sun.cool.app.MainApp) super package com.sun.cool.app { // module name // imported module(s) @VersionConstraint(2.[0.0+]) import com.sun.cool.library; // exported class(es) export com.sun.cool.app.MainApp; // module membership com.sun.cool.app.MainApp; com.sun.cool.app.PrivateClassA; com.sun.cool.app.PrivateInterfaceB; com.sun.cool.app.PrivateClassC; com.sun.cool.app.otherPrivateStuff;
35
October 2, 2006 1:33 am

3.
The developer compiles the source files using the compiler. The versioning requirement specified in the import instructs the compiler to use a version of com.sun.cool.library that is greater than or equal to 2.0.0 within the 2.0 family (i.e. 2.0.0 <= x < 3.0.0). The compilation results in a module file and several class files. The content of the generated module file is shown below: METADATA.module: ( name= com.sun.cool.app extensible-metadata= [@Version(1.1.0), @MainClass(com.sun.cool.app.MainApp)] imports= [ImportModule(com.sun.cool.library, @VersionConstraint(2.[0.0+]))] class-exports= [com.sun.cool.app.MainApp] members= [com.sun.cool.app.MainApp, com.sun.cool.app.PrivateClassA, com.sun.cool.app.PrivateInterfaceB, com.sun.cool.app.PrivateClassC, com.sun.cool.app.otherPrivateStuff] )
4.
The developer packages the module file, the classes and other resources into a module archive. com.sun.cool.app-1.1.0.jam: /META-INF/MANIFEST.MF /MODULE-INF/METADATA.module /com/sun/cool/app/MainApp.class /com/sun/cool/app/PrivateClassA.class /com/sun/cool/app/PrivateInterfaceB.class /com/sun/cool/app/PrivateClassC.class /com/sun/cool/app/otherPrivateStuff.class
4.4.3 Trying it out

1. The developer deploys com.sun.cool.app 1.1.0 and com.sun.cool.library 2.0.0 into the repository. The repository already has com.sun.cool.app 1.0.0 and com.sun.cool.library 1.1.0, 1.0.0.1 and 1.0.0 installed from previous deployment. The developer executes the application using the launcher. e.g., java -module com.sun.cool.app 3. The launcher finds the highest version of com.sun.cool.app in the repository to be 1.1.0, and it creates a module instance by instantiating this module definition. When the module instance is initializing and resolving its imports, the module system interconnects it with a module instance of com.sun.cool.library 2.0.0. After the module instance of com.sun.cool.app is initialized, the launcher loads and invokes the main class from the module class loader.
2.
10/2/06
36

Scenario 4: Making Incompatible Changes Java Module System, Early Draft Scenarios
4. 5.
The new application (1.1.0) is running using the new utility library (2.0.0). The developer then runs the old application using the launcher. e.g., java -module com.sun.cool.app:1.0.0
6.
The launcher finds com.sun.cool.app 1.0.0 in the repository, and it creates a module instance by instantiating this module definition. When the module instance is initializing and resolving its imports, the module system interconnects it with a module instance of com.sun.cool.library 1.1.0. After the module instance of com.sun.cool.app is fully initialized, the launcher loads and invokes the main class from the module class loader. The old application (1.0.0) is running using the old utility library (1.1.0). The result illustrates the side-by-side deployment of multiple versions of applications and libraries on the same system.
7. 8.
37
October 2, 2006 1:33 am

10/2/06
38

Version Java Module System, Early Draft Versioning
Ch apt er 5
Versioning
This chapter describes the versioning scheme in the module system.
5.1 Version
The format of a version is defined as major[.minor[.micro[.update]]][-qualifier] where
major, minor, micro, and update are non-negative integers, i.e. 0 <= x <=
java.lang.Integer.MAX_VALUE.
qualifier is a string, and it can contain regular alphanumeric characters, -, and _. qualifier indicates a non-FCS (non-GA) release; an FCS (GA) version must not have
qualifier.
If minor is not specified, it has a default value of 0.
39
October 2, 2006 1:33 am

Versioning Java Module System, Early Draft Version
If micro is not specified, it has a default value of 0. If update is not specified, it has a default value of 0. If qualifier is not specified, it has a default value of an empty string.
The grammar for the version is as follows: version := simple-version ('-' qualifier)? simple-version:= major ('.' minor ('.' micro ('.' update)?)?)? major := digit+ minor := digit+ micro := digit+ update := digit+ qualifier := (alpha | digit | '-' | '_')+ Example: Versions and their parts Version
1 1.7 1.7-b61 1.7.0 1.7.0-b61 1.7.0.0 1.7.0.1 1.7.0.3 1.7.0.3-b32 1.7.1-b32-beta-1 1.7.1.3-b56_rc 1 1 1 1 1 1 1 1 1 1 1
major
0 7 7 7 7 7 7 7 7 7 7
minor
0 0 0 0 0 0 0 0 0 1 1
micro
0 0 0 0 0 0 1 3 3 0 3
update
qualifier
b61 b61 b32 b32-beta-1 b56_rc
When two versions are compared,
major, minor, micro, and update are converted into integers before comparison. qualifier is compared through string comparison. If characters in the qualifier have been encoded, qualifier should first be decoded
into Unicode string before comparison. Two versions are logically equivalent if and only if the major numbers, the minor numbers, the micro
10/2/06
40

Version Java Module System, Early Draft Versioning
numbers, the update numbers, and the qualifiers each are equal respectively. If the major numbers, the minor numbers, the micro numbers, and the update numbers of two versions are equal respectively but one version has a qualifier while the other has none, the latter is considered a higher version. Example: Pseudo algorithm that demonstrates versions comparison /** * Compare two versions. * * if v1 == v2, return 0. * if v1 < v2, return a negative number. * if v1 > v2, return a positive number. */ int compare(v1, v2) { // Compare identity if (v1 == v2) return 0; // Compare major version int result = v1.major - v2.major; if (result != 0) return result; // Compare minor version result = v1.minor - v2.minor; if (result != 0) return result; // Compare micro version result = v1.micro - v2.micro; if (result != 0) return result; // Compare update version result = v1.update - v2.update; if (result != 0) return result; // Is there a qualifier? if (v1.qualifierExists()) { if (!v2.qualifierExists()) return -1; else return v1.qualifier.compareTo(v2.qualifier); } return (!v2.qualifierExists()) ? 0 : 1;
Example: Versions comparison 1 < 1.2 < 1.3.1 < 2 1.6.0.5 < 1.7.0 < 1.7.0.1 < 1.7.0.2 3.4.5.6 < 3.4.5.7 == 3.4.5.07 < 3.4.6 7.8.9-b23 < 7.8.9 < 7.8.9.1-b10-alpha < 7.8.9.1-b18 < 7.8.9.1
41
October 2, 2006 1:33 am

Versioning Java Module System, Early Draft Version
4.3.2 == 4.3.2.0 < 4.3.2.1 Qualifiers could be a source of countless hard-to-spot bugs in versions comparison. Example: Unexpected result from versions comparison due to qualifiers // A beta release is earlier than an early access release. Oops! 1.7.0-beta < 1.7.0-ea < 1.7.0-rc // A b30 build is earlier than a b4 build. Oops! 5.6.7.8-b30 < 5.6.7.8-b4-alpha Developers could make the comparison predictable in well-defined order by normalizing the qualifiers. Example: Make versions comparison predictable by normalizing the qualifiers // Prefix milestone with build number. 1.7.0-b10-ea < 1.7.0-b30-beta < 1.7.0-b52-rc // Add leading zeros to build number. 5.6.7.8-b04-alpha < 5.6.7.8-b30
5.1.1 Versioning Policy

A versioning policy is a set of guidelines governing how version numbers should be used. The module system does not enforce any versioning policy, but it is still an important issue to address as the number of modules increase and the number of versions proliferate. Below is the recommended versioning policy for module developers:
Major version number should be incremented for making changes that are not backward com-
patible. It should also be incremented for making major changes that the software remains mostly backward compatible, although minor incompatibilities might be possible. When a major version number is changed, the minor and the micro version numbers should be reset to zero, and the update version number should be omitted.
Minor version number should be incremented for making medium or minor changes that the
software remains largely backward compatible, although minor incompatibilities might be possible. When a minor version number is changed, the micro version number should be reset to zero, and the update version number should be omitted.
Micro version number should be incremented for changing implementation details that the
software remains largely backward compatible, although minor incompatibilities might still be possible. When a micro version number is changed, the update version number should be omitted.
Update version number should be incremented for adding very limited number of critical bug
fixes in a highly compatible fashion.
10/2/06
42

Version Range Java Module System, Early Draft Versioning
Qualifier should be changed when the build number or the milestone is changed.
All changes visible externally through the exports of a module should be considered under the versioning policy, and they include anything that changes one of the followings:
Behavior of any method, class, or module. Changes in signature (that is, parameter lists) to a method. Adding, renaming, or removing class members. Adding, renaming, or removing class and interface methods. Adding, changing, or removing module member (classes and interfaces). Changes in visibility of members, and classes. Adding, renaming, or removing resources.
5.2 Version Range

A version range is a range of versions. There are three basic kinds of version ranges: open, family, and open within family. An open range matches any version (ignoring qualifier) greater than or equal to a specified version. It can be in one of the following formats (The + character means this version or later): a+ a.b+ a.b.c+ a.b.c.d+ // // // // a.0 or later a.b or later a.b.c or later a.b.c.d or later
A family range matches any version (ignoring qualifier) that is in a particular family, and it can be in one of the following formats (The * character means prefix match): a* a.b* a.b.c* a.b.c.d* // // // // a.* a.b.* a.b.c.* a.b.c.d (ignoring qualifier)
An open range within family matches any version (ignoring qualifier) greater than or equal to a specified version in a particular family. It can be in one of the following formats: a.[b.c.d+] a.b.[c.d+] a.b.c.[d+] // a.b.c.d or later within a family // a.b.c.d or later within a.b family // a.b.c.d or later within a.b.c family
43
October 2, 2006 1:33 am

Versioning Java Module System, Early Draft Version Range
The grammar for the version range is as follows: version-range := simple-version-range (';' simple-version-range)* simple-version-range := open-range | family-range | family-open-range open-range := simple-version '+' family-range := simple-version '*' family-open-range := major-range | minor-range | micro-range major-range := major'.''['minor('.'micro('.'update)?)?'+'']' minor-range := major'.'minor'.''['micro('.'update)?'+'']' micro-range := major'.'minor'.'micro'.''['update'+'']' Example: Version ranges and their meanings Version Range
1+ 1.7+ 1.7.2+ 1.7.2.1+ 1* 1.7* 1.7.2* 1.7.2.1* 1.[7+] 1.[7.2+] 1.[7.2.1+] 1.7.[2+] 1.7.[2.1+] 1.7.2.[1+]
Meaning (ignoring qualifier)

1.0 or later: 1.0 <= x 1.7 or later: 1.7 <= x 1.7.2 or later: 1.7.2 <= x 1.7.2.1 or later: 1.7.2.1 <= x 1.0 <= x < 2.0 1.7 <= x < 1.8 1.7.2 <= x < 1.7.3 1.7.2.1 <= x < 1.7.2.2 1.7 or later within 1.x family: 1.7 <= x < 2.0 1.7.2 or later within 1.x family: 1.7.2 <= x < 2.0 1.7.2.1 or later within 1.x family: 1.7.2.1 <= x < 2.0 1.7.2 or later within 1.7.x family: 1.7.2 <= x < 1.8 1.7.2.1 or later within 1.7.x family: 1.7.2.1 <= x < 1.8 1.7.2.1 or later within 1.7.2 family: 1.7.2.1 <= x < 1.7.3
It is possible to group two or more contiguous version ranges together as an union of ranges, using the ; character as separator. Example: Union of ranges 1.[2.3.1+];2*;3* ~ 1.2.3.1 <= x < 4.0 (ignoring qualifier)
10/2/06
44

Version Constraint Java Module System, Early Draft Versioning
5.3 Version Constraint

A version constraint is a mechanism in specifying versioning requirement in a module dependency. A version constraint is a version, a version range, or a combination of both. The grammar for the version constraint is defined below: version-constraint := simple-version-constraint (';' simple-version-constraint)* simple-version-constraint := version | version-range The version and the version range are really shorthands in establishing compatibility. If more artibrary range, version inclusion, or version exclusion is needed, the version and the version range can be used as building blocks to express the versioning requirement. Example: Import modules with version constraints // Import org.foo.xml version 1.3.0-b45-beta precisely ImportModule(org.foo.xml, @VersionConstraint(1.3.0-b45-beta)) // Import org.foo.soap version 2.0.0 or later ImportModule(org.foo.soap, @VersionConstraint(2.0.0+)) // Import the highest version of org.foo.soap between // x == 1.3.0 || x <= 2.0.0 ImportModule(org.foo.soap, @VersionConstraint(1.3.0;2.0.0+)) // Import org.foo.soap version with union of ranges // 1.3 <= x < 4.0 ImportModule(org.foo.soap, @VersionConstraint(1.[3+];2*;3*)) Example: Use version constraints programmatically // Get module org.foo.xml version 1.3.0 or later // Repository repos = Repository.getSystemRepository(); ModuleDefinition moduleDef = repos.find(org.foo.xml, Query.parse(1.3.0+)); Module module = moduleDef.getInstance(); // Get module org.foo.xml version 1.3 <= x < 4.0 moduleDef = repos.find(org.foo.xml, Query.parse(1.[3+];2*;3*)); module = moduleDef.getInstance();
45
October 2, 2006 1:33 am

Versioning Java Module System, Early Draft Version Constraint
Example: Use version constraint in tools // Execute com.wombat.webservice version 2.3.4 or later from the // repository. // java -module com.wombat.webservice:2.3.4+ When the version constraint is insufficient in specifying versioning requirement, the import policy might be used for further customization on testing arbitrary requirements. Please refer to Section 8.2.1 about the import policy.
10/2/06
46

Overview Java Module System, Early Draft Distribution Format
Ch apt er 6
Distribution Format
This chapter describes the distribution format of the module system.
6.1 Overview
A module archive is the physical representation of a module definition for packaging and distribution. The file format of the module archive is called JAM (JAva Module), and it is based on the JAR file format. A JAM file is essentially a jar file that contains a METADATA.module file under the MODULE-INF directory. There is no restriction on the name of the module archive; it can be any legal file name on a particular platform. However, it is still desirable to have a naming convention to minimize conflicts during deployment. The recommended naming convention of the module archive is: <name>-<version>[-<platform>-<arch>].jam where name: version: platform: Name of the module. Version of the module. Name of the platform for platform binding. It should be one of the possible values of the system property "os.platform[5]".
[5]
The system property os.platform is expected to be defined in Java SE 7. e.g. windows for Windows, linux for Linux.
47
October 2, 2006 1:33 am

Distribution Format Java Module System, Early Draft File Contents
arch:
Name of the architecture for platform binding. It should be one of the possible values of the system property "os.arch".
Example: Filenames of module archives org.foo.xml-1.3.jam com.sun.java3d-1.5.0.1-linux-x86.jam com.wombat.webservice-2.0.0.jam
6.2 File Contents

Conceptually, the general form of a module definition is a tuple: (Metadata, MemberClassDefinitions, Resources) Example: Content of a module archive that is a module definition com.wombat.webservice-2.0.0.jam /META-INF/MANIFEST.MF /MODULE-INF/METADATA.module /com/wombat/webservice/MainApp.class /icons/graphics1.jpg /icons/graphics2.jpg
6.2.1 Metadata
/MODULE-INF/METADATA.module Each module archive contains a METADATA.module file which is the module definitions metadata, and it should be stored under the MODULE-INF directory.
6.2.2 Resources
/<resource(s)> Resources (e.g. Java class files, graphics files, and others) that are part of the module definition should be stored according to their corresponding paths under the root directory in the module archive.
6.2.3 Native Libraries

/MODULE-INF/bin/<platform>/<arch>/<native-libraries> where platform: arch: Name of the platform for platform binding. It should be one of the possible values of the system property "os.platform". Name of the architecture for platform binding. It should be one of the possible values of the system property "os.arch".
10/2/06
48

Types of Module Archive Java Module System, Early Draft Distribution Format
Platform dependent native libraries that are part of the module definition should be stored under the MODULE-INF/bin/<platform>/<arch> directory in the module archive.
6.2.4 Legacy JAR Files

/MODULE-INF/lib/<legacy-jar-files> Legacy JAR files that are part of the module definition should be stored under the MODULE-INF/lib directory in the module archive. These legacy JAR files must use the .jar extension in their filename; otherwise, they are ignored by the module system.
6.3 Types of Module Archive

Module archives can be categorized into two different types: simple and complex. A simple module archive only contains metadata, classes, and resources. It has neither legacy JAR file nor native library. Example: Simple module archive org.foo.simple-1.0.0.jam: /META-INF/MANIFEST.MF /MODULE-INF/METADATA.module /org/foo/simple/SimpleApp.class /icons/arrow.jpg A simple module archive may use the .jar extension in its filename, in addition to the .jam extension. Furthermore, it may be used as a plain JAR file in older JRE releases; see Section B.6. Example: Simple module archive with .jar extension org.foo.simple-1.0.0.jar: /META-INF/MANIFEST.MF /MODULE-INF/METADATA.module /org/foo/simple/SimpleApp.class /icons/arrow.jpg A complex module archive contains legacy JAR files and/or native libraries, in addition to metadata, classes, and resources. A complex module archive must use the .jam extension in its filename. Example: Complex module archive with no platform binding org.foo.complex-1.0.0.jam: /META-INF/MANIFEST.MF /MODULE-INF METADATA.module bin/windows/x86/bar.dll
49
October 2, 2006 1:33 am

Distribution Format Java Module System, Early Draft Note on Manifest
bin/linux/x86/bar.so bin/solaris/x86/bar.so bin/solaris/sparc/bar.so lib/javahelp-1.2.0.jar /org/foo/complex/ComplexApp.class /icons/drawing.jpg Example: Complex module archive with platform binding for Windows on x86 org.foo.complex-1.0.0-windows-x86.jam: /META-INF/MANIFEST.MF /MODULE-INF METADATA.module bin/windows/x86/bar.dll lib/javahelp-1.2.0.jar /org/foo/complex/ComplexApp.class /icons/drawing.jpg
6.4 Note on Manifest

Like the JAR file format, the JAM file format has a manifest (i.e. MANIFEST.MF) that can be used to store extension and package related data. In general, the module system ignores all manifest entries in a JAM file, except the following: 1. The manifest entries for signing and verifying purposes: <digest-algorithm>-Digest[-<language>]: The name of this attribute specifies the name of the digest algorithm used to compute the digest value for the corresponding file entry. The value of this attribute stores the actual digest value. <digest-algorithm> specifies the algorithm name and <language> indicates to which language the digest value should be verified against. Magic: This is an optional attribute that can be used by applications to indicate how verifier should compute the digest value contained in the manifest entry. The value of this attribute is a set of comma separated context specific strings. 2. The Main-Class manifest entry for determining the main class of an executable module. If this attribute is present in the JAM manifest, its value defines the main class of a module which the launcher will load when it executes the module. The value must not have the .class extension appended to the class name. If the main class is also specified in the metadata of the module definition, the one in the metadata takes precedence. 3. The Sealed manifest entry for sealing a package. The sealing of packages are verified according to the Extension Mechanism Architecture [4].
10/2/06
50

Signed JAM File Java Module System, Early Draft Distribution Format
4. The manifest entries described by the Optional Package Versioning [3], including Extension-Name, Specification-Vendor, Specification-Version, Implementation-Vendor-Id, Implementation-Vendor, and Implementation-Version. These values of these entries will be available through the java.lang.Package. However, the JAM file containing these manifest entries is otherwise not recognized as an installed optional package by the module system. If a JAM file contains legacy JAR files, each legacy JAR file also has a manifest (i.e. MANIFEST.MF) that can be used to store extension and package related data. The module system ignores all manifest entries in an legacy JAR file.
6.5 Signed JAM File

The signing and signature verification for a JAM file are identical to those for the JAR file format in the Java SE platform. A JAM file can be signed and verified using, e.g., the standard jarsigner tool from the Java SE SDK. Specifically, a JAM file can be signed by one or more signers. The entries in a signed JAM file must be consistently signed by the same set of signers, otherwise the JAM file is considered invalid. If a signed JAM file contains legacy JAR files, the signature of each legacy JAR file is ignored, and the module system would pretend the entries in each legacy JAR file as if they are signed by the same set of signers in the JAM file.
6.6 Packed JAM file

Pack200 is a hyper-compression scheme for the JAR file format, and it is defined in JSR-200 [ 16 ]. The JAM file format is based on the JAR file format, hence developers may use Pack200 to further compress a module archive (i.e. a JAM file) for distribution. A packed module archive is a module archive that is Pack200-gzip-compressed. The module system supports packed module archives directly; a packed module archive is automatically unpacked if it is provided to the module system. The recommended naming convention of the packed module archive is: <name>-<version>[-<platform>-<arch>].jam.pack.gz where name: version: platform: arch: Name of the module. Version of the module. Name of the platform for platform binding. It should be one of the possible values of the system property "os.platform". Name of the architecture for platform binding. It should be one of the possible values of the system property "os.arch".
Example: Filenames of packed module archives org.foo.xml-1.3.jam.pack.gz com.sun.java3d-1.5.0.1-linux-x86.jam.pack.gz
51
October 2, 2006 1:33 am

Distribution Format Java Module System, Early Draft Packed JAM file
com.wombat.webservice-2.0.0.jam.pack.gz
10/2/06
52

Overview Java Module System, Early Draft Repository
Ch apt er 7
Repository
This chapter describes the repository of the module system.
7.1 Overview
The repository is a mechanism for storing, discovering, and retrieving module definitions in the module system. It allows more than one version of a module definition installed in isolation, and the installed module definitions are only loaded and instantiated when the module system needs them. These characteristics are central in enabling side-by-side deployment of the module definitions of multiple versions on the same system.
The module system has one or more repositories. The bootstrap repository is the only repository always present in the module system. The bootstrap repository always exposes the core platform module definition, and the module system restricts that no other repository may expose the core platform module def-
53
October 2, 2006 1:33 am

Repository Java Module System, Early Draft Overview
inition for security reason. Besides, the module system also utilize module definitions from other repositories. One example is a global repository. A global repository exposes module definitions that are deployed in a location on the system for sharing among different JVM processes. In most cases, a global repository requires administrative privileges to install and uninstall module definitions. Another example is an application repository. An application repository exposes module definitions that are specific to an application and is usually specified per JVM launch; user typically executes the launcher with a repository path as one of its command line options. Yet another example is an URL repository. An URL repository exposes module definitions from a specific codebase URL on the server. It downloads module definitions from the codebase URL on demand and caches them locally based on requests. Each repository has a name that is a case-sensitive string. The name of a repository is informational, and it is not uniquely identified in the module system. Each repository also has a source location that represents the origin of the module definitions. In most cases, the source location of a repository is its physical path on the system. For a global repository which exposes deployed module definitions from a system path, the source location is the system path. For an URL repository that exposes module definitions from a remote site, the source location is the codebase URL. The repository uses a delegation model to search for module definitions. Each repository has an associated parent repository. When a repository is requested to find a module definition, it will delegate the search to its parent repository before attempting to find the module definition in the repository itself. The bootstrap repository is the only repository that does not have a parent but may serve as the parent of other repositories.
The module system also defines the system repository as the repository used to start the application, and it is typically an application repository.
10/2/06
54

Construction Java Module System, Early Draft Repository
Moreover, repositories are extensible in the module system. New repositories could be added, and existing repositories (except the bootstrap repository) could be removed from the module system. A repository instance is represented by a Repository object at run time.
7.2 Construction
A repository instance is created by invoking one of the constructors in a Repository subclass. Whenever a repository instance is created, it is inactive. When constructing a new repository instance, it is critical to use a parent repository that is at least as secure than the one being constructed. This approach protects the module system from security attack through unexpected shadowing of the module definitions while searching is performed through repository delegation. For example, if a repository instance providing untrusted module definitions is specified as the parent repository of another repository instance that provides trusted module definitions, the trusted module definitions can be shadowed by the untrusted ones when the repository instances are searched. Hence, it is very important to chain the repository securely during construction.
7.3 Initialization and Shutdown

Each repository instance has a simple lifecycle: initialized and shutdown. A repository instance is initialized when the initialize method of the Repository object is invoked. After the repository instance has been initialized, it becomes active. A repository instance is shutdown when the shutdown method of the Repository object is invoked. The repository instance is inactive after the shutdown. A program can specify that a repository instance that has not been shutdown are to be invoked before the virtual machine exits. However, this is only an advisory to the Java runtime, and there is no particular guarantee that the shutdown method is ever invoked. By default, a repository instance is not shutdown on exit. Once shutting down a repository instance on exit has been enabled, it may be disabled again. See Section 8.1.4.
7.4 Search
Module definitions in a repository are available for search when its repository instance is active. A module definition is searched in a specific repository instance when the findModuleDefinitions method of the Repository object is invoked. A module definition is searched in multiple repository instances through delegation when the find method or the findAll method of the Repository object is invoked:
55
October 2, 2006 1:33 am

Repository Java Module System, Early Draft Install Module Definition
ModuleDefinition find(String name) ModuleDefinition find(String name, Query constraint); List<ModuleDefinition> findAll(); List<ModuleDefinition> findAll(Query constraint); The procedure for searching a module definition in a repository delegation is as follows: 1. If the repository has no parent repository, it is the bootstrap repository.
Invoke the findModuleDefinitions method of the Repository object that

represents the repository.
If the method completes normally, let C be the set of module definitions the method
returns. Complete this procedure normally with result C.
Otherwise, the method must have completed abruptly by throwing some exception E.
Complete this procedure abruptly with reason E. 2. The repository has a parent repository. Invoke the corresponding find* Repository object that represents the parent repository. method of the
3.
If the method in the parent repository has completed normally, let P be the set of module definitions the method returns. If the method in the parent repository has completed abruptly by throwing some exception E, complete this procedure abruptly with reason E. Invoke the findModuleDefinitions method of the Repository object that represents the repository. If the method completes normally, let C be the set of module definitions the method returns. 6.1 If one of the module definitions in C is the core platform module definition, throw a SecurityException. Let R be a set of module definitions that is a union of C and P. If the same module definition is found in both C and P, the one in P is preferred since it presumably comes from a more secure source. Complete this procedure normally with result R.
4.
5.
6.
6.2
6.3 7.
Otherwise, the method must have completed abruptly by throwing some exception E. Complete this procedure abruptly with reason E.
7.5 Install Module Definition

A module definition is installed into a repository instance when the install method of the Repository object is invoked.
10/2/06
56

Uninstall Module Definition Java Module System, Early Draft Repository
The installation of the module definition would fail if one of the following conditions occurs:
The repository instance is inactive or read-only. The module definition with the same name and version has already been installed in the repository.
The module definition is malformed, if one of the following conditions occurs: The filename of the module archive does not have .jam, .jam.pack.gz, or
.jar extension.
The module archive is not in the JAM file format. i.e. a jar file without the METADATA.module file under the MODULE-INF directory. signers.
The module archive is signed, but its entries are not consistently signed by same set of The metadata of the module definition does not follow the format of the module file. The module name is missing in the metadata of the module definition. The module version is specified in the metadata of the module definition, but it does
not follow the versioning scheme.
The module definition declares java.* as export in the metadata, but the installation
target is not the bootstrap repository.
Version constraints are specified with the imports in the metadata of the module definition, but they do not follow the versioning scheme. class is not present in the module archive.
The import policy class is specified in the metadata of the module definition, but the
If the module definition is installed successfully, it becomes available in subsequent search with the repository instance.
7.6 Uninstall Module Definition

A module definition is uninstalled from a repository when the uninstall method of the Repository object is invoked with the module definitions name and version. The uninstallation of the module definition would fail if the repository instance is inactive or read-only. If the module definition is uninstalled successfully, it becomes unavailable in subsequent search with the repository instance.
7.7 Reload Module Definitions

Module definitions in a repository instance is reloaded when the reload method of the Repository object is invoked. A repository instance may be reloaded only if it is active.
57
October 2, 2006 1:33 am

Repository Java Module System, Early Draft Repository Interchange Format
Support for repository reload is optional, however. If reload is supported in a repository instance, invoking the isReloadSupported method of the Repository object returns true. When a repository instance is reloaded in a JVM process, it should detect changes related to module definition in the repository and reflect these changes in the same JVM process:
A new module definition has been installed. The new module definition will become available
in subsequent search with the repository instance.
An existing module definition has been uninstalled. The existing module definition will be
unavailable for subsequent search with the repository instance. There is no behavior change to the users of the existing module definition and its corresponding module instances, however.
An existing module definition has been replaced (i.e. uninstall and install). The old module
definition will no longer be reachable via search with the repository instance. There is however no behavior change to the users of the old module definition and its corresponding module instances. Further, the new module definition will become available in subsequent search with the repository instance.
7.8 Repository Interchange Format

To facilitate sharing between different repositories, the module system defines a repository interchange format that specifies how module definitions are stored. The repository interchange format is a directory that contains module archives.
Example: Repository Interchange Format {repository-path}/com.sun.javahelp-1.3.jam {repository-path}/com.sun.java3d-1.5.0.1-linux-x86.jam {repository-path}/com.sun.java3d-1.5.0.1-solaris-sparc.jam {repository-path}/com.sun.java3d-1.5.0.1-windows-x86.jam {repository-path}/com.weather.weather-1.0.0.jam.pack.gz
10/2/06
58

Insulating Module Definitions Java Module System, Early Draft Repository
The policy for processing the module definitions in the repository interchange format is as follows:
Files whose names end in .jam, or .jam.pack.gz will be recognized. Files whose names
end in .jar will be recognized if it is a simple module archive. Files whose names end in .zip, or which have a particular magic number, regardless of filename extension, will be ignored.
Files will be considered regardless of whether or not they are "hidden" in the UNIX sense, i.e.,
have names beginning with '.'.
Subdirectories will not be searched recursively, i.e., if the directory is foo, the repository
implementation should only looks for JAM files in foo, not in foo/bar, foo/baz, etc.
The order in which the JAM files are enumerated is not specified and may vary from platform
to platform and even from moment to moment on the same machine. If there is more than one JAM file containing the same version of the module definition, the repository implementation should only load the first enumerated one, and ignore the others.
7.9 Insulating Module Definitions

A consequence of the repository delegation is that module definitions that are searchable in a parent repository are visible to its child repositories. Code in a module instance that is instantiated from a module definition in a child repository can reach other module definitions and their corresponding module instances in the same repository, as well as that are in the parent repositories. To offer isolation between codes in different module instances, e.g. Java applets, JNLP applications, or Java EE applications, a distinct repository instance should be used for each set of insulated module definitions. For example, using a different URL repository instance per codebase would insulate module definitions between different codebases in the security sandbox.
59
October 2, 2006 1:33 am

Repository Java Module System, Early Draft Local Repository
7.10 Local Repository

A repository instance that recognizes the repository interchange format is represented by a LocalRepository object at runtime. Example: Search module definition from the Repository Interchange Format programmatically // Create a repository instance. The source location is // interpreted by the repository implementation as a local // directory where the module definitions are stored in the // Repository Interchange Format. // URL url = new URL(file:///home/wombat/repos); Repository repos = new LocalRepository(wombat, url); // Initialize the repository instance. repos.initialize(); // Search org.foo.xml version 1.0.0 from the repository instance. repos.find(org.foo.xml, Query.parse(1.0.0));
7.11 URL Repository

An instance of an URL repository is represented by a URLRepository object at runtime. Each URL repository has a repository metadata file (i.e. repository-metadata.xml) that describes all the module definitions available. When an URL repository instance is initialized, the repository metadata file is downloaded from the codebase URL (i.e. the source location): {codebase}/repository-metadata.xml In the repository metadata file, each module definition is described with a name, a version, a platform binding, and a path (relative to the codebase URL where the module file, the module archive, and/or the packed module archive are located). Please refer to Section A.38 for more details. If no path and platform binding is specified, the default path is {name}/{version}. If the path is not specified and there is a platform binding, the default path is {name}/{version}/{platform}-{arch}. If the URL repository instance has successfully downloaded the repository metadata file, the module file (i.e. metadata) of each module definition is downloaded on demand: {codebase}/{path}/METADATA.module If a module definition is platform-specific, its module file is downloaded if and only if the platform binding described in the repository metadata file matches the platform and the architecture of the system. After the URL repository instance is fully initialized, it becomes active, and the module definitions are available for search. If a module instance is instantiated from a module definition that has no platform binding, the module archive is downloaded by probing in the following order: {codebase}/{path}/{name}-{version}.jam.pack.gz
10/2/06
60

URL Repository Java Module System, Early Draft Repository
{codebase}/{path}/{name}-{version}.jam On the other hand, if a module instance is instantiated from a platform-specific module definition, the module archive is downloaded by probing in the following order: {codebase}/{path}/{name}-{version}-{platform}-{arch}.jam.pack.gz {codebase}/{path}/{name}-{version}-{platform}-{arch}.jam To ensure the integrity of each separately-hosted module file is in sync with the module file within the module archive of the same module definition, they are compared bit-wise against each other after the module archive is downloaded. Example: Search module definition from codebase on remote site programmatically // Create a URL repository instance. The source location is // interpreted by the repository implementation as the codebase // where the module definitions are downloaded on demand based on // requests. // URL url = new URL(http://x.y.z/); Repository repos = new URLRepository("x.y.z", url); // Initialize the repository instance. repos.initialize(); // Search org.foo.xml version 1.3.0 from the repository instance. repos.find(org.foo.xml, Query.parse(1.3.0)); Example: Files hosted on the server side for the URL repository http://x.y.z/repository-metadata.xml http://x.y.z/org.foo.xml/1.3/METADATA.module http://x.y.z/org.foo.xml/1.3/org.foo.xml-1.3.jam.pack.gz http://x.y.z/soap2Linux/METADATA.module http://x.y.z/soap2Linux/org.foo.soap-2.0.0-linux-x86.jam http://x.y.z/soap2Other/METADATA.module http://x.y.z/soap2Other/org.foo.soap-2.0.0.jam Example: Content of the URL repository metadata file repository-metadata.xml: <?xml version="1.0" encoding="UTF-8"?> <modules> <module> <name>org.foo.xml</name> <version>1.3</version> </module> <module> <name>org.foo.soap</name> <version>2.0.0</version> <platform-binding> <platform>linux</platform> <arch>x86</arch> </platform-binding> <path>soap2Linux</path> </module>
61
October 2, 2006 1:33 am

Repository Java Module System, Early Draft Notes to Repository Implementors
<module> <name>org.foo.soap</name> <version>2.0.0</version> <path>soap2Other</path> </module> </modules> Example: URLs of the module files downloaded on Linux http://x.y.z/org.foo.xml/1.3/METADATA.module http://x.y.z/soap2Linux/METADATA.module Example: URLs of the module files downloaded on other platforms http://x.y.z/org.foo.xml/1.3/METADATA.module http://x.y.z/soap2Other/METADATA.module Example: URLs of the module archives probed on Linux http://x.y.z/org.foo.xml/1.3/org.foo.xml-1.3.jam.pack.gz http://x.y.z/org.foo.xml/1.3/org.foo.xml-1.3.jam http://x.y.z/soap2Linux/org.foo.soap-2.0.0-linux-x86.jam.pack.gz http://x.y.z/soap2Linux/org.foo.soap-2.0.0-linux-x86.jam Example: URLs of the module archives probed on other platforms http://x.y.z/org.foo.xml/1.3/org.foo.xml-1.3.jam.pack.gz http://x.y.z/org.foo.xml/1.3/org.foo.xml-1.3.jam http://x.y.z/soap2Other/org.foo.soap-2.0.0.jam.pack.gz http://x.y.z/soap2Other/org.foo.soap-2.0.0.jam
7.12 Notes to Repository Implementors

1. A repository implementation can be composed of other repositories. A composite repository is implemented by delegating the calls to other repositories, and it offers the illusion of one repository to the module system. initialize, shutdown, install, uninstall, and reload are operations that target a specific repository. A repository implementation must not delegate these operations its parent repository. On the other hand, a composite repository implementation may delegate these operations to one or more of its delegated repositories. It is possible that a JVM process may exit abnormally when a module definition is installed into a repository or uninstalled from a repository. A repository implementation should ensure that the install and the uninstall operations are performed transactionally to maintain the data integrity of the underlying storage.
2.
3.
10/2/06
62

Notes to Repository Implementors Java Module System, Early Draft Repository
4.
A repository implementation should not load module definitions and allocate resources until it is initialized. A repository implementation should release all outstanding locks and resources when it is shutted down. A repository implementation may need a mechanism to limit the number of versions of the same modules installed side by side in the same repository. For example, a repository may reside on a limited storage, or some enterprise may want to implement a policy to restrict the number of versions available to make their environment more manageable. Tools (e.g. IDEs or compilers) may use repository implementations that store modules in unpacked form to support compile and debug for development. When installing a module definition, it is possible that some repository implementations may check conditions that are not required by this specification. For example, a custom global repository which only accepts signed module archive generates exception if the module archive for installation is unsigned, or if the module archive is not signed by one of the pre-approved signers in an enterprise configuration. When uninstalling a module definition, it is possible that some repository implementations may check conditions that are not required by this specification. For instance, a repository implementation may generate exception if the module definition being uninstalled is vital to other importing modules in the same repository. Module definitions must be deployed into a repository, before the module system can discover and make use of it. This deployment step offers the repository implementation an opportunity to transform a module definition into a more efficient format for run time access. For instance,
5.
6.
7.
8.
9.
10.
Index can be built for all classes and resources in a module definition to optimize
classloading at runtime.
Native code can be generated for the frequently used classes in a module definition to
optimize runtime performance.
63
October 2, 2006 1:33 am

Repository Java Module System, Early Draft Notes to Repository Implementors
10/2/06
64

Execution Java Module System, Early Draft Runtime Support
Ch apt er 8
Runtime Support
This chapter describes the run time support of the module system.
8.1 Execution
This section specifies activities that occur during the execution of the module system.
8.1.1 Module System Start-up

The module system is started when the Java virtual machine starts execution. 1. The virtual machine instantiates and initializes a Repository instance to represent the bootstrap repository. The virtual machine instantiates a set of Repository instances to represent other repositories based on the configuration in the Java virtual machine and the configuration specified in the launcher. Each configured Repository instance is initialized by invoking the initialize method. The virtual machine sets the system repository to the Repository instance that is used to
2.
3.
65
October 2, 2006 1:33 am

Runtime Support Java Module System, Early Draft Execution
start the application. 4. If a module is specified in the launcher for execution, 4.1 The requested module definition is searched using the system repository, and a module instance is instantiated and initialized from the module definition. The system class loader is set to be the module class loader. The main class of the module is loaded from the system class loader and invoked.
4.2 4.3
8.1.2 Initialization of Module Instances

Initialization of a module instance requires careful synchronization, since some other thread may be trying to initialize the same module instance at the same time. There is also the possibility that initializing of a module instance may be requested recursively as part of the initializing of that module instance; for example, module A might import on module B, which might in turn import module A. The implementation of the module system is responsible for taking care of synchronization and recursive initializing. The Module object contains states that indicate one of the following situations:
This Module object is constructed but not initialized. i.e. NEW. This Module object is being prepared. i.e. PREPARING. This Module object is prepared and is being validated. i.e. VALIDATING. This Module object is prepared and validated successfully, but not yet fully initialized. i.e.
RESOLVED.
This Module object is fully initialized and ready to use. i.e. READY. This Module object is in an erroneous state, perhaps because initialization was attempted and
failed. i.e. ERROR.
10/2/06
66

Execution Java Module System, Early Draft Runtime Support
A module instance is in the NEW state before the initialization occurs. The procedure for initializing the module instance is then as follows: 1. The module instance enters the PREPARING state: 1.1 1.2 Create a module class loader and associate it with the module instance. If the module instance has not provided any import policy class, the module system provides a default import policy class using the versioning requirements specified in the imports of the module definition. If no version constraint is attached to an import, the highest version is assumed. The module instance is prepared by loading and invoking the import policy to interconnect the module instance with instances of the imported module definitions. See Section 8.2.1. If there is any error encountered when loading the import policy, throw an ImportPolicyError; if the import policy can not resolve an import based on the versioning requirements, throw a ResolveError. In either cases, change the state of the module instance to ERROR, and complete this procedure abnormally. Otherwise, the preparation of the module instance completes normally. Proceed to the next step.
1.3
1.4
1.5
2.
The module instance enters the VALIDATING state. 2.1 Shallow validation is performed to check the consistency requirement of the network of modules. See Section 8.2.2.1. If the validation fails, throw a ResolveError that is instantiated with ValidationException as the argument. Change the state of the module instance to ERROR, and complete this procedure abnormally. Otherwise, the validation of the module instance completes normally. Proceed to the next step.
2.2
2.3
3.
The module instance enters the RESOLVED state. 3.1 For each imported module instance, 3.1.1 Monitor the state of the imported module instance until it transitions to RESOLVED, READY, or ERROR. If the state of the imported module instance is ERROR, throw a ResolveError. Change the state of the module instance to ERROR, and complete this procedure abnormally.
3.1.2
3.2
If all imported module instances are either in RESOLVED or READY state, the imports are fully resolved. Set up the module class loader for classloading with the module class loaders from the imported module instances, and proceed to the next
67
October 2, 2006 1:33 am

Runtime Support Java Module System, Early Draft Resolving
step. 4. The module instance enters the READY state.
After the procedure is completed, the module instance is initialized successfully if it is in the READY state. Otherwise, the module instance fails to be initialized, and its state is ERROR. If the module instance has a main class, the Java runtime may invoke the main class only if the module instance is in the READY state.
8.1.3 Creation of New Module Instances

A new module instance is implicitly created when the following situation occurs:
Invocation of the getInstance method of the ModuleDefinition object creates a

new instance of the module definition represented by the ModuleDefinition object for which the method was invoked.
There is at most one module instance instantiated from each module definition per repository instance. A module definition can have multiple module instances through multiple repository instances. Whenever a new module instance is created, it is in the NEW state and it has not been initialized.
8.1.4 Module System Shutdown

The module system is shutdown when the Java virtual machine terminates. A program can specify that a repository instance that have not been shutdown are to be invoked before the virtual machine stops. The Java runtime shutdowns each repository instance that is marked to be shutdown on exit, by invoking the shutdown method of the Repository object. If an uncaught exception is thrown by the shutdown method, the exception is ignored and shutdown of that object terminates. The virtual machine imposes no ordering on shutdown method calls among repository instances. Shutdown may be called in any order or even concurrently. There is also no particular guarantee that the shutdown method is ever invoked.
8.2 Resolving
Resolving is a process that interconnects and validates a module instance with its imported modules through preparation and validation. A resolved module is a module instance that is interconnected and validated with its imported modules successfully after resolving. Resolving occurs when a module instance is initializing.
10/2/06
68

Resolving Java Module System, Early Draft Runtime Support
8.2.1 Preparation
Preparation involves invoking an import policy to interconnect a module instance with instances of the imported module definitions. Preparation occurs when a module instance is resolving during initialization. The procedure for preparing a module instance is as follows: 1. Load and define the import policy class in the module class loader of the module instance. The module class loader assigns a protection domain to the class. The protection domain is described in Section 8.3.3. Reflect a public constructor that takes a Module argument in the import policy class. If the constructor is absent, throw an ImportPolicyError. Instantiate the import policy by invoking the public constructor with the module instance as argument. If the construction have completed abruptly by throwing some exception E and if the class of E is not ImportPolicyError or one of its subclasses, then create a new instance of ImportPolicyError, with E as the argument. Return abruptly with reason E or its replacement. Reflect a public prepare method that has no return type and takes no argument in the import policy object. If such method is absent, throw an ImportPolicyError. Invoke the prepare method in the import policy object. If the execution of the prepare method completes normally, the module instance is prepared. Otherwise, the prepare method have completed abruptly by throwing some exception E and if the class of E is not ResolveError or one of its subclasses, then create a new instance of ResolveError, with E as the argument. Return abruptly with reason E or its replacement.
2.
3.
4.
5. 6.
7.
Note that the module instance is not yet interconnected with the imported modules when preparation occurs, and its module class loader can only load classes from the core platform module and the module instance itself during preparation.
8.2.1.1 Import Policy

An import policy is a piece of Java code that contains requirement logic to interconnect a module instance with instances of the immediate imported module definitions during the preparation phase. There are several requirements on an import policy class:
The class must extend java.lang.module.ImportPolicy. The class must be public and concrete.
69
October 2, 2006 1:33 am

The class must have a public constructor that takes a Module argument. The class must override the prepare method that has no return type and takes no argument. The class must only use classes transitively from the core platform module or from the module
itself. If an import policy class fails to conform one or more requirements above, initializing the module instance will result in an ImportPolicyError. In addition, there are several requirements on the logic in the import policy:
The import policy should hold a reference of the Module object that is passed in its constructor. This object represents the module instance that the import policy is associated with.
If a security manager is present, operations performed in the import policy are subjected to the
permissions in the protection domain of the import policy class. Protection domain is described in Section 8.3.3. If a module definition is downloaded from a remote host, its import policy should only make API calls that are permitted in the security sandbox environment.
When the prepare method of the import policy is called, it should perform the actions
below: 1 Invoke the getModuleDefinition method of the Module to get the ModuleDefinition object. Invoke the getRepository method of the ModuleDefinition to get the Repository object. For each imported module, calls the Repository object to get a ModuleDefinition of the imported module based on some versioning requirements. If a module definition cannot be found to satisfy an import, throw a ResolveError. For each imported module, make a module instance (i.e. Module) from the module definition by invoking the getInstance method of the ModuleDefinition. Invoke the addImports method of the Module object that was passed in the constructor, using the imported module instances from previous steps as arguments. The order of the imported module instances must follow the import order declared in the module definition. Otherwise, shallow validation will fail afterwards when it validates the imports of the module instance. Please refer to Section 8.2.2.1 for more details.
If an import policy fails to interconnect a module instance with its imported module instances, initializing the module instance will result in a ResolveError.
10/2/06
70

8.2.2 Validation
Validation is a process that checks the consistency requirement of a network of modules. There are two kinds of validations: shallow and deep.
8.2.2.1 Shallow Validation

Shallow validation checks that every module instance has been connected to all of its imports: 1. For every import clause in the corresponding module definition, an actual instance is provided, and that instances name matches the name declared in the import. 2. For all import clauses in the corresponding module definition, there is no overlap in the exported types. Shallow validation is the minimal consistency requirement of a network of modules, and it occurs when a module instance is resolving during initialization. If there is any error during shallow validation, ValidationException is thrown.
8.2.2.2 Deep Validation

Deep validation checks that every module instance has been connected to all of its imports, and that the module network does not contain inconsistent namespaces. While the JVM will catch such inconsistencies at runtime, one really wants to check that such a situation cannot occur at run time. The simplest way to implement deep validation is to load all classes and interfaces whose names are referenced by a module instance, and ensure that each is uniquely defined. For a specific module instance, a namespace is created by loading the instances members; for each of these types, all of types mentioned in their signatures are loaded. Similar procedure is applied for each import: a namespace is created for each imported module, and all the types mentioned in the signatures of the types that the original module is importing are loaded. Deep validation succeeds if there is no contradiction between namespace of the original module and that of the imported modules. Support for deep validation is optional in the module system. If deep validation is supported in an implementation of the module system, invoking the supportsDeepValidation method of the Module object returns true. Deep validation does not occur when a module instance is resolving during initialization. Instead, deep validation is performed on a module instance only if the deepValidate method of the Module object is invoked; if the validation fails, it throws a ValidationException.
8.2.3 Scenarios
To help illustrate how modules are resolved with their imports, this section walks through a few sample scenarios. It is intended to show some ways modules may be resolved together, but not to describe all possibilities. Note that this section is intended to be illustrative rather than prescriptive.
71
October 2, 2006 1:33 am

8.2.3.1 Scenario 1: Resolve imports with open range version constraints

Example: Module definitions in the repository @Version(1.0) super package A { import B; import C; ... } @Version(1.0) super package B { @VersionConstraint(1.0+) import D; ... } @Version(1.0) super package C { @VersionConstraint(1.0+) import D; ... } @Version(1.0) super package D { ... } @Version(1.1) super package D { ... } Example: Import dependencies between module instances at runtime
There is no version constraint specified with the import, so 0.0.0.0+ is assumed. The highest version of B and C in the repository that satisfies As version constraint is 1.0. The highest version of D in the repository that satisfies Bs and Cs version constraint is 1.1. After resolving, module instances of B and C both interconnect with the same module instance of D.
10/2/06
72

8.2.3.2 Scenario 2: Resolve imports with the same specified version

Example: Module definitions in the repository @Version(1.0) super package A { import B; import C; ... } @Version(1.0) super package B { @VersionConstraint(1.0) import D; ... } @Version(1.0) super package C { @VersionConstraint(1.0) import D; ... } @Version(1.0) super package D { ... } @Version(1.1) super package D { ... } Example: Import dependencies between module instances at runtime
The highest version of B and C in the repository that satisfies As version constraint is 1.0. The highest version of D in the repository that satisfies Bs and Cs version constraint is 1.0. After resolving, module instances of B and C both interconnect with the same module instance of D.
73
October 2, 2006 1:33 am

8.2.3.3 Scenario 3: Resolve imports with different versions

Example: Module definitions in the repository @Version(1.0) super package A { import B; import C; ... } @Version(1.0) super package B { @VersionConstraint(1.0+) import D; ... } @Version(1.0) super package C { @VersionConstraint(1.0) import D; ... } @Version(1.0) super package D { ... } @Version(1.1) super package D { ... } Example: Import dependencies between module instances at runtime
The highest version of B and C in the repository that satisfies As version constraint is 1.0. The highest version of D in the repository that satisfies Bs version constraint is 1.1, while that for Cs version constraint is 1.0. After resolving, module instances of B and C each interconnect with module instance of D of different versions.
10/2/06
74

Classloading Java Module System, Early Draft Runtime Support
8.3 Classloading
A module class is an instance of Class that is a member of a development module. A legacy class is defined as a Class instance that does not have any development module membership. A module class loader is an instance of ClassLoader that is used to load classes and resources from a module instance instantiated from a module definition in a repository. Each Module instance instantiated from module definition in the repository has a single module class loader instance for loading classes and resources.
8.3.1 Search Order

Unlike typical classloading which follows the single-parent delegation model, each module class loader instance searches classes and resources through the multiple-siblings delegation.
More specifically, each module class loader instance searches classes and resources from:
The imported module instance if it exports or re-exports the requested classes or resources. The initiating module instance itself.
The module class loader instance never consults the parent class loader in the search.
75
October 2, 2006 1:33 am

Runtime Support Java Module System, Early Draft Classloading
The search order between the imported module instances is based on the declarative order in the imports of the initiating module instance. Once a module instance is fully initialized, the search order is fixed for the lifetime of the associated module class loader instance. If a module instance is instantiated from a module definition that has one or more embedded legacy JAR files in its module archive (i.e. JAM file), classes and resources directly in the module archive are searched first, before those in the embedded legacy JAR files are searched. The order in which the embedded legacy JAR files are searched is not specified and may vary from platform to platform.
8.3.2 Classes and Resources Visibility

Each module definition has exports that determines what classes and resources are visible to other modules after its instance is interconnected, and the mechanism for accessing classes and resources from a module instance is through its class loader (i.e. module class loader). The visibility policy is enforced by the module class loader as follows:
8.3.2.1 Loading classes

When a class is loaded through java.lang.ClassLoader.loadClass(String) the module class loader returns a Class object. The module class loader will enforce the following policy: 1. All classes in a module instance are visible to classes from the same module instance. 2. Only exported and re-exported classes from an imported module instance are visible. When methods of the Class object are invoked, the Java virtual machine will leverage the class export list to enforce access control based on the development module membership. The access control in the development module will be defined in JSR-294: Improved Modularity Support in the Java Programming Language [20].
8.3.2.2 Loading resources

A resource is data, such as image, audio, text, etc. When a resource is requested through java.lang.ClassLoader.getResource(String) java.lang.ClassLoader.getResourceAsStream(String) java.lang.ClassLoader.getResources(String) the result is either a URL of the resource, or a Enumeration that enumerates the URL of the resource. The module class loader will enforce the following policy: 1. All resources in a module instance are visible to classes from the same module instance. 2. Only exported and re-exported resources in a module instance are visible to classes from a different module instance.
10/2/06
76

Classloading Java Module System, Early Draft Runtime Support
If the requested resource is visible to the caller, the module class loader should proceed with returning the resource as part of the result. Otherwise, the requested resource is non-exported to the caller, and the module class loader should pretend the resource does not exist. Resources in a module definition are read-only, hence opening a resource URL as an output stream always results in java.net.UnknownServiceException. Opening a resource URL as an input stream may also fail with java.io.IOException if the module definition has been uninstalled from the repository when the resource URL is actually opened.
8.3.3 Classes and Protection Domain

Each Class instance in a module instance is loaded by its module class loader, and it is associated with a protection domain when the module class loader defines it. The code source of a class in a module instance is based on the origin of the module definition and the certificates associated with the class in the module archive. The origin of the module definition is a URL in the following form: module:<repos-name>[/<source>]!/<module-name>/<module-version> where repos-name: Name of the repository. source: Source location of the repository. module-name: Module name. module-version: Module version. Example: The origin of module definitions module:bootstrap!/javax.xml/1.3 module:x.y.z/http://x.y.z/!/javax.xml/1.3 The protection domain of a class is determined by the code source and the permission set; the permission set is obtained by consulting the system security policy with the code source.
8.3.4 Classloading Requirements for Java SE 7

The classloading architecture will be revisited in Java SE 7 to support classloading interaction in the module system. Due to the search model in classloading in the module system, it imposes the following requirements to the classloading architecture: 1. Searches will cross loader boundaries with greater frequency. Rationale: The classloading model in JSR-277 is multiple-siblings delegation instead of the typical single-parent delegation. 2. Searches will recurse between loader boundaries with greater frequency.
77
October 2, 2006 1:33 am

Runtime Support Java Module System, Early Draft Classloading
Rationale: Having custom class loaders that search recursively between loader boundaries was possible prior to Java SE 7 but they were not easy to write. In Java SE 7, JSR-294 will enable developers to write modules in a very simple manner, including modules that have cyclic dependencies, without requiring custom class loader to be written manually. Hence, the ease of development of JSR-294 increases the likelihood around class loaders in JSR-277 being set up in cyclic delegation between some module instances. 3. Searches that cross loader boundaries will occur from multiple threads, with similar frequency. Rationale: In the concurrency model of the existing classloading architecture, searches that cross loader boundaries from multiple threads could lead to deadlocks in some situations. Since it will be quite normal to search across loader boundaries from multiple threads in the module system, the issue around parallelism should be revisited.
10/2/06
78

Dependencies of Modules on Legacy JAR Files Java Module System, Early Draft Migration
Ch apt er 9
Migration
The Java Module System supports independent migration of each component of an application from a JAR file to a module. This chapter outlines the migration guidelines.
9.1 Dependencies of Modules on Legacy JAR Files

A component can be migrated to the module system before all dependent components are migrated. To declare its dependency on legacy JAR files from the dependent components, the module imports the classpath module definition from the Java Runtime. This allows the module to access all classes present in the application classpath and the extension classpath. The classpath module definition is described in more details in Section 2.17. The module instance of the classpath module definition is a singleton, which is shared by all modules that import it. This preserves the semantics of the traditional classpath, where the classes are shared by all components of the application. Example: Import classpath module definition // Lets assume the name of the classpath module definition // is java.classpath for now. ImportModule(java.classpath)
79
October 2, 2006 1:33 am

Migration Java Module System, Early Draft Dependencies of Legacy JAR Files on Modules
For the component to work properly after the migration, deployers need to make sure the legacy JAR files from the dependent components are present on the classpath or in the extension directory when the component is used. An alternative migration approach is to bundle the dependent components within the module as embedded legacy JAR files. This is a change in semantics from the traditional classpath, so this approach should be used with care.
9.2 Dependencies of Legacy JAR Files on Modules

A JAR file can continue to work unaltered after a dependent component has been migrated to the module system and deployed into a repository. To enable that, the Java Runtime will provide a mechanism that allows selected modules from the repository to appear as an installed extension. This makes it possible for a module and a legacy JAR file to access a shared component that has been migrated to module system. Example: Application module A depends on module M and a legacy JAR file J. Each of A, M, and J depend on library L, which is also present in module form. The modules A, M, and L are all installed in the repository and J is in the extension directory. The module system is configured to make L also available as an extension. During startup, the module system creates instances of the module A, M, and L. It also sets up the module class loaders of A and M, to import L. The platform also creates an extension class loader which includes the module class loader created for L in addition to the JAR files in the extension directory. That means references of J to classes in L will be resolved via the module class loader of L. This ensures that if A, M, and J access classes of L, they all access the same Class instances. Instances of L's classes can be passed between the modules components and legacy JAR components without conflicts.
9.3 Dependencies of Legacy JAR Files on Extensions

A component may declare dependencies on one or more extensions (a.k.a optional packages). Example: JAR manifest with extension dependencies Extension-List: javahelp javahelp-Extension-Name: javax.help javahelp-Specification-Version: 1.0 javahelp-Implementation-Version: 1.0.3 javahelp-Implementation-Vendor-Id: com.sun
10/2/06
80

Dependencies of Legacy JAR Files on Extensions Java Module System, Early Draft Migration
In Java Plug-in, the dependencies are checked against extensions available in the extension class loader. In Java EE platform specification (v5.0 at the moment), it does not specify how the dependencies are checked, but it is generally presumed to be a vendor-specific mechanism other than checking the extensions available in the extension class loader. A module definition can declare itself as an extension using module attributes. The names of the extensions module attributes are loosely based on the extension attributes described in the Optional Package Versioning [3]:
extension.name: The value of this attribute specifies a name for the extension contained
in the module definition. The name should be a unique identifier such as the name of the main package comprising the extension.
extension.specification.vendor: The value of this attribute identifies the company that originated the specification to which the extension conforms.
extension.specification.version: The value of this attribute specifies the version number of the specification to which the implementation conforms.
extension.implementation.vendor.id: This attribute's value is a unique identifier for the company that produced the extension implementation in the module definition.
extension.implementation.vendor: This attribute's value is the name of the com-
pany that produced the implementation of the extension. This attribute should be used only for such purposes such as displayable text.
extension.implementation.version: This attribute indicates the vendor's version

number for the implementation of the extension. Example: A development module as an extension @Version(1.2.3) @ModuleAttributes({ @ModuleAttribute(name=extension.name, value=javax.help), @ModuleAttribute(name=extension.specification.vendor, value=Sun Microsystems, Inc), @ModuleAttribute(name=extension.specification.version, value=1.0), @ModuleAttribute(name=extension.implementation.vendor.id, value=com.sun), @ModuleAttribute(name=extension.implementation.vendor, value=Sun Microsystems, Inc), @ModuleAttribute(name=extension.implementation.version, value=1.2.3), }) super package com.sun.javahelp ... Example: Discover available extensions programmatically // Build query for all module definitions that have the module // attribute extension.name. Query query = Query.ANY().attributeEquals(extension.name);
81
October 2, 2006 1:33 am

Migration Java Module System, Early Draft User Defined Class Loaders
// Discover all extensions in the system repository. Repository repos = Repository.getSystemRepository(); List<ModuleDefinition> extensions = repos.findAll(query); This approach offers a standard way for a module definition to declare itself as an extension and to be discovered programmatically at run time. Existing codes that check extension dependencies in legacy JAR files in various environments should be updated accordingly to support this approach.
9.4 User Defined Class Loaders

Some applications create class loaders at runtime, e.g. URLClassLoader or an application specific subclass of ClassLoader. While a portion of these applications may migrate to modules and simply make use of the module class loaders, others will continue to define their own class loaders. Such applications can interact with the module system by calling its reflective APIs to lookup module definitions from the repository and to create a module instance. A custom class loader can then delegate to the module class loader of the module instance.
9.5 Limitations
As legacy JAR files do not support all the features of modules, there are a few limitations on module configurations which include legacy JAR files: 1. Only one version of a JAR file can be placed on the classpath per JVM launch and it becomes visible to all modules that import the classpath module definition. Only one version of a given module can be made available as an installed extension to legacy JAR files.
2.
In order to avoid these limitations, we recommend that JAR files are migrated to modules as soon as convenient. Also, note that library L is installed in the repository while the same of a different version of L is also being present on the classpath can lead to problems. Modules that import L will see the classes defined by the module class loader, which legacy JAR files will have the classes of L defined by the application class loader. This conflict can be avoided by configuring L to be available as an installed extension as described in Section 9.2. However, to reduce the likelihood of this occurrence, it is recommended to limit the legacy JAR files on the classpath and in the extension directory to those required to run the application. Deep validation may be helpful in determining which files are required and if there are any conflicts present.
10/2/06
82

Limitations Java Module System, Early Draft Related Documents
Chapter 10
Related Documents
[ 1 ]
Java Product Versioning Specification. http://java.sun.com/j2se/1.5.0/docs/guide/versioning/spec/versioningTOC.html. Sun supported Specification-Version and Implementation-Version format. http://java.sun.com/j2se/1.5.0/docs/guide/plugin/developer_guide/version_format.html. Optional Package Versioning. http://java.sun.com/j2se/1.5.0/docs/guide/extensions/versioning.html. The Extension Mechanism. http://java.sun.com/j2se/1.5.0/docs/guide/extensions/spec.html. JAR File Specification. http://java.sun.com/j2se/1.5.0/docs/guide/jar/jar.html. Signed JAR File. http://java.sun.com/j2se/1.5.0/docs/guide/jar/jar.html#Signed%20JAR%20File. Java Platform, Standard Edition (Java SE). http://java.sun.com/javase. Java Platform, Enterprise Edition (Java EE). http://java.sun.com/javaee. The Java Virtual Machine Specification, Second Edition, by Tim Lindholm, Frank Yellin. http://java.sun.com/docs/books/vmspec/2nd-edition/html/VMSpecTOC.doc.html The Java Language Specification, Third Edition, by Bill Joy, Guy Steele, James Gosling, Gilad Bracha. http://java.sun.com/docs/books/jls/third_edition/html/j3TOC.html JSR-56: Java Network Launching Prototocol and APIs. http://jcp.org/en/jsr/detail?id=56.
[ 2 ]
[ 3 ]
[ 4 ] [ 5 ] [ 6 ]
[ 7 ] [ 8 ] [ 9 ]
[ 10 ]
[ 11 ]
83
October 2, 2006 1:33 am

Related Documents Java Module System, Early Draft Limitations
[ 12 ]
JSR-160: Java Management Extensions (JMX) Remote API 1.0. http://www.jcp.org/en/jsr/detail?id=160. JSR-174: Monitoring and Management Specification for the Java Virtual Machine. http://www.jcp.org/en/jsr/detail?id=174. JSR-175: A Metadata Facility for the Java Programming Language. http://jcp.org/en/jsr/detail?id=175. JSR-199: Java Compiler APIs. http://jcp.org/en/jsr/detail?id=199. JSR-200: Network Transfer Format for Java Archives. http://jcp.org/en/jsr/detail?id=200. JSR-250: Common Annotations for the Java Platform. http://www.jcp.org/en/jsr/detail?id=250. JSR-277: Java Module System. http://jcp.org/en/jsr/detail?id=277. JSR-291: Dynamic Component Support for Java SE. http://jcp.org/en/jsr/detail?id=291. JSR-294: Improved Modularity Support in the Java Programming Language. http://jcp.org/en/jsr/detail?id=294. Developing Modules for Development. http://blogs.sun.com/roller/page/gbracha?entry=developing_modules_for_development. java.util.ServiceLoader. http://download.java.net/jdk6/docs/api/java/util/ServiceLoader.html. Java Security Policy File. http://java.sun.com/j2se/1.5.0/docs/guide/security/PolicyFiles.html. RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax. http://www.ietf.org/rfc/rfc2396.txt. OSGi Service Platform Release 4, Core Specification. http://www.osgi.org/. Eclipse Plug-in Architecture. http://www.eclipse.org/articles/Article-Plug-in-architecture/plugin_architecture.html. NetBeans Module Architecture. http://www.netbeans.org/download/dev/javadoc/org-openide-modules/org/openide/modules/doc-files/api.html. .NET Assemblies. http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconassemblies.asp. Ivy Repository. http://ivyrep.jayasoft.org/. Maven Repository. http://maven.apache.org/.
[ 13 ]
[ 14 ]
[ 15 ] [ 16 ] [ 17 ]
[ 18 ] [ 19 ] [ 20 ]
[ 21 ]
[ 22 ] [ 23 ] [ 24 ]
[ 25 ] [ 26 ]
[ 27 ]
[ 28 ]
[ 29 ] [ 30 ]
10/2/06
84

Limitations Java Module System, Early Draft Glossary
Ch apt er 11
Glossary
Application Repository A repository that is specific to an application and is usually specified per JVM launch. See Section 7.1. Bootstrap Class Loader A class loader that loads system classes, such as classes in the java.* packages. Bootstrap Repository A repository that exposes the core SE platform as module definition. This is the only repository always present in the module system. See Section 7.1. Class Export List Defines what classes in a module are visible externally. It is used at build-time and is enforced at run time after the module instance is interconnected. See Section 2.6. Complex Module Archive A type of module archive that contains metadata, classes, resources, legacy JAR files, and native libraries. See Section 6.3.
85
October 2, 2006 1:33 am

Glossary Java Module System, Early Draft Limitations
Deep Validation Deep validation checks that every module instance has been connected to all of its imports, and that the module network does not contain inconsistent namespaces. Support for deep validation is optional in the module system. See Section 8.2.2.2. Development Module The module for development that is defined in JSR-294 [20]. Deployment Module The module for deployment that is the module definition defined in this specification. See Section 2.1. Executable Module A module definition that has a main class and is executable by the launcher. The main class is specified in the metadata of the module definition. See Section 2.16. Explicit Module Dependency A module imports another module entirely based on a module name and a version constraint. See Section 2.6 Export Defines what classes and resources in a module are visible to other modules after the module instance is interconnected. See Section 2.6. Extension Class Loader A class loader that loads classes from the JAR files in a list of standard extensions directories. Family Version Range A version range that matches any version in a particular family. See Section 5.2. Global Repository A repository that exposes module definitions which are deployed in a location on the system for sharing among different JVM processes. See Section 7.1. Import Defines a dependency between a module and the module it depends on. See Section 2.7. Import Policy A mechanism for a module instance to interconnect its imported modules with custom requirements through a piece of Java code. The import policy is responsible for ensuring that instances of the associated module definition are indeed ready to use. The import policy is invoked before the module instance can be used, and can test for arbitrary requirements. See Section 2.7. Java Module A Java module is a unit of encapsulation. It is generally written as a development module in a programming language in the Java platform, and is ultimately compiled into metadata and packaged together with classes and other resources as a deployment module for distribution. See Section 2.1.
10/2/06
86

Java Module System An architecture for the development and the deployment of module-based applications and libraries. It offers first-class modularity, packaging, and deployment support in the Java platform. JAR Stands for Java ARchive. A file format widely used as both the distribution format and the execution format in the Java platform since mid-1990s. Files in the JAR file format usually have a .jar extension. A JAR file typically contains classes and resources. See [5]. JAM Stands for JAva Module. It is the file format of the module archive. Files in the JAM file format usually have a .jam extension. A JAM file typically contains metadata, classes, resources, legacy JAR files, and native libraries. See Section 6.1. JNLP Stands for Java Networking Launching Protocol. A deployment technology defined in JSR-56 [11]. Legacy Class A class instance that does not have any development module membership. See Section 8.3. Legacy JAR File A JAR file that contains legacy classes and resources. See Section 2.14. Module Archive The physical representation of the module definition for distribution. It contains metadata, classes, and resources that are part of the module. See Section 6.1. Module Attribute A key-value pair of case-sensitive strings attached to a module definition. The attributes are generally defined and used by components at a higher layer on top of the module system. See Section 2.5. Module Class A class instance that is a member of a development module. See Section 8.3. Module Class Loader An instance of ClassLoader that is used to load classes and resources from a module instance instantiated from a module definition in a repository. See Section 8.3. Module Definition A unit of reuse, versioning, packaging, and deployment in the module system. It identifies a logical module, and specifies what classes and resources are provided by the module, and what the module imports and exports. A module definition is inherently stateless, and is properly understood as a mathematical abstraction. The identity of a module definition is represented by a modules name and version. See Section 2.1.
87
October 2, 2006 1:33 am

Module file One kind of binary artifacts resulted from the compilation of a development module. It serves as an authoritative source for module membership and module exports that is necessary for maintaining the development modules semantics. It also serves as the metadata of the module definition in the context of the deployment module. See Section 3.2. Module Instance An instantiation of a module definition. See Section 2.1. Module Metadata Information about a module, including the name, the version, the imports that define its dependencies upon other modules, and the exports that define what classes and resources are visible to other modules. See Section 2.5. Network of Modules A group of interconnected modules. Open Version Range A version range that matches any version greater than or equals to a specified version. See Section 5.2. Open Version Range Within Family A version range that matches any version greater than or equals to a specified version within a particular family. See Section 5.2. Pack200 A hyper-compression scheme for the JAR file format. It is defined in JSR-200 [16]. Packed Module Archive A module archive that is Pack200-gzip-compressed. It typically has a .jam.pack.gz extension. See Section 6.6. Platform Binding A mechanism for a module definition to indicate its platform dependency in its metadata. See Section 2.12. Preparation Preparation is a process that involves invoking an import policy to interconnect a module instance with instances of the imported module definitions. Preparation occurs when a module instance is initializing. See Section 8.2.1. Resolved Module A module instance that is interconnected and validated with its imported module instances successfully after the resolving process. See Section 8.2. Resolving Resolving is a process that interconnects and validates a module instance with its imported modules through preparation and validation. Resolving occurs when a module instance is initializing. See Section 8.2.
10/2/06
88

Resource Export List Defines what resources in a module are visible externally. It is enforced at run time after the module instance is interconnected. See Section 2.6. Repository A mechanism for storing, discovering, and retrieving module definitions in the module system. See Section 7.1. Repository Interchange Format A directory that contains module archives to facilitate sharing between different repositories. See Section 7.8. super package The new language construct that is defined in JSR-294 [20]. Shallow Validation Shallow validation checks that every module instance has been connected to all of its imports, and it is the minimal consistency requirement of a network of modules. Shallow validation occurs when a module instance is initializing. See Section 8.2.2.1. Simple Module Archive A type of module archive that only contains metadata, classes, and resources. It has neither legacy JAR file nor native library. See Section 6.3. Union of Ranges Two or more contiguous version ranges grouped together. See Section 5.2. URL Repository A repository that exposes module definitions from a specific codebase URL on the server. It downloads module definitions from the codebase URL on demand and caches them locally based on requests. See Section 7.1. Validation Validation is a process that checks the consistency requirement of a network of modules. See Section 8.2.2. Version A term generally used in the context of software, in which the version of the software changes with each modification, and the version changes in different aspect depending on the magnitude of the modification. See Section 5.1. Version Constraint A mechanism in specifying versioning requirement in a module dependency. A version constraint is a version, a version range, or a combination of both. See Section 5.3. Version Range A range of versions. See Section 5.2. Versioning Policy A set of guidelines governing how version numbers should be used. See Section 5.1.1.
89
October 2, 2006 1:33 am

Versioning Scheme A scheme to defines how a module should declare its own version as well as its versioned dependencies upon other modules. See Chapter 5.
10/2/06
90

Limitations Java Module System, Early Draft Application Programming Interface
Ap pe nd ix A
Application Programming Interface
This is a listing of the interfaces, classes, exceptions, and metadata annotations that compose the Java Module System API. They are assumed to be in the following packages for now: java.lang.module java.lang.module.annotation java.lang.module.spi Provides core classes. Provides metadata annotations for development module. Provides SPI classes.
The metadata annotation support for development module will be defined in JSR-294: Improved Modularity Support in the Java Programming Language [20]. Since the development of JSR-294 is in progress, it is entirely possible that some of these annotations might get subsumed by new mechanisms.
91
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.Class (Changes only)
A.1 java.lang.Class (Changes only)

package java.lang; ... import java.lang.module.Module; public final Class { ... /** * Return the module instance that the class is associated with. */ public Module getModule();
A.2 java.lang.module.ImportDependency
package java.lang.module; /** * This class represents an import dependency of the module definition. */ public class ImportDependency { /** * Construct a new ImportDependency object. * * @param name the name of the imported module definition. * @param constraint the constraint of the import dependency. */ public ImportDependency(String name, Query constraint); /** * Return the name of the imported module definition in an import * dependency. * * @return the name of the imported module definition. */ public String getModuleName(); /** * Return the constraint of the import dependency. * * @return the constraint of the import dependency. */ public Query getConstraint();
10/2/06
92

java.lang.module.ImportPolicy Java Module System, Early Draft Application Programming Interface
A.3 java.lang.module.ImportPolicy
package java.lang.module; /** * This class represents the import policy of a module instance. The * import policy is used to interconnect the module instance with * the imported modules during the resolving process. * * @see java.lang.module.Module */ public abstract class ImportPolicy { /** * Construct a new ImportPolicy object. * * @param module the module instance that associated * with the import policy. */ protected ImportPolicy(Module module); /** * Prepare the module instance for classloading by * interconnecting all the imported modules with * the module instance. * * @throws ResolveError if an import cannot be * satisfied. */ public abstract void prepare();
93
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.ImportPolicyError
A.4 java.lang.module.ImportPolicyError
package java.lang.module; /** * Thrown to indicate that the module system has encountered * problem when loading the import policy of a module during * resolving. */ public class ImportPolicyError extends ResolveError { /** * Constructs a <code>ImportPolicyError</code> with * no detail message. */ public ImportPolicyError(); /** * Constructs a <code>ImportPolicyError</code> with * the specified detail message. * * @param s the detail message. */ public ImportPolicyError(String s); /** * Constructs a <code>ImportPolicyError</code> with * the specified detail message and cause. * * @param s the detail message. * @param cause the cause. */ public ImportPolicyError(String s, Throwable cause); /** * Constructs a <code>ImportPolicyError</code> with * the specified cause. * * @param cause the cause. */ public ImportPolicyError(Throwable cause);
10/2/06
94

java.lang.module.LocalRepository Java Module System, Early Draft Application Programming Interface
A.5 java.lang.module.LocalRepository
package java.lang.module; import java.net.URL; /** * This class represents a repository that the module definitions * are located locally on the system. * * When the repository is initialized, the source location is * interpreted by the <code>LocalRepository</code> instance as a * directory where the module definitions are stored in the Repository * Interchange Format. */ public class LocalRepository extends Repository { /** * Creates a new LocalRepository instance. * * If a security manager is present, this method calls the * security manager's <code>checkPermission</code> method with * a <code>ModuleSystemPermission("createRepository")</code> * permission to ensure it's ok to create a repository. * * @param parent the parent repository for delegation. * @param name the repository name. * @param source the source location. * @throws SecurityException if a security manager exists and * its <tt>checkPermission</tt> method denies access * to create a new instance of repository. */ public LocalRepository(Repository parent, String name, URL source); /** * Creates a new LocalRepository instance using the Repository * returned by the method getSystemRepository() as the parent * repository. * * If a security manager is present, this method calls the * security manager's <code>checkPermission</code> method with * a <code>ModuleSystemPermission("createRepository")</code> * permission to ensure it's ok to create a repository. * * @param name the repository name. * @param source the source location. * @throws SecurityException if a security manager exists and * its <tt>checkPermission</tt> method denies access * to create a new instance of repository. */ public LocalRepository(String name, URL source);
95
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.Module
A.6 java.lang.module.Module
package java.lang.module; import java.util.List; /** * This class represents the reified module instance in the * module system. * * @see java.lang.ClassLoader * @see java.lang.module.ModuleDefinition */ public final class Module { /** * Return the <code>ModuleDefinition</code> of the module * instance. * * @return the <code>ModuleDefinition</code> object. */ public ModuleDefinition getModuleDefinition(); /** * Return the class loader associated with the module * instance. * * If a security manager is present, and the caller's * class loader is not null and the caller's class loader * is not the same as or an ancestor of the class loader * for the module instance whose class loader is * requested, then this method calls the security * manager's <code>checkPermission</code> method with a * <code>RuntimePermission("getClassLoader")</code> * permission to ensure it's ok to access the class * loader for the module instance. * * @return the <code>ClassLoader</code> object of the module. * @throws SecurityException if a security manager * exists and its <code>checkPermission</code> * method denies access to the class loader for * the module instance. */ public ClassLoader getClassLoader(); /** * Add imported module instances to this module instance. * * @throws IllegalStateException if the module instance is * not initializing. */ public void addImports(Module... imports); /** * Returns an unmodifiable list of imported module instances. * * @return an unmodifiable list of imported module instances. */
10/2/06
96

java.lang.module.Module Java Module System, Early Draft Application Programming Interface
public List<Module> getImportedModules(); /** * Check if deep validation is supported. * * @return true if deep validation is supported. */ public boolean supportsDeepValidation(); /** * Perform deep validation on the module instance. * * @throws ValidationException if deep validation fails. */ public void deepValidate(); /** * Compare two <code>Module</code> objects for equality. * The result is <code>true</code> if and only if the * argument is not <code>null</code> and is a * <code>Module</code> object that is the same instance as * this <code>Module</code>. * * @param obj the object to compare with. * @return whether or not the two objects are equal */ public boolean equals(Object obj); /** * Returns a hash code for this <code>Module</code>. * * @return a hash code value for this object. */ public int hashCode(); /** * Returns a <code>String</code> object representing this * <code>Module</code>. * * @return a string representation of the * <code>Module</code> object. */ public String toString();
97
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.ModuleDefFormatException
A.7 java.lang.module.ModuleDefFormatException
package java.lang.module; import java.io.IOException; /** * Thrown to indicate that the format of the module definition is * not recognized or supported. */ public class ModuleDefFormatException extends java.io.IOException { /** * Constructs a <code>ModuleDefFormatException</code> detail * message. */ public ModuleDefFormatException(); /** * Constructs a <code>ModuleDefFormatException</code> the * specified detail message. * * @param s the detail message. */ public ModuleDefFormatException(String s); /** * Constructs a <code>ModuleDefFormatException</code> the * specified detail message and cause. * * @param s the detail message. * @param cause the cause. */ public ModuleDefFormatException(String s, Throwable cause); /** * Constructs a <code>ModuleDefFormatException</code> the * specified cause. * * @param cause the cause. */ public ModuleDefFormatException(Throwable cause);
10/2/06
98

java.lang.module.ModuleDefNotFoundException Java Module System, Early Draft Application Programming Interface
A.8 java.lang.module.ModuleDefNotFoundException
package java.lang.module; import java.io.IOException; /** * Thrown to indicate the repository attempts to access a module * definition and fails. */ public class ModuleDefNotFoundException extends java.io.IOException { /** * Constructs a <code>ModuleDefNotFoundException</code> with * no detail message. */ public ModuleDefNotFoundException(); /** * Constructs a <code>ModuleDefNotFoundException</code> with * the specified detail message. * * @param s the detail message. */ public ModuleDefNotFoundException(String s); /** * Constructs a <code>ModuleDefNotFoundException</code> with * the specified detail message and cause. * * @param s the detail message. * @param cause the cause. */ public ModuleDefNotFoundException(String s, Throwable cause); /** * Constructs a <code>ModuleDefNotFoundException</code> with * the specified cause. * * @param cause the cause. */ public ModuleDefNotFoundException(Throwable cause);
99
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.ModuleDefinition
A.9 java.lang.module.ModuleDefinition
package java.lang.module; import java.util.Collection; import java.util.List; import java.util.Set; /** * This class represents the reified module definition in the * module system. * * @see java.lang.ClassLoader * @see java.lang.module.Repository * @see java.lang.module.Version */ public final class ModuleDefinition { /** * Return the name of the module definition. * * @return the name of the module definition. */ public String getName(); /** * Return the version of the module definition. * * @return the <code>Version</code> object. */ public Version getVersion(); /** * Returns an unmodifiable set of the names of the attributes * associated with the module definition. If the module * definition has attributes with duplicated name, only one of * them is returned in the set. * * @return a unmodifiable set of the names of the attributes. */ public Set<String> getAttributeNames(); /** * Returns the value to which the specified name of the * attribute associated with the module definition. If the module * definition has attributes with duplicated name, the value of * the attribute in the last occurrence is returned. * * @param name The name of the attribute. * @return the value of the attribute. Returns null if the * specified attribute name is not found. */ public String getAttribute(String name); /** * Return the name of the main class of the module definition. * * @return the class name if module definition has a main
10/2/06
100

java.lang.module.ModuleDefinition Java Module System, Early Draft Application Programming Interface
* class. Otherwise, return null. */ public String getMainClassName(); /** * Return repository that is associated with the module * definition. * * @return the <code>Repository</code> object. */ public Repository getRepository(); /** * Returns an unmodifiable list of import dependency. The order * of the import dependency in the list follows the declared * import order in the module definition. * * @return an unmodifiable list of import dependency. */ public List<ImportDependency> getImportDependencies(); /** * Returns an unmodifiable set of the name of the classes * exported by this module definition in the class export list. * * @return The unmodifiable set of the name of the exported * classes. */ public Set<String> getExported(); /** * Returns an unmodifiable set of the name of the classes * re-exported by this module definition in the class export * list. * * @return The unmodifiable set of the name of the re-exported * classes. */ public Set<String> getReexported(); /** * Returns an unmodifiable set of the path of the resources * exported by this module definition in the resource export * list. * * Resources are specified as '/' separated paths, with no * leading '/'. * * @return The unmodifiable set of the path of the exported * resources. */ public Set<String> getExportedResources(); /** * Returns an unmodifiable set of the path of the resources * re-exported by this module definition in the resource export * list. * * Resources are specified as '/' separated paths, with no * leading '/'.
101
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.ModuleDefinition
* * @return The unmodifiable set of the path of the re-exported * resources. */ public Set<String> getReexportedResources(); /** * Check if the specified class is exported by this module * definition in the class export list. * * @param name the name of the class. * @return true if the class is exported. */ public boolean isExported(String name); /** * Check if the specified resource is exported by this module * definition in the resource export list. * * @param path A '/' delimited path (e.g. x/y/Z.class") * @return true if the resource in the path is exported. */ public boolean isResourceExported(String path); /** * Return a module instance from the module definition for * sharing. * * If a module instance has been instantiated and returned * previously, the already-instantiated module instance should be * returned instead of creating and returning a new module * instance. * * @return a module instance of the module definition. */ public Module getInstance(); /** * Compare two <code>ModuleDefinition</code> objects for * equality. The result is <code>true</code> if and only if * the argument is not <code>null</code> and is a * <code>ModuleDefinition</code> object that is the same * instance as this <code>ModuleDefinition</code>. * * @param obj the object to compare with. * @return whether or not the two objects are equal */ public boolean equals(Object obj); /** * Returns a hash code for this * <code>ModuleDefinition</code>. * * @return a hash code value for this object. */ public int hashCode(); /** * Returns a <code>String</code> object representing this * <code>ModuleDefinition</code>.
10/2/06
102

java.lang.module.ModuleDefinition Java Module System, Early Draft Application Programming Interface
* * @return a string representation of the * <code>ModuleDefinition</code> object. */ public String toString();
103
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.ModuleDefinitionContent
A.10 java.lang.module.ModuleDefinitionContent
package java.lang.module; import import import import java.io.File; java.io.InputStream; java.io.IOException; java.security.CodeSource;
/** * This class represents the content of the module definition. * * @see java.lang.module.ModuleDefinition */ public abstract class ModuleDefinitionContent { /** * Open the content of the module definition. * * @throws IOException if an I/O error occurs. */ public void open() throws IOException; /** * Close the content of the module definition. * * @throws IOException if an I/O error occurs. */ public void close() throws IOException; /** * Return the module file of the module definition as a byte * array. * * @return byte array of the module file. * @throws IOException if an I/O error occurs. */ public byte[] getModuleFileBytes() throws IOException; /** * Find the path of the native library associated with the * module definition. * * @param libraryName the library name. * @return native library if found; otherwise, null is returned. */ public File findNativeLibrary(String libraryName); /** * Check if an entry exists in the module definition. * * @param name entrys name. * @return true if entry exists in the module definition; * otherwise, false is returned. */ public boolean hasEntry(String name); /**
10/2/06
104

java.lang.module.ModuleDefinitionContent Java Module System, Early Draft Application Programming Interface
* Return an entry in the module definition as an input stream. * * @param name entrys name. * @return if entry exists, return input stream; otherwise, * return null. * @throws IOException if an I/O error occurs. */ public InputStream getEntryAsStream(String name) throws IOException; /** * Return the code source associated with the module definition. * * @return code source of the module definition. */ public CodeSource getCodeSource(); /** * Return the content of the module definition as a JAM file. * * @return jam file that is the physical representation of the * module definition. * @throws IOException if an I/O error occurs. */ public File toJamFile() throws IOException;
105
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.ModuleFileFormatError
A.11 java.lang.module.ModuleFileFormatError
package java.lang.module; /** * Thrown to indicate the Java Virtual Machine attempts to read a * module file and determines that the file is malformed or otherwise * cannot be interpreted as a module file. */ public class ModuleFileFormatError extends java.lang.LinkageError { /** * Constructs a <code>ModuleFileFormatError</code> with * no detail message. */ public ModuleFileFormatError(); /** * Constructs a <code>ModuleFileFormatError</code> with * the specified detail message. * * @param s the detail message. */ public ModuleFileFormatError(String s); /** * Constructs a <code>ModuleFileFormatError</code> with * the specified detail message and cause. * * @param s the detail message. * @param cause the cause. */ public ModuleFileFormatError(String s, Throwable cause); /** * Constructs a <code>ModuleFileFormatError</code> with * the specified cause. * * @param cause the cause. */ public ModuleFileFormatError(Throwable cause);
10/2/06
106

java.lang.module.ModuleSystemPermission Java Module System, Early Draft Application Programming Interface
A.12 java.lang.module.ModuleSystemPermission
package java.lang.module; import java.security.BasicPermission; /** * The permission which the SecurityManager will check when code that * is running with a SecurityManager calls methods defined in the * module system for the Java platform. * * The following table provides a summary description of what the * permission allows, and discusses the risks of granting code the * permission. * * * <table border=1 cellpadding=5 summary="Table shows permission target name, what the permission allows, and associated risks"> * <tr> * <th>Permission Target Name</th> * <th>What the Permission Allows</th> * <th>Risks of Allowing this Permission</th> * </tr> * <tr> * <td>installModuleDefinition</td> * <td>Install new module definition in a repository via calls * to the Repository <code>install</code> method.</td> * <td>This allows an attacker to install malicious code * into the repository of the module system.</td> * </tr> * <tr> * <td>uninstallModuleDefinition</td> * <td>Uninstall a module definition in a repository via calls * to the Repository <code>uninstall</code> method.</td> * <td>This allows an attacker to remove critical module * definitions from the repository of the module system.</td> * </tr> * <tr> * <td>createRepository</td> * <td>Creation of a repository.</td> * <td>This is an extremely dangerous permission to grant. * Malicious applications that can instantiate their * own repositories could then load their rogue * modules and classes into the module system.</td> * </tr> * <tr> * <td>shutdownRepository</td> * <td>Shutdown a repository.</td> * <td>This allows an attacker to shutdown a repository * so the repository can no longer serve any module * definition.</td> * </tr> * <tr> * <td>reloadRepository</td> * <td>Reload module definitions in a repository.</td> * <td>This allows an attacker to invalidate the lifetime of * the outstanding module instances instantiated from * the module definitions in the repository.</td>
107
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.ModuleSystemPermission
* </tr> * </table> * * Programmers do not normally create ModuleSystemPermission * objects directly. Instead they are created by the security * policy code based on reading the security policy file. * * * @see java.security.BasicPermission * @see java.security.Permission * @see java.security.Permissions * @see java.security.PermissionCollection * @see java.lang.SecurityManager */ public final class ModuleSystemPermission extends BasicPermission { /** * Constructs a ModuleSystemPermission with the specified name. * * @param name Permission name. * @throws IllegalArgumentException if the name argument is * invalid. */ public ModuleSystemPermission(String name); /** * Constructs a new ModuleSystemPermission object. * * @param name Permission name. * @param actions Must be either null or the empty string. * @throws IllegalArgumentException if arguments are invalid. */ public ModuleSystemPermission(String name, String actions);
10/2/06
108

java.lang.module.Query Java Module System, Early Draft Application Programming Interface
A.13 java.lang.module.Query
package java.lang.module; /** * This class represents a query that determines whether or not * a particular module definition matches some criteria. * * @see java.lang.module.ModuleDefinition */ public abstract class Query { private Query(); /* * Returns a query that matches everything. * * @return the <code>Query</code> object. */ public static Query ANY(); /** * Returns a query that inverts the specified query. * * @return the <code>Query</code> object. */ public Query not(); /** * Returns a query that requires this query and the * specified query match. * * @param query the specified query. * @return the <code>Query</code> object. */ public Query and(Query query); /** * Returns a query that requires either this query or the * specified query matches. * * @param query the specified query. * @return the <code>Query</code> object. */ public Query or(Query query); /** * Returns a query that requires the version of a module * definition equals to the specified version. * * @param version the <code>Version</code> object. * @return the <code>Query</code> object. * */ public Query versionEquals(Version version); /** * Returns a query that requires the version of a module
109
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.Query
* definition equals to the specified version, ignoring the * qualifiers. * * @param version the <code>Version</code> object. * @return the <code>Query</code> object. * */ public Query versionEqualsIgnoreQualifier(Version version); /** * Returns a query that requires the version of a module * definition less than the specified version, ignoring the * qualifiers. * * @param version the <code>Version</code> object. * @return the <code>Query</code> object. */ public Query versionLessThan(Version version); /** * Returns a query that requires the version of a module * definition greater than the specified version, ignoring the * qualifiers. * * @param version the <code>Version</code> object. * @return the <code>Query</code> object. */ public Query versionGreaterThan(Version version); /** * Returns a query that requires the version of a module * definition greater than or equals to the specified floor * version but less than the specified ceiling version, ignoring * the qualifiers. * * @param floor the <code>Version</code> object. * @param ceiling the <code>Version</code> object. * @return the <code>Query</code> object. */ public Query versionRange(Version floor, Version ceiling); /** * Return a query by parsing a version constraint. The * version constraint is in the format of the version * constraint according to the versioning scheme. * * @param source the string to be parsed. * @return the <code>Query</code> object that matches * the version contraint parsed from the string. * @throws java.lang.module.VersionFormatException if * the string cannot be parsed. */ public static Query parse(String constraint) throws VersionFormatException; /** * Returns a query that requires the name of a module * definition equals to the specified name. *
10/2/06
110

java.lang.module.Query Java Module System, Early Draft Application Programming Interface
* @param name the name of the module. * @return the <code>Query</code> object. */ public Query nameEquals(String name); /** * Returns a query that requires the specified name of a * attribute exists in a module definition. * * @param name the name of the module attribute. * @return the <code>Query</code> object. */ public Query attributeExists(String name) /** * Returns a query that requires an attribute of a module * definition matches the specified name and specified value. * * @param name the name of the module attribute. * @param value The value of the module attribute. * @return The query. */ public Query attributeEquals(String name, String value) /** * Determine if the specified module definition matches this * query. * * @param target the <code>ModuleDefinition</code> to be matched. * @return true if the <code>ModuleDefinition</code> matches this * query. */ public abstract boolean match(ModuleDefinition target);
111
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.Repository
A.14 java.lang.module.Repository
package java.lang.module; import import import import /** * This * * @see * @see * @see */ public java.io.IOException; java.net.URL; java.util.Collection; java.util.List; class represents the repository in the module system. java.lang.module.ModuleDefinition java.lang.module.ModuleSystemPermission java.lang.module.Query class Repository {
/** * Creates a repository instance. * * If a security manager is present, this method calls the * security manager's <code>checkPermission</code> method with * <code>ModuleSystemPermission("createRepository")</code> * permission to ensure it's ok to create a repository. * * @param parent the parent repository for delegation. * @param name the repository name. * @param source the source location. * @throws SecurityException if a security manager exists and * its <tt>checkPermission</tt> method denies access * to create a new instance of repository. * @throws RepositoryCircularityError if a circularity is * detected. */ protected Repository(Repository parent, String name, URL source); /** * Creates a repository instance using the Repository * returned by the method getSystemRepository() as the parent * repository. * * If a security manager is present, this method calls the * security manager's <code>checkPermission</code> method with * <code>ModuleSystemPermission("createRepository")</code> * permission to ensure it's ok to create a repository. * * @param name the repository name. * @param source the source location. * @throws SecurityException if a security manager exists and * its <tt>checkPermission</tt> method denies access * to create a new instance of repository. */ protected Repository(String name, URL source); /** * Returns the name of this repository. *
10/2/06
112

java.lang.module.Repository Java Module System, Early Draft Application Programming Interface
* @return the name. */ public final String getName(); /** * Returns the source location of the repository instance. * * @return the source location. */ public final URL getSourceLocation(); /** * Returns the parent repository for delegation. If this * is the bootstrap repository, its parent is null. * * @return the parent <code>Repository.</code>. */ public final Repository getParent(); /** * Returns the bootstrap repository for delegation. The bootstrap * repository is provided by the Java Runtime. */ public static Repository getBootstrapRepository(); /** * Returns the system repository for delegation. This is * the default delegation parent for new Repository * instances. */ public static Repository getSystemRepository(); /** * Initialize the repository instance. * * @throws IOException if an I/O error occurs. * @throws IllegalStateException if the repository instance is * active. */ public void initialize() throws IOException; /** * Shutdown the repository instance. * * If a security manager is present, this method calls the * security manager's <code>checkPermission</code> method with * a <code>ModuleSystemPermission("shutdownRepository")</code> * permission to ensure it's ok to shutdown a repository. * * @throws SecurityException if a security manager exists and * its <tt>checkPermission</tt> method denies access * to shutdown the repository. * @throws IOException if an I/O error occurs. * @throws IllegalStateException if the repository instance is * inactive. */ public void shutdown() throws IOException; /**
113
October 2, 2006 1:33 am

* Enable or disable shutdown of the repository instance on exit. * This is only an advisory to the Java runtime to invoke * shutdown on the repository instance before the Java runtime * exits, however there is no particular guarantee that the * shutdown is ever invoked. By default, a repository instance is * disabled to be shutdown on exit. * * If a security manager is present, this method calls the * security manager's <code>checkPermission</code> method with * a <code>ModuleSystemPermission("shutdownRepository")</code> * permission to ensure it's ok to shutdown a repository. * * @param value indicating enabling or disabling of shutdown. * @throws SecurityException if a security manager exists and * its <tt>checkPermission</tt> method denies access * to shutdown the repository. */ public void shutdownOnExit(boolean value); /** * Returns whether or not the repository instance is active. * * @return true if this repository instance is active. */ public boolean isActive(); /** * Returns whether or not the repository instance is read-only. * * @return true if this repository instance is read-only. */ public boolean isReadOnly(); /** * Find a module definition. Equivalent to: * <pre> * find(name, Query.ANY()); * </pre> * * @param name the module definitions name. * @return the module definition or null if not found. If * more than one module definition matches the specified * name, the highest version is returned. * @throws IllegalStateException if the repository instance is * inactive. */ public final ModuleDefinition find(String name); /** * Find a module definition. * * @param name the module definitions name. * @param constraint the constraint. * @return the module definition or null if not found. If more * more than one module definition matches the specified * name and constraint, the highest version is returned. * @throws IllegalStateException if the repository instance is * inactive. */
10/2/06
114

public final ModuleDefinition find(String name, Query constraint); /** * Find all module definitions. Equivalent to: * <pre> * findAll(Query.ANY()); * </pre> * * @return the result list. * @throws IllegalStateException if the repository instance is * inactive. */ public final List<ModuleDefinition> findAll(); /** * Find all module definitions that match the specified * constraint. * * @param constraint the constraint. * @return the result list. * @throws IllegalStateException if the repository instance is * inactive. */ public final List<ModuleDefinition> findAll(Query constraint); /** * Find all matching module definitions in the repository. This * method should be overridden by repository implementations for * finding matching module definitions, and will be invoked by * the findAll method after checking the parent repository for * the requested module definitions. * * @param constraint the constraint. * @return the collection of matching module definitions. */ protected List<ModuleDefinition> findModuleDefinitions(Query constraint); /** * Install a module definition into the repository. * * If a security manager is present, this method calls the * security manager's <code>checkPermission</code> method with * a <code>ModuleSystemPermission("installModuleDefinition) * </code> permission to ensure it's ok to install new * module definition into a repository. * * @param moduleDef the module definition to be installed. * @return the newly installed module definition. * @throws SecurityException if a security manager exists * and its <tt>checkPermission</tt> method denies * access to install new module definition in the * repository. * @throws IOException If an error occurs while installing * the module definition. * @throws ModuleDefNotFoundException if the repository does * not find any module definition for installation. * @throws ModuleDefFormatException if the module format is not
115
October 2, 2006 1:33 am

* supported by this implementation. * @throws UnsupportedOperationException If the repository * is ready-only. * @throws IllegalStateException if a module definition * with the same name and version is already * installed, or if the repository instance is * inactive. */ public ModuleDefinition install(URL moduleDef) throws IOException; /** * Uninstall a module definition from the repository. * * If a security manager is present, this method calls the * security manager's <code>checkPermission</code> method with * a <code>ModuleSystemPermission("uninstallModuleDefinition) * </code> permission to ensure it's ok to uninstall module * definition from a repository. * * @param name the module definitions name. * @param version the module definitions version. * @return true if the module definition is found and * uninstalled, false otherwise. * @throws SecurityException if a security manager exists and * its <tt>checkPermission</tt> method denies access * to uninstall module definition in the repository. * @throws UnsupportedOperationException if the repository * is ready-only. * @throws ModuleDefNotFoundException if the repository does * not find the specified module definition to be * uninstalled. * @throws IOException If an error occurs while uninstalling * the module definition. * @throws IllegalStateException if the repository instance is * inactive. */ public boolean uninstall(String name, Version version) throws IOException; /** * Returns whether or not the repository instance can be * reloaded. * * @return true if this repository instance can be reloaded. */ public boolean isReloadSupported(); /** * Reload the repository. The behavior of this method depends on * the implementation. * * If a security manager is present, this method calls the * security manager's <code>checkPermission</code> method with * a <code>ModuleSystemPermission("reloadRepository")</code> * permission to ensure it's ok to reload module * definitions in a repository. * * @throws SecurityException if a security manager exists and
10/2/06
116

* its <tt>checkPermission</tt> method denies access * to reload module definitions in the repository. * @throws IOException If an error occurs while reloading * the module definitions. * @throws IllegalStateException if the repository instance is * inactive. */ public void reload() throws IOException; /** * Converts modules content into an instance of class * ModuleDefinition. * * @param content modules content. * @return The <code>ModuleDefinition</code> object that was * created from the specified module's content. */ protected ModuleDefinition defineModuleDefinition(ModuleDefinitionContent content); }
117
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.RepositoryCircularityError
A.15 java.lang.module.RepositoryCircularityError
package java.lang.module; /** * Thrown to indicate that the module system has detected a * circularity while constructing a repository instance. */ public class RepositoryCircularityError extends Error { /** * Constructs a <code>RepositoryCircularityError</code> * with no detail message. */ public RepositoryCircularityError(); /** * Constructs a <code>RepositoryCircularityError</code> * with the specified detail message. * * @param s the detail message. */ public RepositoryCircularityError(String s); /** * Constructs a <code>RepositoryCircularityError</code> * with the specified detail message and cause. * * @param s the detail message. * @param cause the cause. */ public RepositoryCircularityError(String s, Throwable cause); /** * Constructs a <code>RepositoryCircularityError</code> * with the specified cause. * * @param cause the cause. */ public RepositoryCircularityError(Throwable cause);
10/2/06
118

java.lang.module.RepositoryFactory Java Module System, Early Draft Application Programming Interface
A.16 java.lang.module.RepositoryFactory
package java.lang.module; import java.net.URL; /** * This class is a factory for creating repository instances in * the module system. * * @see java.lang.module.Repository */ public abstract class RepositoryFactory { /** * Creates a new <code>Repository</code> instance with the * specified parent repository. * * If a security manager is present, this method calls the * security manager's <code>checkPermission</code> method with * a <code>ModuleSystemPermission("createRepository")</code> * permission to ensure it's ok to create a repository. * * @param parent the parent repository for delegation. * @param name the name of the repository to be created. * @param url the source location. * @return a <code>Repository</code> that is initialized. * @throws SecurityException if a security manager exists and * its <tt>checkPermission</tt> method denies access * to create a new instance of repository. * @throws IOException if the repository factory * fails to create an instance, or the instance fails * to initiailize. */ public abstract Repository createRepository(Repository parent, String name, URL url) throws IOException; }
119
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.ResolveError
A.17 java.lang.module.ResolveError
package java.lang.module; /** * Thrown to indicate that the module system is not able to * resolve a module. */ public class ResolveError extends LinkageError { /** * Constructs a <code>ResolveError</code> with * no detail message. */ public ResolveError(); /** * Constructs a <code>ResolveError</code> with * the specified detail message. * * @param s the detail message. */ public ResolveError(String s); /** * Constructs a <code>ResolveError</code> with * the specified detail message and cause. * * @param s the detail message. * @param cause the cause. */ public ResolveError(String s, Throwable cause); /** * Constructs a <code>ResolveError</code> with * the specified cause. * * @param cause the cause. */ public ResolveError(Throwable cause);
10/2/06
120

java.lang.module.URLRepository Java Module System, Early Draft Application Programming Interface
A.18 java.lang.module.URLRepository
package java.lang.module; import java.io.IOException; import java.net.URL; import java.util.List; /** * This class represents a repository that loads module definitions * from a codebase URL. * * Information about the module definitions available from the * codebase URL must be published in a repository metadata file. The * contents of the file must follow the schema of the URL Repository * metadata for the Java Module System. * * {codebase}/repository-metadata.xml * * When the repository is initialized, the repository metadata file * (i.e. repository-metadata.xml) would be downloaded from the * codebase URL. * * In the repository metadata file, each module definition is described * with a name, a version, a platform binding, and a path (relative to * the codebase URL where the module file, the module archive, and/or * the packed module archive are located). If no path and no platform * binding is specified, the default path is {name}/{version}. If the * path is not specified and the module definition has platform * binding, the default path is {name}/{version}/{platform}-{arch}. * * After the URL repository instance successfully downloads the * repository metadata file, the module file of each module definition * (i.e. METADATA.module file) in the repository is downloaded based on * the information in the repository metadata file: * * {codebase}/{path}/METADATA.module * * If a module definition is platform-specific, its module file is * downloaded if and only if the platform binding described in the * repository metadata file matches the platform and the architecture * of the system. * * Module definitions are available for searches after the URL * repository instance is initialized. If a module instance is * instantiated from a module definition that has no platform binding, * the module archive is downloaded by probing in the following order: * * {codebase}/{path}/{name}-{version}.jam.pack.gz * {codebase}/{path}/{name}-{version}.jam * * On the other hand, if a module instance is instantiated from a * platform-specific module definition, the module archive is * downloaded by probing in the following order: * * {codebase}/{path}/{name}-{version}-{platform}-{arch}.jam.pack.gz * {codebase}/{path}/{name}-{version}-{platform}-{arch}.jam * 
121
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.URLRepository
* To ensure the integrity of the separately-hosted module file is in * sync with that in the module archive of the same module definition, * they are compared bit-wise against each other after the module * archive is downloaded. * * @see java.lang.module.ModuleDefinition * @see java.lang.module.ModuleSystemPermission * @see java.lang.module.Query */ public class URLRepository extends Repository { /** * Creates a URLRepository instance. * * If a security manager is present, this method calls the * security manager's <code>checkPermission</code> method with * a <code>ModuleSystemPermission("createRepository")</code> * permission to ensure it's ok to create a repository. * * @param parent the parent repository for delegation. * @param name the repository name. * @param codebase the source location. * @throws SecurityException if a security manager exists and * its <tt>checkPermission</tt> method denies access * to create a new instance of repository. */ public URLRepository(Repository parent, String name, URL codebase); /** * Creates a URLRepository instance using the Repository returned * by the method getSystemRepository() as the parent repository. * * If a security manager is present, this method calls the * security manager's <code>checkPermission</code> method with * a <code>ModuleSystemPermission("createRepository")</code> * permission to ensure it's ok to create a repository. * * @param name the repository name. * @param codebase the source location. * @throws SecurityException if a security manager exists and * its <tt>checkPermission</tt> method denies access * to create a new instance of repository. */ public URLRepository(String name, URL codebase);
10/2/06
122

java.lang.module.ValidationException Java Module System, Early Draft Application Programming Interface
A.19 java.lang.module.ValidationException
package java.lang.module; /** * Thrown to indicate that the module system has encountered * validation problem in a module. */ public class ValidationException extends Exception { /** * Constructs a <code>ValidationException</code> with * no detail message. */ public ValidationException(); /** * Constructs a <code>ValidationException</code> with * the specified detail message. * * @param s the detail message. */ public ValidationException(String s); /** * Constructs a <code>ValidationException</code> with * the specified detail message and cause. * * @param s the detail message. * @param cause the cause. */ public ValidationException(String s, Throwable cause); /** * Constructs a <code>ValidationException</code> with * the specified cause. * * @param cause the cause. */ public ValidationException(Throwable cause);
123
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.Version
A.20 java.lang.module.Version
package java.lang.module; /** * This class represents a version in the module versioning * scheme. * * @see java.lang.module.Query */ public class Version implements Comparable<Version> { /** * Constructs a new version. * * @param major the major version number. * @param minor the minor version number. * @param micro the micro version number. * @throws java.lang.module.VersionFormatException if major * or minor or micro is negative. */ public Version(int major, int minor, int micro) throws VersionFormatException; /** * Constructs a new version. * * @param major the major version number. * @param minor the minor version number. * @param micro the micro version number. * @param qualifier the qualifier * @throws java.lang.module.VersionFormatException if major * or minor or micro or update is negative. */ public Version(int major, int minor, int micro, String qualifier) throws VersionFormatException; /** * Constructs a new version. * * @param major the major version number. * @param minor the minor version number. * @param micro the micro version number. * @param update the update version number. * @throws java.lang.module.VersionFormatException if major * or minor or micro or update is negative. */ public Version(int major, int minor, int micro, int update) throws VersionFormatException; /** * Constructs a new version. * * @param major the major version number. * @param minor the minor version number. * @param micro the micro version number. * @param update the update version number. * @param qualifier the qualifier
10/2/06
124

java.lang.module.Version Java Module System, Early Draft Application Programming Interface
* @throws java.lang.module.VersionFormatException if major * or minor or micro or update is negative. */ public Version(int major, int minor, int micro, int update, String qualifier) throws VersionFormatException; /** * Returns the major number in the version. * * @return the major version. */ public int getMajorNumber(); /** * Returns the minor number in the version. * * @return the minor version. */ public int getMinorNumber(); /** * Returns the micro number in the version. * * @return the micro version. */ public int getMicroNumber(); /** * Returns the update number in the version. * * @return the update version. */ public int getUpdateNumber(); /** * Returns the qualifier in the version. * * @return the qualifier. */ public String getQualifier(); /** * Parse a string according to the version format described * in the module versioning scheme. * * @param source the string to be parsed. * @return A <code>Version</code> parsed from the string. * @throws java.lang.module.VersionFormatException if * the string cannot be parsed. */ public static Version parse(String source) throws VersionFormatException; /** * Return a query that matches this <code>Version</code>. * * @return a <code>Query</code> object. */ public Query toQuery();
125
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.Version
/** * Compare two <code>Version</code> objects. * * @param version the <code>Version</code> to be compared. * @return the value 0 if the argument <code>Version</code> * is equal to this <code>Version</code>; a value * less than 0 if this <code>Version</code> is less than * the <code>Version</code> argument; and a value greater * than 0 if this <code>Version</code> is greater than * the <code>Version</code> argument. */ public int compareTo(Version version); /** * Compare two <code>Version</code> objects, ignoring the * qualifiers. * * @param version the <code>Version</code> to be compared. * @return the value 0 if the argument <code>Version</code> * is equal to this <code>Version</code>; a value * less than 0 if this <code>Version</code> is less than * the <code>Version</code> argument; and a value greater * than 0 if this <code>Version</code> is greater than * the <code>Version</code> argument. */ public int compareToIgnoreQualifier(Version version); /** * Compare two <code>Version</code> objects for equality. * The result is <code>true</code> if and only if the * argument is not <code>null</code> and is a * <code>Version</code> object that the major, minor, * micro, update, and qualifier the same as those of this * <code>Version</code>. * * @param obj the object to compare with. * @return whether or not the two objects are equal */ public boolean equals(Object obj); /** * Returns a hash code for this <code>Version</code>. * * @return a hash code value for this object. */ public int hashCode(); /** * Returns a <code>String</code> object representing this * <code>Version</code>'s value. The value is converted to * the version format in the versioning scheme and returned * as a string. * * @return a string representation of the value of this * object in the version format. */ public String toString();
10/2/06
126

java.lang.module.VersionFormatException Java Module System, Early Draft Application Programming Interface
A.21 java.lang.module.VersionFormatException
package java.lang.module; /** * Throw to indicate that a parser has attempted to parse a * version string and determines that the format is malformed. */ public class VersionFormatException extends IllegalArgumentException { /** * Constructs a <code>VersionFormatException</code> with no * detail message. */ public VersionFormatException(); /** * Constructs a <code>VersionFormatException</code> with * the specified detail message. * * @param s the detail message. */ public VersionFormatException(String s); /** * Constructs a <code>VersionFormatException</code> with * the specified detail message and cause. * * @param s the detail message. * @param cause the cause. */ public VersionFormatException(String s, Throwable cause); /** * Constructs a <code>VersionFormatException</code> with * the specified cause. * * @param cause the cause. */ public VersionFormatException(Throwable cause);
127
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.annotation.ExportResources
A.22 java.lang.module.annotation.ExportResources
package java.lang.module.annotation; import import import import java.lang.annotation.ElementType; java.lang.annotation.Target; java.lang.annotation.Retention; java.lang.annotation.RetentionPolicy;
/** * Indicates the exported resources of a module definition. Each * export is the corresponding path of the resource within the * module archive that is exported. This metadata annotation is * applied to the development module, i.e. the super package * construct. * * The string that specifies the exported resource may contain * wildcard: * 1. A path with a trailing /* matches all files contained in * that directory. * 2. A path with a trailing /** matches all files in the * directory, and recursively all files in subdirectories * contained in that directory. * * For example, * <blockquote><pre> * // * // Export resources one-by-one. * // * @ExportResources({ * "icons/graphics1.jpg", * "icons/graphics2.jpg"}) * super package org.foo.xml ... * * // * // Export resources using wildcards, including * // - all contents under icons directory, and * // - all contents under META-INF and its sub-directories * // * @ExportResources({ * "icons/*", * "META-INF/**"}) * super package org.foo.xml ... * </pre></blockquote> */ @Target(ElementType.SUPERPACKAGE[6]) @Retention(RetentionPolicy.RUNTIME) public @interface ExportResources { /** * Exported resources of the module definition. */ String[] value();
[6]
The java.lang.annotation.ElementType.SUPERPACKAGE annotation target is expected to be defined by JSR-294.
10/2/06
128

java.lang.module.annotation.ImportPolicyClass Java Module System, Early Draft Application Programming Interface
A.23 java.lang.module.annotation.ImportPolicyClass
/** * Indicates the class of the import policy a module definition. The * class name not have the .class extension appended. The class must * extend the <code>ImportPolicy</code> class. This metadata * annotation is applied to the development module, i.e. the super * package construct. * * For example, * <blockquote><pre> * @ImportPolicyClass("org.foo.xml.ImportPolicy") * super package org.foo.xml ... * </pre></blockquote> * * @see java.lang.module.ImportPolicy */ @Target(ElementType.SUPERPACKAGE) @Retention(RetentionPolicy.RUNTIME) public @interface ImportPolicyClass { /** * Import policy class name. */ String value();
129
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.annotation.MainClass
A.24 java.lang.module.annotation.MainClass
/** * Indicates the main class of a module definition. The main class name * must not have the .class extension appended. This metadata * annotation is applied to the development module, i.e. the super * package construct. * * For example, * <blockquote><pre> * @MainClass("org.foo.xml.Main") * super package org.foo.xml ... * </pre></blockquote> * * Being a main class does not imply the class is exported from the * module definition. The main class must be exported explicitly. For * example, * <blockquote><pre> * @MainClass("org.foo.xml.Main") * super package org.foo.xml { * export org.foo.xml.Main; * ... * </pre></blockquote> */ @Target(ElementType.SUPERPACKAGE) @Retention(RetentionPolicy.RUNTIME) public @interface MainClass { /** * Main class name. */ String value();
10/2/06
130

java.lang.module.annotation.ModuleAttribute Java Module System, Early Draft Application Programming Interface
A.25 java.lang.module.annotation.ModuleAttribute
/** * Indicates an attribute of a module definition. This metadata * annotation is applied to the parameter. * * Module attributes are generally defined by components at higher * layer on top of the module system. To minimize the naming conflicts * between module attributes, each module attribute should be defined * with a fully qualified name. * * For example, * <blockquote><pre> * @ModuleAttribute(name="org.opensource.license", value="GPL") * * @ModuleAttribute(name="java.magic.number", value="CAFEBABE") * </pre></blockquote> */ @Target(ElementType.PARAMETER) @Retention(RetentionPolicy.RUNTIME) public @interface ModuleAttribute { /** * Name of the module attribute. */ String name(); /** * Value of the module attribute. */ String value();
131
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.annotation.ModuleAttributes
A.26 java.lang.module.annotation.ModuleAttributes
/** * Indicates an array of attributes of a module definition. This * metadata annotation is applied to the development module, i.e. * the super package construct. * * For example, * <blockquote><pre> * @ModuleAttributes({ * @ModuleAttribute(name="org.opensource.license", value="GPL"), * @ModuleAttribute(name="java.magic.number", value="CAFEBABE") * }) * super package org.foo.xml ... * </pre></blockquote> * * @see java.lang.module.annotation.ModuleAttribute */ @Target(ElementType.SUPERPACKAGE) @Retention(RetentionPolicy.RUNTIME) public @interface ModuleAttributes { /** * Array of module attributes. */ ModuleAttribute[] value();
10/2/06
132

java.lang.module.annotation.NativeLibraryPath Java Module System, Early Draft Application Programming Interface
A.27 java.lang.module.annotation.NativeLibraryPath
/** * Override the directory within the module archive for searching * native libraries for a particular platform and architecture. This * metadata annotation is applied to the parameter. * * For example, * <blockquote><pre> * @NativeLibraryPath(platform=windows, arch=x86, * path=native/windows-x86) * * @NativeLibraryPath(platform=linux, arch=x86, * path=native/linux-x86) * * @NativeLibraryPath(platform=solaris, arch=sparc, * path=native/solaris-sparc) * </pre></blockquote> */ @Target(ElementType.PARAMETER) @Retention(RetentionPolicy.RUNTIME) public @interface NativeLibraryPath { /** * Name of the platform. It should be one of the possible values * of the system property "os.platform[7]". */ String platform(); /** * Name of the architecture. It should be one of the possible * values of the system property "os.arch". */ String arch(); /** * Directory within the module archive for searching native * library. */ String path();
[7]
The system property os.platform is expected to be defined in Java SE 7. e.g. windows for Windows, linux for Linux, solaris for Solaris, etc.
133
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.annotation.NativeLibraryPaths
A.28 java.lang.module.annotation.NativeLibraryPaths
/** * Override the directories within the module archive for searching * native libraries. This metadata annotation is applied to the * development module, i.e. the super package construct. * * For example, * <blockquote><pre> * @NativeLibraryPaths({ * @NativeLibraryPath(platform=windows, arch=x86, * path=native/windows-x86), * @NativeLibraryPath(platform=linux, arch=x86, * path=native/linux-x86), * @NativeLibraryPath(platform=solaris, arch=sparc, path=native/solaris-sparc), * }) * super package com.sun.java3d ... * </pre></blockquote> * * @see java.lang.module.annotation.NativeLibraryPath */ @Target(ElementType.SUPERPACKAGE) @Retention(RetentionPolicy.RUNTIME) public @interface NativeLibraryPaths { /** * Array of native library paths within the module archive. */ NativeLibraryPath[] value();
10/2/06
134

java.lang.module.annotation.PlatformBinding Java Module System, Early Draft Application Programming Interface
A.29 java.lang.module.annotation.PlatformBinding
/** * Indicates the platform binding of a module definition. This * metadata annotation is applied to the development module, i.e. the * super package construct. * * For example, * <blockquote><pre> * @PlatformBinding(platform="windows", arch="x86") * super package org.foo.xml ... * * @PlatformBinding(platform="linux", arch="x86") super package org.foo.xml ...
* @PlatformBinding(platform="solaris", arch="sparc") * super package org.foo.xml ... * </pre></blockquote> */ @Target(ElementType.SUPERPACKAGE) @Retention(RetentionPolicy.RUNTIME) public @interface PlatformBinding { /** * Name of the platform. It should be one of the possible values * of the system property "os.platform". */ String platform(); /** * Name of the architecture. It should be one of the possible * values of the system property "os.arch". */ String arch();
135
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.annotation.ReexportResources
A.30 java.lang.module.annotation.ReexportResources
/** * Indicates the re-exported resources of a module definition. Each * re-export is the corresponding path of the resource that this * module definition re-exports from the imported module definition. * This metadata annotation is applied to the development module, * i.e. the super package construct. * * The string that specifies the re-exported file may contain * wildcard: * 1. A path with a trailing /* matches all files contained in * that directory. * 2. A path with a trailing /** matches all files in the * directory, and recursively all files in subdirectories * contained in that directory. * * For example, * <blockquote><pre> * // * // Re-export resources one-by-one. * // * @ReexportResources({ * "icons/graphics1.jpg", * "icons/graphics2.jpg"}) * super package com.sun.wombat { * import org.foo.xml ... * * // * // Re-export resources using wildcards, including * // - all contents under icons directory, and * // - all contents under META-INF and its sub-directories * // * @ReexportResources({ * "icons/*", * "META-INF/**"}) * super package com.sun.wombat { * import org.foo.xml ... * </pre></blockquote> */ @Target(ElementType.SUPERPACKAGE) @Retention(RetentionPolicy.RUNTIME) public @interface ReexportResources { /** * Re-exported resources of the module definition. */ String[] value();
10/2/06
136

java.lang.module.annotation.SearchPath Java Module System, Early Draft Application Programming Interface
A.31 java.lang.module.annotation.SearchPath
/** * Override the directory within the module archive for searching * classes and resources. This metadata annotation is applied to the * development module, i.e. the super package construct. * * For example, * <blockquote><pre> * @SearchPath("WEB-INF/classes") * super package org.foo.webapp ... * </pre></blockquote> * */ @Target(ElementType.SUPERPACKAGE) @Retention(RetentionPolicy.RUNTIME) public @interface SearchPath { /** * Directory within the module archive for searching classes and * resources. */ String value();
137
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.annotation.SkipValidation
A.32 java.lang.module.annotation.SkipValidation
/** * Indicates whether an import in a module definition should skip * validation. This metadata annotation is applied to the import of * the development module, i.e. the super package construct. * * For example, * <blockquote><pre> * // Import a different version of the javax.xml module than * // the one exported from the java.se module through the * // following steps: * // * // 1. Declare imports for the javax.xml and java.se modules * // manually. Notice that the javax.xml module is declared first * // to ensure the runtime search order. * // 2. Mark the javax.xml import with @SkipValidation. * // There are type conflicts between the javax.xml and the * // java.se modules, so this is necessary to avoid validation * // failure. * // * super package org.foo.xml { * @SkipValidation * @VersionConstraint(2.0) * import javax.xml; * * // Import java.se module manually * @VersionConstraint(1.7) * import java.se; * ... * } * </pre></blockquote> * */ @Target(ElementType.IMPORT[8]) @Retention(RetentionPolicy.RUNTIME) public @interface SkipValidation { /** * Return true if the validation should be skipped for the * import; otherwise, return false. */ boolean value() default true;
[8]
The java.lang.annotation.ElementType.IMPORT annotation target is expected to be defined by JSR-294.
10/2/06
138

java.lang.module.annotation.Version Java Module System, Early Draft Application Programming Interface
A.33 java.lang.module.annotation.Version
/** * Indicates the version of a module definition. The version * should follow the format described in the module versioning * scheme: * major[.minor[.micro[.update]]][-qualifier] * * This metadata annotation is applied to the development module, * i.e. the super package construct. * * For example, * <blockquote><pre> * @Version("1.0.0") * super package org.foo.xml ... * * @Version("2.3.4-b17-beta") * super package org.foo.xml ... * * @Version("3.4.5.6-b44-rc") * super package org.foo.xml ... * </pre></blockquote> * */ @Target(ElementType.SUPERPACKAGE) @Retention(RetentionPolicy.RUNTIME) public @interface Version { /** * Version of the module definition. */ String value();
139
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.annotation.VersionConstraint
A.34 java.lang.module.annotation.VersionConstraint
/** * Indicates the version constraint of an import in a module * definition. The version constraint is either a version, a version * range, or a combination of both, following the format described in * the module versioning scheme. * * This metadata annotation is applied to the import of the development * module, i.e. the super package construct. * * For examples, * <blockquote><pre> * super package org.foo.xml { * @VersionConstraint("1.0+") * import org.w3c.dom.domLevel3; ... * * super package org.foo.xml { * @VersionConstraint("1.2.1*") * import org.w3c.dom.domLevel3; ... * * super package org.foo.xml { * @VersionConstraint("1.2.[1+];2*;3*") * import org.w3c.dom.domLevel3; ... * </pre></blockquote> */ @Target(ElementType.IMPORT) @Retention(RetentionPolicy.RUNTIME) public @interface VersionConstraint { /** * Version constraint of the import in the module definition. */ String value();
10/2/06
140

java.lang.module.spi.ModuleDefinitionProvider Java Module System, Early Draft Application Programming Interface
A.35 java.lang.module.spi.ModuleDefinitionProvider
package java.lang.module.spi; import import import import import java.lang.module.ImportDependency; java.lang.module.ModuleDefinitionContent; java.lang.module.Version; java.util.Collection; java.util.List;
/** * Module definition provider class. * * A module definition provider is a concrete subclass of this class * that has a zero-argument constructor and some number of associated * implementation classes. */ public abstract class ModuleDefinitionProvider { /** * Return the name of the module definition provider. * * @return name of the module definition provider. */ public String getProviderName(); /** * Return the name of the module definition. * * @return the name of the module definition. */ public String getName(); /** * Return the version of the module definition. * * @return the <code>Version</code> object. */ public Version getVersion(); /** * Returns an unmodifiable set of the names of the attributes * associated with the module definition. If the module * definition has attributes with duplicated name, only one of * them is returned in the set. * * @return a unmodifiable set of the names of the attributes. */ public Set<String> getAttributeNames(); /** * Returns the value to which the specified name of the * attribute associated with the module definition. If the module * definition has attributes with duplicated name, the value of * the attribute in the last occurrence is returned. * * @param name The name of the attribute. * @return the value of the attribute. Returns null if the
141
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.spi.ModuleDefinitionProvider
* specified attribute name is not found. */ public String getAttribute(String name); /** * Return the name of the main class of the module definition. * * @return the class name if module definition has a main * class. Otherwise, return null. */ public String getMainClassName(); /** * Returns an unmodifiable list of import dependency. The order * of the import dependency in the list follows the declared * import order in the module definition. * * @return an unmodifiable list of import dependency. */ public List<ImportDependency> getImportDependencies(); /** * Returns an unmodifiable set of the name of the classes * exported by the module definition in the class export list. * * @return The unmodifiable set of the name of the exported * classes. */ public Set<String> getExported(); /** * Returns an unmodifiable set of the name of the classes * re-exported by the module definition in the class export * list. * * @return The unmodifiable set of the name of the re-exported * classes. */ public Set<String> getReexported(); /** * Returns an unmodifiable set of the path of the resources * exported by the module definition in the resource export * list. * * Resources are specified as '/' separated paths, with no * leading '/'. * * @return The unmodifiable set of the path of the exported * resources. */ public Set<String> getExportedResources(); /** * Returns an unmodifiable set of the path of the resources * re-exported by the module definition in the resource export * list. * * Resources are specified as '/' separated paths, with no
10/2/06
142

java.lang.module.spi.ModuleDefinitionProvider Java Module System, Early Draft Application Programming Interface
* leading '/'. * * @return The unmodifiable set of the path of the re-exported * resources. */ public Set<String> getReexportedResources(); /** * Check if the specified class is exported by this module * definition in the class export list. * * @param name the name of the class. * @return true if the class is exported. */ public boolean isExported(String name); /** * Check if the specified resource is exported by this module * definition in the resource export list. * * @param path A '/' delimited path (e.g. x/y/Z.class") * @return true if the resource in the path is exported. */ public boolean isResourceExported(String path); /** * Return a new module instance provider from the module * definition. * * If the module instance provider is a singleton, calling * this method should return the singleton provider the first * time. Subsequent calling on this method should throw * UnsupportedOperationException. * * @return a module instance provider of the module definition. * @throws UnsupportedOperationException if a new module instance * provider cannot be instantiated. */ public ModuleProvider newInstance(); /** * Return the content of the module definition. * * @return the <code>ModuleDefinitionContent</code> object that * represents the content of the module definition. */ public ModuleDefinitionContent getContent();
143
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.spi.ModuleProvider
A.36 java.lang.module.spi.ModuleProvider
package java.lang.module.spi; import java.lang.module.Module; /** * Module instance provider class. * * A module instance provider is a concrete subclass of this class * that has a zero-argument constructor and some number of associated * implementation classes. */ public abstract class ModuleProvider { /** * Return the name of the module instance provider. * * @return name of the module instance provider. */ public String getProviderName(); /** * Prepare the module instance by interconnecting it with * instances of the imported module definitions. This * method is called when the module instance is preparing (i.e. * the PREPARING state) during initialization. * * @param self the module instance itself. * @throws ImportPolicyError if error is encountered when * loading the import policy. * @throws ResolveError if an import cannot be satisfied. */ public void prepareImports(Module self); /** * Prepare the module instance for classloading by * fully resolving its imports. This method is called * after the module instance is interconnected with * its imports and passes shallow validation (i.e. the RESOLVED * state) during initialization. * * @param self the module instance itself. * @throws ResolveError if error is encountered while * resolving the import. */ public void prepareClassLoading(Module self); /** * Return the class loader associated with the module * instance. This method is called after the module instance is * fully initialized (i.e. the READY state). * * @return the <code>ClassLoader</code> object of the module * instance. */ public ClassLoader getClassLoader();
10/2/06
144

java.lang.module.spi.RepositoryProvider Java Module System, Early Draft Application Programming Interface
A.37 java.lang.module.spi.RepositoryProvider
package java.lang.module.spi; import import import import import java.lang.module.Query; java.lang.module.Version; java.io.IOException; java.net.URL; java.util.List;
/** * Repository provider class. * * A repository provider is a concrete subclass of this class * that has a zero-argument constructor and some number of associated * implementation classes. */ public abstract class RepositoryProvider { /** * Return the name of the repository provider. * * @return name of the repository provider. */ public String getProviderName(); /** * Find all matching module definitions in the repository. * * @param constraint the constraint. * @return the collection that contains the matching module * definitions. */ public List<ModuleDefinitionProvider> findModuleDefinitionProviders(Query constraint); /** * Initialize the repository. * * @param name the repository name. * @param source the source location. * @throws IOException if an I/O error occurs. */ public void initialize(String name, URL source) throws IOException; /** * Shutdown the repository. * * @throws IOException if an I/O error occurs. */ public void shutdown() throws IOException; /** * Returns whether or not the repository is active. * * @return true if this repository is active. */
145
October 2, 2006 1:33 am

Application Programming Interface Java Module System, Early Draft java.lang.module.spi.RepositoryProvider
public boolean isActive(); /** * Returns whether or not the repository is read-only. * * @return true if this repository is read-only. */ public boolean isReadOnly(); /** * Install a module definition into the repository. * * @param moduleDef the module definition to be installed. * @return the provider of the newly installed module * definition. * @throws IOException if an error occurs while installing * the module definition. * @throws ModuleDefNotFoundException if the repository does * not find any module definition for installation. * @throws ModuleDefFormatException if the module format is not * supported by this implementation. * @throws IllegalStateException if a module definition with * the same name and version is already installed. */ public ModuleDefinitionProvider install(URL moduleDef) throws IOException; /** * Uninstall a module definition from the repository. * * @param name the module definition's name. * @param version the module definition's version. * @return true if the module definition is found and * uninstalled, false otherwise. * @throws ModuleDefNotFoundException if the repository does * not find the specified module definition to be * uninstalled. * @throws IOException If an error occurs while uninstalling * the module definition. */ public boolean uninstall(String name, Version version) throws IOException; /** * Returns whether or not the repository can be reloaded. * * @return true if this repository can be reloaded. */ public boolean isReloadSupported(); /** * Reload the module definitions in the repository. The * behavior of this method depends on the implementation. * * @throws IOException If an error occurs while reloading * the module definitions. */ public void reload() throws IOException;
10/2/06
146

Schema: URL Repository Metadata Java Module System, Early Draft Application Programming Interface
A.38 Schema: URL Repository Metadata

<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:annotation> <xs:documentation xml:lang="en"> URL Repository Metadata Schema for Java Module System. Copyright 2006 Sun Microsystems, Inc. All rights reserved. </xs:documentation> </xs:annotation> <xs:element name="modules" type="ModulesType"/> <xs:complexType name="ModulesType"> <xs:sequence> <xs:element name="module" type="ModuleType" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:complexType name="ModuleType"> <xs:sequence>  <xs:element name="name" type="xs:string"/> <!-Version of the module. It must follow the version format in the module versioning scheme.
--> <xs:element name="version" type="xs:string"/>  <xs:element name="platform-binding" type="PlatformBindingType" minOccurs="0"/> <!-Relative path to the files that belong to the specified module, including the module file (i.e. METADATA.module), the module archive (i.e. .jam file) and/or the packed module archive (i.e. .jam.pack.gz file).
--> <xs:element name="path" type="xs:string" minOccurs=0/> </xs:sequence> </xs:complexType> <xs:complexType name="PlatformBindingType"> <xs:sequence>  <xs:element name="arch" type="xs:string"/> </xs:sequence> </xs:complexType> </xs:schema>
10/2/06
148

Why does the versioning scheme look familiar? Java Module System, Early Draft Frequently Asked Questions (FAQ)
Ap pe nd ix B
Frequently Asked Questions (FAQ)
B.1 Why does the versioning scheme look familiar?

There are a few versioning schemes ([1] and [2]) already used widely in the Java platform today, and the versioning scheme in this specification is loosely based on these existing ones for backwards compatibility reason.
B.2 What should I be aware in migration from an existing versioning scheme?

Some Java products and applications on the market might use versioning scheme that contains less than or more than four numerics in the version format. To migrate these products and applications as modules, developers are expected to define version mappings between the proprietary version and the versioning scheme in the module system. It is also important to consider the versioning policy while defining the version mapping, thus other developers using your module can establish versioning requirements with reasonable expectation on compatibility.
149
October 2, 2006 1:33 am

Frequently Asked Questions (FAQ) Java Module System, Early Draft Will module developers need to write the import
B.3 Will module developers need to write the import policy manually?
The import policy is a low level but very general and powerful facility that can accommodate almost any scenario, and it should be used when the declarative mechanism is not sufficiently expressive. In most cases, we expect developers will specify version constraint declaratively in the import dependencies instead of using the import policy. In the cases where import policy is really necessary, we expect developers will generate the import policy using higher level tools that translate into lower level calls, rather than writing one manually.
B.4 Why are the exports lists for classes and resources separate?
The export lists for classes and resources are separate because they serve different purposes. When a development module (defined in JSR-294) is compiled against other imported development modules at build time, the compiler would leverage the class export list of the imported development modules to ensure only exported classes can be compiled against. At run time, the Java virtual machine also leverages the class export list to enforce access control among classes that are part of the development module membership. On the other hand, the resource export list is only used by JSR-277 to limit the visibility of resources at the module class loaders level at run time. The resource export list is neither recognized by the compiler at build time, nor by the Java virtual machine at run time. Please refer to Section 8.3.2 for more information on the visibility of classes and resources.
B.5 Why is the JAM file format based on the JAR file format?
The JAR file format was adopted by Sun in 1996 as the packaging and distribution format for the Java platform. Over the years, developers and companies have big investiments on this format therefore for any new distribution format, compatibility should be an important design goal. New formats could be designed with better properties (faster access to packaged components, better space efficiency), but we do not feel that potential improvements justify a departure from the well-understood JAR file format. Therefore, it is a natural choice for the Java Module System to reuse the existing JAR file format to support module archives.
10/2/06
150

Can a JAM file be used as a plain JAR file in older releases?Java Module System, Early Draft Frequently Asked Questions (FAQ)
B.6 Can a JAM file be used as a plain JAR file in older releases?
The format of the module archive (i.e. JAM) is based on the JAR file format, so in theory a JAM file can be used as a plain JAR file in older JRE releases. However, there are two prerequisites for it to work: 1. The JAM file is a simple module archive. It contains module file, classes, and resources; it has neither legacy JAR file nor native library. The class file generated from the development module (JSR-294) uses an existing class file format version that the VMs in older releases recognize, and the class file needs to carry module information in a backwards compatible way.
2.
Since the development of JSR-294 is in progress, (2) is only a speculation at this point. The actual answer to this question will depend on the design of JSR-294.
B.7 Does the system recognize the JAM file as a physical representation of a module definition no matter what I do?
No, only the repository in the module system supports the JAM file format, and you must deploy the module definition into a repository before it can be recognized by the module system. If you use the JAM file in the classpath, bootclasspath, etc., even if the Java platform supports JSR-277, the JAM file will simply be treated as a plain JAR file.
B.8 Why isnt the Class-Path manifest entry recognized in JAM?

The Class-Path manifest entry is used to define the relative URLs of the extensions or libraries that this application or extension needs. Because a module archive is inherently self-contained, it does not reference any resource externally, nor it defines dependencies upon other modules based on relative URLs. Hence, there is no reasonable interpretation of the Class-Path manifest entry by the module system, so it is ignored.
B.9 What kind of errors would be caught by shallow validation?

Preparation of a module instance results in a list of imported module instances, but there is no guarantee that each imported module instance actually matches the modules import in the declared order. Shallow validation could detect the error. Further, there could be overlaps between the types exported from the imported module instances; shallow validation could detect the error as well.
151
October 2, 2006 1:33 am

Frequently Asked Questions (FAQ) Java Module System, Early Draft When do we want to do a deep validation?
B.10 When do we want to do a deep validation?

Deep validation is valuable in determining the consistencies of the class loader namespace. However, it cannot be performed with absolute certainty except during the actual run, and then by actually doing eager loading of all classes and interfaces into the class loader namespace. There are at least two situations that performing deep validation would be useful: 1. Perform deep validation after installation of a module definition in the repository as a sanity check for namespace consistency. 2. If ClassCastException is encountered in code from a module instance at run time due to namespace inconsistency in the class loader, performing deep validation should help developers uncover the root cause.
B.11 When do we need to instantiate a new module instance explicitly?

Generally, using the same module instance maximizes sharing in the same JVM process. However, it is sometimes necessary to instantiate a new module instance. For example, 1. When there are issues around the state of the existing module instance, it is critical to instantiate a new module instance with a clean state for further sharing. 2. Some applications might need to use module instances privately for isolation.
B.12 How scalable is the URL repository?

URLRepository is designed to be simple for downloading module definitions from the web, e.g. module-based Java applets or JNLP applications, but it is not designed to be highly scalable. If scalability is a critical requirement for deployment, custom repository implementations should be used instead, e.g. some implementations may use Ivy repository [29] or Maven repository [30] as the back-ends.
B.13 Why does the URL repository require the module file to be hosted separately from the module archive?
The size of a module file is typically much smaller than that of a module archive. An URL repository instance only needs information from the module files to satisfy search requests, and the module archives are needed only if a module instance has been instantiated and is being initialized. Hence, hosting the module file (i.e. METADATA.module) and the module archive (i.e. JAM file) separately on the server side would reduce the amount of download required up front and also make the rest of the download as lazy as possible when using an URL repository instance.
10/2/06
152

Submodules Java Module System, Early Draft Expert Group Work Items
Ap pe nd ix C
Expert Group Work Items
This chapter highlights some of the work items that will be investigated by the JSR-277 Expert Group after the Early Draft is released. This list is by no means complete, nor the Expert Group guarantees these work items will be fully realized in future revision of the specification.
C.1 Submodules
For any large application, it is not uncommon to build module from submodules that some are not visible to the outside world. These are a bit like private modules and don't have an equivalent within the current Java platform.
C.2 Distribution Format for Multiple Module Definitions

JAM is the file format for the module archive that is the physical representation of a module definition. Developers will want to have the ability to package multiple module definitions together as a single bundle for distribution.
153
October 2, 2006 1:33 am

Expert Group Work Items Java Module System, Early Draft Internationalization
C.3 Internationalization
Some developers will want to distribute localized resources separately from a module, often after the module is already deployed. Moreover, if a module has displayable strings in its metadata, the module system should also define how to support localized resources in the metadata.
C.4 Contractual Dependency

Explicit module dependency is the only dependency granularity supported in the Early Draft. It would be very useful if the module dependencies can also be expressed in terms of a contract. A contract is a well defined set of APIs with a name and a version, and the most common form of a contract is a specification. For example, if a module declares a dependency of JAXP 1.3 in its import, the module system could interconnect the module with any module from any vendor that implements all the APIs defined in the JAXP 1.3 specification.
C.5 Missing Dependency Prediction

Some tools and management systems may want to predict missing dependency for a specific module in the repository, so they could go and look for suitable versions. The opaqueness of the repository makes the dependency prediction difficult for tools and management systems. It would be useful if the module system offers support for inquiry of dependency information for a specified module.
C.6 More Explicit Lifecycle

In the server environment, it would be useful to notify a module instance about its lifecycle after it has been fully initialized or before it is completely shutdown, so the module instance may properly allocate and free the resources (e.g. threads, locks, etc.) it uses.
C.7 Interoperability with Other Module Systems

JSR-277 is an architecture that offers first class modularity support in the Java platform. It may be possible to build or rebase other module systems on top of this architecture, so they can take advantages of the built-in modularity and the tight integration between the language, the JVM, and the class libraries in the Java platform.
C.8 Monitoring and Management Support

It could be useful if the module system supports instrumentation in the modules and the repositories on top of the Java Management Extensions (JMX) to make the platform more observable.
10/2/06
154

Locking Strategy for Initializing Module InstancesJava Module System, Early Draft Expert Group Work Items
C.9 Locking Strategy for Initializing Module Instances

Initialization of a module instance requires careful synchronization, and the locking strategy in the algorithm described in Section 8.1.2 remains to be fully worked out.
C.10 Tearing Down Module Instances

When a repository is shutdown, the module instances that are instantiated from the module definitions in the repository may also need to be teared down. However, this issue hits the usual shutdown issues surrounding any multi-threaded service; for example, what happens when a module is being used in one thread and stopped in another? This will happen "accidentally" all the time, and no answers to the embedded policy questions will satisfy everyone, so it could invite a never-ending stream of bug reports.
C.11 Import Policy Override

Developers and deployers sometimes want to control the import policy in a module differently. However, it's clear that no matter what we do, there are plenty of losing strategies in the resulting multi-player game between developers and deployers.
C.12 Refactoring and Refining Abstractions

The abstractions (including the APIs) will be refactored and refined over time as we gain more insights from implementing the reference implementation and working on other work items.
155
October 2, 2006 1:33 am

Expert Group Work Items Java Module System, Early Draft Refactoring and Refining Abstractions
10/2/06
156

Early Draft Java Module System, Early Draft Revision History
Ap pe nd ix D
Revision History
This appendix lists the significant changes that have been made during the development of the JSR-277: Java Module System specification.
D.1 Early Draft

0.121 9/21/2006 Created document.
157
October 2, 2006 1:33 am

JSR-277: Java Module System

Загружено:

Сведения о документе

Исходное описание:

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

JSR-277: Java Module System

Загружено:

Авторское право:

Доступные форматы

Sun Microsystems, Inc.

JSR-277 Expert Group

Java Module System, Early Draft

Sun Microsystems, Inc.

Java Module System, Early Draft

Sun Microsystems, Inc.

Java Module System, Early Draft

Sun Microsystems, Inc.

Sun Microsystems Inc

October 2, 2006 1:34 am

Sun Microsystems Inc.

Sun Microsystems Inc

7.9 7.10 7.11 7.12 Chapter 8

Chapter 10 Chapter 11 Appendix A

October 2, 2006 1:34 am

Sun Microsystems Inc.

Sun Microsystems Inc

October 2, 2006 1:34 am

Sun Microsystems Inc

October 2, 2006 1:33 am

Sun Microsystems Inc.

Sun Microsystems Inc

October 2, 2006 1:33 am

Sun Microsystems Inc.

1.2 Overall Architecture

The Java Module System is compatible with Java SE 7 or later.

1.4 Reflective API

Sun Microsystems Inc

1.5 Development Module and Deployment Module

1.6 Multiple Languages

1.7 JSR-277 Expert Group

October 2, 2006 1:33 am

Sun Microsystems Inc.

1.9 Document Conventions

Sun Microsystems Inc

2.1 What is a Module?

October 2, 2006 1:33 am

Sun Microsystems Inc.

2.2 Module Name

Sun Microsystems Inc

2.3 Module Version

2.4 Module Identity

2.5 Module Metadata

October 2, 2006 1:33 am

Sun Microsystems Inc.

2.6 Module Export

Sun Microsystems Inc

October 2, 2006 1:33 am

Sun Microsystems Inc.

2.7 Module Import

2.7.1 Import with version constraint

Sun Microsystems Inc

2.7.2 Import policy

October 2, 2006 1:33 am

Sun Microsystems Inc.

2.8 Distribution Format

Sun Microsystems Inc

October 2, 2006 1:33 am

Sun Microsystems Inc.

2.12 Platform Binding

2.14 Legacy JAR Files

Sun Microsystems Inc

2.15 Native Libraries