Java SE 9 ( JSR 379) (original) (raw)

A module is a named set of packages designed for reuse. A specification governed by the JCP defines standard packages, and may group them into one or more standard modules.

This Specification groups the standard packages of the Java SE Platform into 26 standard modules, which we refer to as the Java SE modules. The name of a Java SE module always starts with the string"java.". The complete list of such modules is:

java.activation java.base java.compiler java.corba java.datatransfer java.desktop java.instrument java.logging java.management	java.management.rmi java.naming java.prefs java.rmi java.scripting java.se java.se.ee java.security.jgss java.security.sasl	java.sql java.sql.rowset java.transaction java.xml java.xml.bind java.xml.crypto java.xml.ws java.xml.ws.annotation

Using the Java Platform Module System, specified by JSR 376, these modules may be combined at compile time, build time, or run time into a variety of configurations including, but not limited to:

• A configuration corresponding to the full Java SE Platform;
• Configurations roughly equivalent in content to each of the Compact Profiles defined inJava SE 8; and
• Custom configurations which contain only a specified set of modules, possibly augmented by external library and application modules, and the modules transitively required by all of these modules.

The module graph A module is a named set of packages designed for reuse, and it can depend upon one or more other modules. A set of related modules can therefore be seen as a directed graph, in which each module is a node and there is an edge from one module to another if the first depends upon the second. The module system guarantees that module graphs are acyclic.

The Java SE modules depend upon each other as stated in their specifications, which are part of the overall API Specification. The corresponding complete Java SE module graph has too many edges to be displayed easily in visual form; here is the transitive reduction of the graph, in which redundant edges are omitted (click to enlarge):

Here is how to read this visualization of the module graph:

• If one module depends upon another, and it grants implied readability to that module via a requires transitive directive, then there is a dark-gray edge from the first module to the second.
• At the very bottom is the java.base module, which contains essential classes such as java.lang.Object andjava.lang.String. The base module depends upon no module, and every other module depends upon the base module. Edges to the base module are lighter than other edges.
• At the top is the java.se.ee module, which gathers together all of the modules that comprise the Java SE Platform, including modules whose exported packages overlap with the Java EE Platform Specification. This is an example of an aggregator module, which logically gathers the content of other modules by granting implied readability to them, but adds no content of its own. A run-time system configured to contain the java.se.ee module will contain all of the packages of the Java SE Platform. A module is considered part of the Java SE Platform Specification if, and only if, it is a standard module reachable from the java.se.ee module.
• The java.se aggregator module gathers together those parts of the Java SE Platform, other than the CORBA APIs, that do not overlap with Java EE.

The module graph is an entirely new aspect of the Java SE Platform Specification. It will evolve over time just like any other API, and with the same degree of care and caution. Removing a module or changing it incompatibly, in particular, will require public notice at least one major release in advance.

Constraints on Java SE modules Each Java SE module is subject to the following constraints:

1. A Java SE module must fully implement the corresponding part of this Specification. It must, in particular, implement every API element of that module including the module’s name, its exported packages, and any requires transitive dependences.
2. If a Java SE module exports a package that contains a type that contains a public or protected member that, in turn, refers to a type from some other Java SE module, then the first module must grant implied readability to the second, via a requires transitive directive. (This ensures that method-invocation chaining works in the obvious way.)
3. A Java SE module must export its standard packages without qualification.
4. A Java SE module may export non-standard packages, in which case the exports must be qualified. The targets of such exports need not themselves be SE modules, but they are intended to be limited to modules that are intimately associated with the implementations of one or more SE modules.
5. A Java SE module may depend upon one or more non-SE modules. It must not grant implied readability to any non-SE module.

An important consequence of constraints 3, 4, and 5 is that user code that depends only upon Java SE modules will depend only upon types declared in the standard packages of the Java SE Platform, and thus be portable to all Implementations of the Platform that include the necessary Java SE modules.

Constraints on all modules in an Implementation A module is said to be included in an Implementation of the Java SE Platform if, and only if, the module is an observable system module. An Implementation may, and typically will, include modules that are not Java SE modules but, rather, specific to the Implementation. An Implementation may also, in the case of a custom configuration, include additional library and application modules.

Every Implementation is subject to the following constraints upon the modules that it includes:

1. An Implementation must include the java.base module.
2. An Implementation may include one or more additional Java SE modules so long as the set of SE modules that the Implementation includes is closed, i.e., includes every SE module required, viarequires transitive directives, by any member of the set.
   For example, an Implementation that includes just thejava.base, java.sql, java.logging, andjava.xml modules is closed because the only requires transitive dependences are from java.sql tojava.logging and java.xml, and the latter two modules are members of the set.
3. An Implementation may include standard modules that are not Java SE modules, i.e., modules whose specifications are governed by the JCP but which are not part of the Java SE Platform.
4. An Implementation may include one or more non-standard modules. The name of a non-standard module must not start with the string "java.". A non-standard module must not export any standard packages. A non-standard module may grant implied readability to a standard module.

The Technology Compatibility Kit (TCK) for this Specification will test all of the Java SE modules included in an Implementation, and it will require that set to be closed. An Implementation that passes the TCK is considered to fully implement this Specification even if it does not include all of the Java SE modules.

This Specification defines the Licensor Name Space on a module-by-module basis. Provided that an Implementation that fully implements this Specification includes the required Licensor Name Space for each included module then it is not considered to subset the Licensor Name Space.

An Implementation of this Specification may provide a means to create further Implementations. If it does so then any such new Implementation need not include all of the modules present in the original Implementation, but it must satisfy the constraints of the preceding paragraphs.

Relaxing strong encapsulation As an aid to migration, an Implementation may relax the strong encapsulation of the modules that it includes as follows:

• An Implementation may provide a means to invoke its run-time system with one or more packages of one or more of its modules open to code in all unnamed modules, i.e., to code on the class path. If the run-time system is invoked in this way, and if by doing so some invocations of the reflection APIs succeed where otherwise they would have failed, then the first such invocation must cause a warning to be issued on the standard error stream. Later such invocations may also cause warnings to be issued.
• An Implementation may, by default, open one or more packages of one or more of its modules to code in all unnamed modules at run time. If it does so then it must issue warnings as described in the previous paragraph. If it does so then it must, further, provide a means to invoke its run-time system without opening any packages of any of its modules.
  (The Reference Implementation’s run-time system behaves this way by default, and because this is the default it can also be invoked without opening any of its packages via the command-line option--illegal-access=deny.)

Future revisions of this Specification are expected to mandate that all of an Implementation’s modules be strongly encapsulated by default and, eventually, to disallow the above-described relaxation.

Overriding module declarations As a further aid to migration, an Implementation may provide a means establish additional relationships between specific modules, identified by name, regardless of the original declarations of those modules and regardless of whether those modules are included in the Implementation or are part of the application being compiled or run:

• One module can be made to read another module, at compile time or at run time.
  (The Reference Implementation provides this capability via the--add-reads command-line option.)
• A package of one module can be opened to another module, at run time.
  (The Reference Implementation provides this capability via the--add-opens command-line option.)
• A package of one module can be exported to another module, at compile time or at run time.
  (The Reference Implementation provides this capability via the--add-exports command-line option.)
• A package of one module can be opened or exported to every unnamed module, at compile time or at run time.
  (The Reference Implementation provides this capability by allowing the special token ALL-UNNAMED to be used as a target of the--add-opens and --add-exports command-line options.)

None of these capabilities, for any modules, may be operative by default. A future revision of this Specification may disallow these capabilities.

Upgradeable modules This Specification permits the user to replace certain APIs in an Implementation of the Java SE Platform with newer versions, without making any changes to that Implementation.

Two kinds of APIs are subject to replacement. First, there are APIs in the Java SE Platform that correspond to standards maintained outside of the Java Community Process, such as CORBA. Second, there are APIs in the Java SE Platform that evolve with the Platform via the Java Community Process, but which are intended to be usable on their own, i.e.,standalone, on versions of the Platform other than the version where they were developed.

Prior to Java SE 9, the Endorsed Standards Override Mechanism allowed the replacement of individual packages in APIs maintained outside of the JCP, but allowed only a complete replacement of APIs evolved via the JCP. Java SE 9 takes advantage of the modular structure of the Platform to allow the replacement of both kinds of APIs, and their implementations, on a uniform module-by-module basis. Specifically, Java SE 9 categorizes each module in an Implementation as either upgradeable or non-upgradeable, and allows an upgradeable module to be replaced by the user without modifying or re-building the Implementation.

An Implementation of the Java SE 9 Platform must provide a means to replace those modules which are categorized as upgradeable, and must not provide a means to replace those modules which are categorized as non-upgradeable. The rules for categorizing a module are as follows:

• A Java SE module is upgradeable if, and only if, it defines an API that is subject to replacement. Only a small number of Java SE modules fall into this category. Examples are thejava.corba module, which corresponds to a standard maintained outside of the Java Community Process, and thejava.transaction and java.xml.bind modules, which are intended to be usable standalone.
• A Java SE module is non-upgradeable if it is essential to the integrity of the Platform. Most Java SE modules fall into this category, for example java.base, java.xml, andjava.management.
• A non-Java SE module is upgradeable unless the Implementation deems otherwise. Custom configurations may include non-Java SE library and application modules which it is convenient to upgrade in an atomic fashion. Creators of such configurations should take care to ensure that qualified exports that target such modules cannot be abused if one or more of those modules is upgraded.

In order to replace an upgradeable module, the user supplies an alternate version which the Implementation observes in preference to the version included in the Implementation. The alternate version must have the same module name. It will typically export APIs that are newer than those exported by the version in the Implementation, although an Implementation is not required to enforce this property. The alternate version may be provided in the form of a JAR file that defines an automatic module.

(The Reference Implementation provides this capability via the--upgrade-module-path command-line option.)

The specification of an upgradeable Java SE module will indicate that it is upgradeable. If the specification of a Java SE module does not indicate that the module is upgradeable then it is not upgradeable. For reference, the set of upgradeable modules in the Java SE 9 platform is:

java.activation java.compiler java.corba java.transaction	java.xml.bind java.xml.ws java.xml.ws.annotation

In Java SE 9, all of the Java SE modules that are upgradeable have been deprecated for removal, except for the java.compiler module.

This Specification does not define a standard means to specify whether an arbitrary library or application module is upgradeable, nor does it define a standard means to ensure the integrity of a set of related library or application modules. The creators of future versions of this Specification are encouraged to consider these requirements.

Configuration files Minor changes to the API specifications of StAX, JAX-WS, and SAAJ were necessary in order to change how their factory methods locate service provider implementations in the modular platform. For StAX, the changes are specified directly in this Umbrella Platform Specification. For JAX-WS and SAAJ, the changes are specified in Maintenance Releases of their Component JSR Specifications.