jsr-277: java module system

8/6/2019 JSR-277: Java Module System

1/162

JSR-277 Expert Group

Specification Lead: Stanley M. Ho, Sun Microsystems, Inc.

Date: October 2, 2006

Please send comments to: [email protected]

EARLY

DRA

FT

Sun Microsystems, Inc.

JSR-277: JavaTM Module System


2/162

Java Module System, Early Draft Sun Microsystems, Inc.

ii 10/2/06

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 follow-

ing 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 Speci-fication and the information described therein will be governed by the terms and conditions of this Agree-

ment.

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 implementa-

tions 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 signifi-cant portion of the Technology.

2.Distribute implementations of the Specification to third parties for their testing and evaluation use, pro-

vided 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 "INCOM-

PATIBLE" 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 contin-

gent upon your agreement to terminate development and distribution of your "early draft" implementa-

tion 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.


3/162


iii 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 ad-dition, 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, IN-

CLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A

PARTICULAR PURPOSE, OR NON-INFRINGEMENT THAT THE CONTENTS OF THE SPECIFI-

CATION ARE SUITABLE FOR ANY PURPOSE OR THAT ANY PRACTICE OR IMPLEMENTA-

TION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS,

COPYRIGHTS, TRADE SECRETS OR OTHER RIGHTS. This document does not represent any com-

mitment 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 SPECIFICA-

TION, 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 PU-

NITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILI-

TY, 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 AD-

VISED OF THE POSSIBILITY OF SUCH DAMAGES.


4/162


iv 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 Feed-

back, you hereby: (i) agree that such Feedback is provided on a non-proprietary and non-confidential ba-

sis, 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 lim-

itation 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 regula-

tions in other countries. Licensee agrees to comply strictly with all such laws and regulations and ac-knowledges 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 com-

munication between the parties relating to its subject matter during the term of this Agreement. No mod-

ification to this Agreement will be binding, unless in writing and signed by an authorized representative

of each party.


5/162

Java Module System, Early Draft

1 October 2, 2006 1:34 am

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

Chapter 2 Fundamentals................................................................................................................. 112.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 ....................................................................................................... 192.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

Chapter 3 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


6/162


10/2/06 2

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.....................................................................294.1.3 Trying it out....................................................................................... 30

4.2 Scenario 2: Adding Bug Fixes......................................................................... 30


4.2.2 Trying it out....................................................................................... 31

4.3 Scenario 3: Adding New Features ................................................................... 32


4.3.2 Trying it out....................................................................................... 33

4.4 Scenario 4: Making Incompatible Changes..................................................... 34


4.4.2 Develop the application.....................................................................35

4.4.3 Trying it out....................................................................................... 36

Chapter 5 Versioning ...................................................................................................................... 39

5.1 Version............................................................................................................. 39

5.1.1 Versioning Policy .............................................................................. 42

5.2 Version Range.................................................................................................. 43

5.3 Version Constraint ........................................................................................... 45

Chapter 6 Distribution Format........................................................................................................ 47

6.1 Overview ......................................................................................................... 47

6.2 File Contents.................................................................................................... 48

6.2.1 Metadata ............................................................................................ 48

6.2.2 Resources .......................................................................................... 486.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

Chapter 7 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


7/162


3 October 2, 2006 1:34 am


7.9 Insulating Module Definitions......................................................................... 59

7.10 Local Repository ............................................................................................. 60

7.11 URL Repository .............................................................................................. 60

7.12 Notes to Repository Implementors.................................................................. 62

Chapter 8 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

Chapter 9 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

Chapter 10 Related Documents........................................................................................................ 83

Chapter 11 Glossary ......................................................................................................................... 85

Appendix A 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 ....................................................................... 93A.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


8/162


10/2/06 4


A.10 java.lang.module.ModuleDefinitionContent ................................................... 104

A.11 java.lang.module.ModuleFileFormatError ...................................................... 106

A.12 java.lang.module.ModuleSystemPermission................................................... 107

A.13 java.lang.module.Query................................................................................... 109A.14 java.lang.module.Repository ........................................................................... 112

A.15 java.lang.module.RepositoryCircularityError ................................................. 118

A.16 java.lang.module.RepositoryFactory............................................................... 119

A.17 java.lang.module.ResolveError ....................................................................... 120

A.18 java.lang.module.URLRepository ................................................................... 121

A.19 java.lang.module.ValidationException............................................................ 123

A.20 java.lang.module.Version ................................................................................ 124

A.21 java.lang.module.VersionFormatException..................................................... 127

A.22 java.lang.module.annotation.ExportResources ............................................... 128

A.23 java.lang.module.annotation.ImportPolicyClass ............................................. 129

A.24 java.lang.module.annotation.MainClass.......................................................... 130A.25 java.lang.module.annotation.ModuleAttribute................................................ 131

A.26 java.lang.module.annotation.ModuleAttributes .............................................. 132

A.27 java.lang.module.annotation.NativeLibraryPath ............................................. 133

A.28 java.lang.module.annotation.NativeLibraryPaths ........................................... 134

A.29 java.lang.module.annotation.PlatformBinding................................................ 135

A.30 java.lang.module.annotation.ReexportResources............................................ 136

A.31 java.lang.module.annotation.SearchPath......................................................... 137

A.32 java.lang.module.annotation.SkipValidation ................................................... 138

A.33 java.lang.module.annotation.Version...............................................................139

A.34 java.lang.module.annotation.VersionConstraint.............................................. 140

A.35 java.lang.module.spi.ModuleDefinitionProvider ............................................ 141A.36 java.lang.module.spi.ModuleProvider............................................................. 144

A.37 java.lang.module.spi.RepositoryProvider........................................................ 145

A.38 Schema: URL Repository Metadata ................................................................ 147

Appendix B 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 def-

inition 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


9/162


5 October 2, 2006 1:34 am


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

Appendix D Revision History ............................................................................................................ 157

D.1 Early Draft....................................................................................................... 157


10/162

5 October 2, 2006 1:33 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 [email protected].


11/162

Preface Java Module System, Early Draft

10/2/06 6



12/162

Background Java Module System, Early Draft Introduction

7 October 2, 2006 1:33 am


Chapter 1 Introduction

Java Module System is an architecture for the development and the deployment of module-based appli-

cations 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 Launch-ing 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


13/162

Introduction Java Module System, Early Draft Overall Architecture

10/2/06 8


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 themodule, 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 sophis-ticated module-based applications.

1.4 Reflective API

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


14/162

Development Module and Deployment Module Java Module System, Early Draft Introduction

9 October 2, 2006 1:33 am


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 Program-

ming 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 coversthe 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 con-

text. 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 Pro-

cess 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 Hir-

sch; 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.


15/162

Introduction Java Module System, Early Draft Acknowledgements

10/2/06 10


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 Kow-

alski, 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 describ-

ing typical use, or notes clarifying the text with prescriptive specification.

The Courier font is used for code examples.


16/162

What is a Module? Java Module System, Early Draft Fundamentals

11 October 2, 2006 1:33 am


Chapter 2 Fundamentals

2.1 What is a Module?

The notion ofmodule 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 pack-

aged together with classes and other resources as a deploymentmodule.

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.


17/162

Fundamentals Java Module System, Early Draft Module Name

10/2/06 12


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 cre-

ates 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 mod-

ule 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.xmlcom.wombat.webservice


18/162

Module Version Java Module System, Early Draft Fundamentals

13 October 2, 2006 1:33 am


2.3 Module Version

Each module has a version. The version must follow the versioning scheme described in Chapter 5: Ver-

sioning. 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.02.3.43.2.1.95.6.7.8-b30-alpha

2.4 Module Identity

The identity of a module definition is represented by a modules name and version. Two ModuleDef-

inition 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])

wherename: Name of the module.extensible-metadata: Version, main class, attributes, resource export list, etc.imports: Imported modules.class-exports: Class export list.members: List of classes that belong to the module membership.

The name, imports, class-exports, and members elements are mandatory, and the exten-

sible-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.


19/162

Fundamentals Java Module System, Early Draft Module Export

10/2/06 14


Example: Content of the metadata in a module definition

(name=

com.wombat.webserviceextensible-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 ser-

vice 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 ser-

vice providers from the modules in the repository.

The format of the metadata will be defined in JSR-294: Improved Modularity Support in the Java Pro-

gramming 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.


20/162

Module Export Java Module System, Early Draft Fundamentals

15 October 2, 2006 1:33 am


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 listis for defining what classes

are visible to other modules at build-time and after the module is interconnected at run time. The

resource export listis for defining what resources are visible to other modules at run time after the mod-

ule 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})


21/162

Fundamentals Java Module System, Early Draft Module Import

10/2/06 16


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 sub-

directories 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 theimporting 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 con-

straint. 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.


22/162

Module Import Java Module System, Early Draft Fundamentals

17 October 2, 2006 1:33 am


Example: Import module with version constraint

// Import the highest version of com.wombat.webserviceImportModule(com.wombat.webservice)

// Import org.foo.xml version 1.3.0 preciselyImportModule(org.foo.xml, @VersionConstraint(1.3.0))

// Import org.foo.soap 2.0.0 or laterImportModule(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 require-

ments instead.

2.7.2 Import policy

The import policy is a mechanism for a module instance to interconnect its imported modules with cus-

tom requirements through a piece of Java code. It is responsible for ensuring that instances of the asso-

ciated 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 constructedprivate 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.0ModuleDefinition xml = repos.find(org.foo.xml,

Query.parse(1.0.0));


23/162

Fundamentals Java Module System, Early Draft Distribution Format

10/2/06 18


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-classis 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 mod-

ule system will load and execute the code to interconnect the dependent modules. Otherwise, the mod-

ule 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 onthe 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 def-

inition and the Java code; he then packages the metadata, the classes, and other resources into a module

archive for distribution.


24/162

Repository Java Module System, Early Draft Fundamentals

19 October 2, 2006 1:33 am


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 mod-

ule 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 nei-

ther 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 net-

work 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 reflec-

tion 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 ischecked 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


25/162

Fundamentals Java Module System, Early Draft Platform Binding

10/2/06 20


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 defi-

nition. 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 onthe 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 mod-

ule 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 mod-

ules.

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.


26/162

Native Libraries Java Module System, Early Draft Fundamentals

21 October 2, 2006 1:33 am


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 run-

ning 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 meta-

data 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 laterjava -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 havethe 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.).


27/162

Fundamentals Java Module System, Early Draft Tools Support

10/2/06 22


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 class-

loader 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 mod-

ule 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 defini-

tions, 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 defini-

tion 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. Never-

theless, we do anticipate many higher level tools and frameworks will build upon the module system to

provide greater convenience and ease of use.


28/162

Source Code Java Module System, Early Draft Note on Development Module

23 October 2, 2006 1:33 am


Chapter 3 Note on Development Module

The development module will be defined in JSR-294: Improved Modularity Support in the Java Pro-

gramming 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 pro-gramming language:

Example: Development module

@Version(1.0) // module annotationsuper package com.wombat.webservice { // module name

// imported module(s)@VersionConstraint(1.0+)


29/162

Note on Development Module Java Module System, Early Draft Compiling a Development Module

10/2/06 24


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 membershipx.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 anotherdevelopment 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 ver-

sioning 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 sourcefor 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 develop-ment modules.


30/162

Integration between JSR-277 and JSR-294 Java Module System, Early Draft Note on Development Module

25 October 2, 2006 1:33 am


(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 neces-

sary for maintaining the development module semantics.

Example: Module file

METADATA.module:(name=

com.wombat.webserviceextensible-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 mod-

ule, 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 formaintaining 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.annota-

tion package that can be used to decorate development modules. Please refer to Appendix A.22 to

A.33for more details.

[3] The metadata annotation types are under the java.lang.module.annotation package although they are not expanded inthe examples.

[4] The wildcards in a development module are expected to be expanded by the compiler when the module file is generated.


31/162

Note on Development Module Java Module System, Early Draft Decorating a Development Module

10/2/06 26


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 membershiporg.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]

)


32/162

Scenario 1: Creating New Modules Java Module System, Early Draft Scenarios

27 October 2, 2006 1:33 am


Chapter 4 Scenarios

To help illustrate how Java modules are developed and function, this chapter walks through a few sam-

ple scenarios. It is intended to show some ways modules may be used, but not to describe all possibili-

ties.

No significance should be attached to the form of the source code, the artifacts for the developmentmodule, 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. The developer writes a number of Java classes that are part of the utility library.

2. 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 informa-

tion about the module definition, such as the modules version, etc.


33/162

Scenarios Java Module System, Early Draft Scenario 1: Creating New Modules

10/2/06 28


@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 membershipcom.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 using the compiler. The compilation results in a mod-

ule file and several class files. Specifically, one class file is generated for each class and inter-

face 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.libraryextensible-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


34/162

Scenario 1: Creating New Modules Java Module System, Early Draft Scenarios

29 October 2, 2006 1:33 am


4.1.2 Develop the application

1. The developer writes a number of Java classes that compose the application.

2. The developer writes a development module for the application. Since the application is exe-

cutable, 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


35/162

Scenarios Java Module System, Early Draft Scenario 2: Adding Bug Fixes

10/2/06 30


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]

)

5. 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. The developer deploys the application and the library into the repository of the module system.

2. The developer then runs the application using the launcher. e.g.,java -module com.sun.cool.app

3. The launcher finds the highest version ofcom.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 ini-

tializing and resolving its imports, the module system interconnects it with a module instance

ofcom.sun.cool.library. After the module instance ofcom.sun.cool.app is ini-

tialized, the launcher loads and invokes the main class from the module class loader.

4. The result is a running application that uses the utility library.

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.


36/162

Scenario 2: Adding Bug Fixes Java Module System, Early Draft Scenarios

31 October 2, 2006 1:33 am


2. Because the change is a bug fix that doesnt affect compatibility, the developer follows the ver-

sioning 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 membershipcom.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=


[@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


37/162

Scenarios Java Module System, Early Draft Scenario 3: Adding New Features

10/2/06 32


repository. The repository already has com.sun.cool.app 1.0.0 and

com.sun.cool.library 1.0.0 installed.

2. The developer executes the application using the launcher.

3. 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 ofcom.sun.cool.library

1.0.0.1. After the module instance ofcom.sun.cool.app is fully initialized, the launcher

loads and invokes the main class from the module class loader.

4. The result is a running application that uses the new utility library which contains the fix. The

application itself has not been changed.

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.

2. 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 membershipcom.sun.cool.library.ClassA;com.sun.cool.library.InterfaceB;com.sun.cool.library.PrivateClassC;com.sun.cool.library.FeatureXClass;


38/162

Scenario 3: Adding New Features Java Module System, Early Draft Scenarios

33 October 2, 2006 1:33 am


com.sun.cool.library.morePrivateClass;com.sun.cool.library.abc.moreStuff;

// no import

}

3. The developer compiles the source files, and the compilation results in a module file and mul-

tiple class files.METADATA.module:(name=


[@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 repos-

itory. 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.


39/162

Scenarios Java Module System, Early Draft Scenario 4: Making Incompatible Changes

10/2/06 34


2. The developer runs the application using the launcher.

3. 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 ofcom.sun.cool.app is

fully initialized, the launcher loads and invokes the main class from the module class loader.

4. The result is a running application that uses the new utility library which provides the new fea-

ture and the performance improvement. The application itself has not been changed.

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. The developer writes a number of Java classes that are part of the utility library.

2. 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 membershipcom.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;

// no import}

3. The developer compiles the source files, and the compilation results in a module file and sev-eral class files.METADATA.module:(name=



40/162

Scenario 4: Making Incompatible Changes Java Module System, Early Draft Scenarios

35 October 2, 2006 1:33 am


[@Version(2.0.0),@ExportResources({

icons/clea