Default Visibility Policy Implementation and File Syntax

The Modules Project was inactive and was subsequently dissolved Oct 2023. The approach described here was superseded by Project Jigsaw.

The visibility policy for the JavaTM module system (specifying which modules in the repositories should be visible to the application at runtime) is represented by a VisibilityPolicy object. More specifically, it is represented by a VisibilityPolicy subclass providing an implementation of the abstract methods in the VisibilityPolicy class (which is in the java.module package).

The source location for the visibility policy information utilized by the VisibilityPolicy object is up to the VisibilityPolicy implementation. The VisibilityPolicy reference implementation obtains its information from static visibility policy configuration files.

The rest of this document pertains to the VisibilityPolicy reference implementation and the syntax that must be used in the visibility policy files it reads.

Default Visibility Policy Implementation

In the VisibilityPolicy reference implementation, the visibility policy can be specified within one or more visibility policy configuration files. The configuration file(s) specify which modules should be visible or invisible at runtime. Each configuration file must be encoded in UTF-8.

A visibility policy file can be composed via a simple text editor.

There is by default a single system-wide visibility policy file, and a single (optional) user visibility policy file.

The VisibilityPolicy reference implementation is initialized when the module system starts up. Initialization involves parsing the visibility policy configuration file(s) (see Visibility Policy File Syntax), and then populating the VisibilityPolicy object.

Default Visibility Policy File Locations

As mentioned previously, there is by default a single system-wide visibility policy file, and a single user visibility policy file.

The system visibility policy file is by default located at

java.home/lib/module/visibility.policy  (Solaris)
java.home\lib\module\visibility.policy  (Win32)

Note: java.home refers to the value of the system property named "java.home", which specifies the directory that houses the runtime environment -- either the jre directory in the JDK or the top-level directory of the Java Runtime Environment.

The system visibility policy file is meant to be a system-wide visibility policy. The visibility.policy file installed with the SDK makes all modules to be visible, allows anyone to use any module in the repositories.

The user visibility policy file is by default located at

user.home/.visibility.policy  (Solaris)
user.home\.visibility.policy  (Win32)

Note: user.home refers to the value of the system property named "user.home", which specifies the user's home directory. On Win32 systems, given user name uName, the "user.home" property value defaults to

C:\Winnt\Profiles\uName on multi-user Windows NT systems
C:\Windows\Profiles\uName on multi-user Windows 95 systems
C:\Windows on single-user Windows 95 systems

When the VisibilityPolicy is initialized, the system visibility policy is loaded in first, and then the user visibility policy is loaded. If neither visibility policy is present, a built-in policy is used. This built-in policy is the same as the visibility.policy file installed with the JRE.

Visibility policy file locations are specified in the module properties file, which is located at

java.home/lib/module/module.properties  (Solaris)
java.home\lib\module\module.properties  (Win32)
As noted above, java.home indicates the directory that houses the runtime environment--either the jre directory in the Java 2 SDK or the top-level directory of the Java Runtime Environment. The visibility policy file locations are specified as the values of properties whose names are of the form 
visibility.policy.url.n
where n is a number. You specify each such property value in a line of the following form: 
visibility.policy.url.n=URL
Here, URL is a URL specification.

For example, the default system and user visibility policy files are defined in the module properties file as

visibility.policy.url.1=file:${java.home}/lib/module/visibility.policy
visibility.policy.url.2=file:${user.home}/.visibility.policy

(See Property Expansion for information about specifying property values via a special syntax, such as specifying the java.home property value via ${java.home}.)

You can actually specify a number of URLs (including ones of the form "http://"), and all the designated visibility policy files will get loaded. You can also comment out or change the second one to disable reading the default user visibility policy file.

The algorithm starts at visibility.policy.url.1, and keeps incrementing until it does not find a URL. Thus if you have visibility.policy.url.1 and visibility.policy.url.3, visibility.policy.url.3 will never be read.

Specifying an Additional Visibility Policy File at Runtime

It is also possible to specify an additional or a different visibility policy file when invoking execution of an application. This can be done via the "-Djava.module.visibility.policy" command line argument, which sets the value of the java.module.visibility.policy property. For example, if you use

    java -Djava.module.visibility.policy=someURL -module SomeModule
where someURL is a URL specifying the location of a visibility policy file, then the specified visibility policy file will be loaded in addition to all the visibility policy files that are specified in the module properties file.

Notes:

If you use

    java -Djava.module.visibility.policy==someURL -module hello
(note the double equals) then just the specified visibility policy file will be used; all the ones indicated in the module properties file will be ignored.

If you want to pass a policy file to the appletviewer, then use a "-J-Djava.module.visibility.policy" argument as follows:

    appletviewer -J-Djava.module.visibility.policy=someURL myApplet
Note:: The "-Djava.module.visibility.policy" policy file value will be ignored (for both java and appletviewer commands) if the "visibility.policy.allowSystemProperty" property in the module properties file is set to false. The default is true.

Changing the Visibility Policy Implementation

An alternative visibility policy class can be given to replace the VisibilityPolicy reference implementation class, as long as the former is a subclass of the abstract VisibilityPolicy class and implements the isVisible method (and other methods as necessary).

The VisibilityPolicy reference implementation can be changed by editing the module properties file, which is the module.properties file in the lib/module directory of the SDK.

One of the types of properties you can set in module.properties is of the following form:

    visibility.policy.class=VisibilityPolicyClassName

VisibilityPolicyClassName must specify the fully qualified name of the desired VisibilityPolicy implementation class. The default module properties file entry for this property is the following:

    visibility.policy.class=sun.module.config.DefaultVisibilityPolicy

To customize, you can change the property value to specify another class, as in

    visibility.policy.class=com.mycom.MyVisibilityPolicy

Visibility Policy File Syntax

The visibility policy configuration file(s) for an SDK installation specify which modules are visible to the application at runtime.

For an application to use a module in a repository, the module must be visible to the application from the repository. In the VisibilityPolicy reference implementation, that module must be considered visible in a visibility policy configuration file.

A visibility policy configuration file essentially contains a list of entries. Each entry has the following syntax:

    +, module-name [, version-constraint]        or
    -, module-name [, version-constraint]

where module-name specifies the name of the module to match, and version-constraint specifies the version constraint of the module to match. version-constraint is optional; if it is omitted, the default version constraint is assumed and it signifies "any version". For example,

    +, p.q.r
    -, x.y.z, [1.0, 2.0)

An entry begins with '+' indicates that the module matches the specified name and version constraint should be visible; an entry begins with '-' indicates the matched module should be invisible.

Note that wildcard can be used in the module-name. An entry with a "*" as the module-name matches all modules. An entry with a trailing ".*" in the module-name matches all modules that have the same module's name prefix. The following table illustrates the different cases.

Module name Module name in Visiblity Policy Match?
p.q.r *
Y
x.y.z *
Y
p.q.r p.q.*
Y
p.q.r.s p.q.*

Y
p.qr p.q.*

N
x.y.z p.q.*
N

To determine if a module should be visible, each entry in the visibility policy is looped through one-by-one, and the first matched entry would determine the visibility of the module. If a module does not match any entry, the default is visible.

Note Regarding Multiple Visibility Policy Files

Each visibility policy configuration file is interpreted independently and effectively forms each own visibility policy. If multiple visibility policy configuration files are used (by specifying them via the module properties file or "-Djava.module.visibility.policy" command line argument), the visibility of a module is determined by ANDing the result from each visibility policy together.

Visibility Policy File Examples

An example of two entries in a visibility policy configuration file is

  // There are some known issues in these modules, thus making 
  // them invisible to the application at runtime.
  //
  -, a.b.c, [1,0, 2.0)
  -, x.y.z, [1,0, 2.0)

In this case, if the two specified modules are in the repositories, they will be invisible to the application at runtime.

The contents of another sample visibility policy configuration file appear below.

  // Make all modules in the repositories invisible, except the 
  // following specified modules.
  //
  +, p.q.r, 1.7.0
  +, f.g.h, 2.1.3
  -, *

In this case, the two specified modules are in the repositories will be the only visible modules to the application at runtime.

Property Expansion

Property expansion is possible in the module properties file. Property expansion is similar to expanding variables in a shell. That is, when a string like 
    ${some.property}
appears in the module properties file, it will be expanded to the value of the system property. For example, 
    visibility.policy.url.2=file:${user.home}/.visibility.policy
will expand "${user.home}" to use the value of the "user.home" system property. If that property's value is "/home/stanleyh", then the above is equivalent to 
    visibility.policy.url.2=file:/home/stanleyh/.visibility.policy