jsr-277: java module system
TRANSCRIPT
-
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
-
8/6/2019 JSR-277: Java 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.
-
8/6/2019 JSR-277: Java Module System
3/162
Java Module System, Early Draft Sun Microsystems, Inc.
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.
-
8/6/2019 JSR-277: Java Module System
4/162
Java Module System, Early Draft Sun Microsystems, Inc.
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.
-
8/6/2019 JSR-277: Java Module System
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
-
8/6/2019 JSR-277: Java Module System
6/162
Java Module System, Early Draft
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.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
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
-
8/6/2019 JSR-277: Java Module System
7/162
Java Module System, Early Draft
3 October 2, 2006 1:34 am
Sun Microsystems Inc
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/6/2019 JSR-277: Java Module System
8/162
Java Module System, Early Draft
10/2/06 4
Sun Microsystems Inc.
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
-
8/6/2019 JSR-277: Java Module System
9/162
Java Module System, Early Draft
5 October 2, 2006 1:34 am
Sun Microsystems Inc
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
-
8/6/2019 JSR-277: Java Module System
10/162
5 October 2, 2006 1:33 am
Java Module System, Early Draft
Sun Microsystems Inc
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].
-
8/6/2019 JSR-277: Java Module System
11/162
Preface Java Module System, Early Draft
10/2/06 6
Sun Microsystems Inc.
-
8/6/2019 JSR-277: Java Module System
12/162
Background Java Module System, Early Draft Introduction
7 October 2, 2006 1:33 am
Sun Microsystems Inc
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
-
8/6/2019 JSR-277: Java Module System
13/162
Introduction Java Module System, Early Draft Overall Architecture
10/2/06 8
Sun Microsystems Inc.
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
-
8/6/2019 JSR-277: Java Module System
14/162
Development Module and Deployment Module Java Module System, Early Draft Introduction
9 October 2, 2006 1:33 am
Sun Microsystems Inc
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.
-
8/6/2019 JSR-277: Java Module System
15/162
Introduction Java Module System, Early Draft Acknowledgements
10/2/06 10
Sun Microsystems Inc.
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.
-
8/6/2019 JSR-277: Java Module System
16/162
What is a Module? Java Module System, Early Draft Fundamentals
11 October 2, 2006 1:33 am
Sun Microsystems Inc
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.
-
8/6/2019 JSR-277: Java Module System
17/162
Fundamentals Java Module System, Early Draft Module Name
10/2/06 12
Sun Microsystems Inc.
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
-
8/6/2019 JSR-277: Java Module System
18/162
Module Version Java Module System, Early Draft Fundamentals
13 October 2, 2006 1:33 am
Sun Microsystems Inc
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.
-
8/6/2019 JSR-277: Java Module System
19/162
Fundamentals Java Module System, Early Draft Module Export
10/2/06 14
Sun Microsystems Inc.
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.
-
8/6/2019 JSR-277: Java Module System
20/162
Module Export Java Module System, Early Draft Fundamentals
15 October 2, 2006 1:33 am
Sun Microsystems Inc
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})
-
8/6/2019 JSR-277: Java Module System
21/162
Fundamentals Java Module System, Early Draft Module Import
10/2/06 16
Sun Microsystems Inc.
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.
-
8/6/2019 JSR-277: Java Module System
22/162
Module Import Java Module System, Early Draft Fundamentals
17 October 2, 2006 1:33 am
Sun Microsystems Inc
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));
-
8/6/2019 JSR-277: Java Module System
23/162
Fundamentals Java Module System, Early Draft Distribution Format
10/2/06 18
Sun Microsystems Inc.
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.
-
8/6/2019 JSR-277: Java Module System
24/162
Repository Java Module System, Early Draft Fundamentals
19 October 2, 2006 1:33 am
Sun Microsystems Inc
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
-
8/6/2019 JSR-277: Java Module System
25/162
Fundamentals Java Module System, Early Draft Platform Binding
10/2/06 20
Sun Microsystems Inc.
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.
-
8/6/2019 JSR-277: Java Module System
26/162
Native Libraries Java Module System, Early Draft Fundamentals
21 October 2, 2006 1:33 am
Sun Microsystems Inc
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.).
-
8/6/2019 JSR-277: Java Module System
27/162
Fundamentals Java Module System, Early Draft Tools Support
10/2/06 22
Sun Microsystems Inc.
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.
-
8/6/2019 JSR-277: Java Module System
28/162
Source Code Java Module System, Early Draft Note on Development Module
23 October 2, 2006 1:33 am
Sun Microsystems Inc
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+)
-
8/6/2019 JSR-277: Java Module System
29/162
Note on Development Module Java Module System, Early Draft Compiling a Development Module
10/2/06 24
Sun Microsystems Inc.
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 sup- port 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.
-
8/6/2019 JSR-277: Java Module System
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
Sun Microsystems Inc
(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.
-
8/6/2019 JSR-277: Java Module System
31/162
Note on Development Module Java Module System, Early Draft Decorating a Development Module
10/2/06 26
Sun Microsystems Inc.
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]
)
-
8/6/2019 JSR-277: Java Module System
32/162
Scenario 1: Creating New Modules Java Module System, Early Draft Scenarios
27 October 2, 2006 1:33 am
Sun Microsystems Inc
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.
-
8/6/2019 JSR-277: Java Module System
33/162
Scenarios Java Module System, Early Draft Scenario 1: Creating New Modules
10/2/06 28
Sun Microsystems Inc.
@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
-
8/6/2019 JSR-277: Java Module System
34/162
Scenario 1: Creating New Modules Java Module System, Early Draft Scenarios
29 October 2, 2006 1:33 am
Sun Microsystems Inc
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
-
8/6/2019 JSR-277: Java Module System
35/162
Scenarios Java Module System, Early Draft Scenario 2: Adding Bug Fixes
10/2/06 30
Sun Microsystems Inc.
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.
4.2.1 Develop the library
1. The developer identifies the bug in the utility library, and puts the fix in the source code.
-
8/6/2019 JSR-277: Java Module System
36/162
Scenario 2: Adding Bug Fixes Java Module System, Early Draft Scenarios
31 October 2, 2006 1:33 am
Sun Microsystems Inc
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=
com.sun.cool.libraryextensible-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
-
8/6/2019 JSR-277: Java Module System
37/162
Scenarios Java Module System, Early Draft Scenario 3: Adding New Features
10/2/06 32
Sun Microsystems Inc.
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.
4.3.1 Develop the library
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;
-
8/6/2019 JSR-277: Java Module System
38/162
Scenario 3: Adding New Features Java Module System, Early Draft Scenarios
33 October 2, 2006 1:33 am
Sun Microsystems Inc
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=
com.sun.cool.libraryextensible-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 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.
-
8/6/2019 JSR-277: Java Module System
39/162
Scenarios Java Module System, Early Draft Scenario 4: Making Incompatible Changes
10/2/06 34
Sun Microsystems Inc.
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.
4.4.1 Develop the library
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=
com.sun.cool.libraryextensible-metadata=
-
8/6/2019 JSR-277: Java Module System
40/162
Scenario 4: Making Incompatible Changes Java Module System, Early Draft Scenarios
35 October 2, 2006 1:33 am
Sun Microsystems Inc
[@Version(2.0.0),@ExportResources({
icons/clea