Module java.base

Package java.lang.module

Classes to support module descriptors and creating configurations of modules by means of resolution and service binding.

Unless otherwise noted, passing a null argument to a constructor or method of any class or interface in this package will cause a NullPointerException to be thrown. Additionally, invoking a method with an array or collection containing a null element will cause a NullPointerException, unless otherwise specified.

Module Resolution

Resolution is the process of computing how modules depend on each other. The process occurs at compile time and run time.

Resolution is a two-step process. The first step recursively enumerates the 'requires' directives of a set of root modules. If all the enumerated modules are observable, then the second step computes their readability graph. The readability graph embodies how modules depend on each other, which in turn controls access across module boundaries.

Step 1: Recursive enumeration

Recursive enumeration takes a set of module names, looks up each of their module declarations, and for each module declaration, recursively enumerates:

  • the module names given by the 'requires' directives with the 'transitive' modifier, and

  • at the discretion of the host system, the module names given by the 'requires' directives without the 'transitive' modifier.

Module declarations are looked up in a set of observable modules. The set of observable modules is determined in an implementation specific manner. The set of observable modules may include modules with explicit declarations (that is, with a module-info.java source file or module-info.class file) and modules with implicit declarations (that is, automatic modules). Because an automatic module has no explicit module declaration, it has no 'requires' directives of its own, although its name may be given by a 'requires' directive of an explicit module declaration.

The set of root modules, whose names are the initial input to this algorithm, is determined in an implementation specific manner. The set of root modules may include automatic modules.

If at least one automatic module is enumerated by this algorithm, then every observable automatic module must be enumerated, regardless of whether any of their names are given by 'requires' directives of explicit module declarations.

If any of the following conditions occur, then resolution fails:

  • Any root module is not observable.

  • Any module whose name is given by a 'requires' directive with the 'transitive' modifier is not observable.

  • At the discretion of the host system, any module whose name is given by a 'requires' directive without the 'transitive' modifier is not observable.

  • The algorithm in this step enumerates the same module name twice. This indicates a cycle in the 'requires' directives, disregarding any 'transitive' modifiers.

Otherwise, resolution proceeds to step 2.

Step 2: Computing the readability graph

A 'requires' directive (irrespective of 'transitive') expresses that one module depends on some other module. The effect of the 'transitive' modifier is to cause additional modules to also depend on the other module. If module M 'requires transitive N', then not only does M depend on N, but any module that depends on M also depends on N. This allows M to be refactored so that some or all of its content can be moved to a new module N without breaking modules that have a 'requires M' directive.

Module dependencies are represented by the readability graph. The readability graph is a directed graph whose vertices are the modules enumerated in step 1 and whose edges represent readability between pairs of modules. The edges are specified as follows:

First, readability is determined by the 'requires' directives of the enumerated modules, disregarding any 'transitive' modifiers:

  • For each enumerated module A that 'requires' B: A "reads" B.

  • For each enumerated module X that is automatic: X "reads" every other enumerated module (it is "as if" an automatic module has 'requires' directives for every other enumerated module).

Second, readability is augmented to account for 'transitive' modifiers:

  • For each enumerated module A that "reads" B:

    • If B 'requires transitive' C, then A "reads" C as well as B. This augmentation is recursive: since A "reads" C, if C 'requires transitive' D, then A "reads" D as well as C and B.

    • If B is an automatic module, then A "reads" every other enumerated automatic module. (It is "as if" an automatic module has 'requires transitive' directives for every other enumerated automatic module).

Finally, every module "reads" itself.

If any of the following conditions occur in the readability graph, then resolution fails:

  • A module "reads" two or more modules with the same name. This includes the case where a module "reads" another with the same name as itself.

  • Two or more modules export a package with the same name to a module that "reads" both. This includes the case where a module M containing package p "reads" another module that exports p to M.

  • A module M declares that it 'uses p.S' or 'provides p.S with ...' but package p is neither in module M nor exported to M by any module that M "reads".

Otherwise, resolution succeeds, and the result of resolution is the readability graph.

Root modules

The set of root modules at compile-time is usually the set of modules being compiled. At run-time, the set of root modules is usually the application module specified to the 'java' launcher. When compiling code in the unnamed module, or at run-time when the main application class is loaded from the class path, then the default set of root modules is implementation specific (In the JDK implementation it is the module "java.se", if observable, and every observable module that exports an API).

Observable modules

The set of observable modules at both compile-time and run-time is determined by searching several different paths, and also by searching the compiled modules built in to the environment. The search order is as follows:

  1. At compile time only, the compilation module path. This path contains module definitions in source form.

  2. The upgrade module path. This path contains compiled definitions of modules that will be observed in preference to the compiled definitions of any upgradeable modules that are present in (3) and (4). See the Java SE Platform for the designation of which standard modules are upgradeable.

  3. The system modules, which are the compiled definitions built in to the environment.

  4. The application module path. This path contains compiled definitions of library and application modules.

'requires' directives with 'static' modifier

'requires' directives that have the 'static' modifier express an optional dependence at run time. If a module declares that it 'requires static M' then resolution does not search the observable modules for M to satisfy the dependency. However, if M is recursively enumerated at step 1 then all modules that are enumerated and `requires static M` will read M.

Completeness

Resolution may be partial at compile-time in that the complete transitive closure may not be required to compile a set of modules. Minimally, the readability graph that is constructed and validated at compile-time includes the modules being compiled, their direct dependences, and all implicitly declared dependences (requires transitive).

At run-time, resolution is an additive process. The recursive enumeration at step 1 may be relative to previous resolutions so that a root module, or a module named in a 'requires' directive, is not enumerated when it was enumerated by a previous (or parent) resolution. The readability graph that is the result of resolution may therefore have a vertex for a module enumerated in step 1 but with an edge to represent that the module reads a module that was enumerated by previous (or parent) resolution.

Since:
9