JEP 396: Strongly Encapsulate JDK Internals by Default

AuthorsAlex Buckley, Mark Reinhold
OwnerMark Reinhold
StatusClosed / Delivered
Discussionjigsaw dash dev at openjdk dot java dot net
Relates toJEP 261: Module System
JEP 260: Encapsulate Most Internal APIs
JEP 403: Strongly Encapsulate JDK Internals
Reviewed byAlan Bateman, Chris Hegarty, Mandy Chung
Endorsed byBrian Goetz
Created2020/10/23 19:41
Updated2024/04/28 18:08


Strongly encapsulate all internal elements of the JDK by default, except for critical internal APIs such as sun.misc.Unsafe. Allow end users to choose the relaxed strong encapsulation that has been the default since JDK 9.




Over the years the developers of various libraries, frameworks, tools, and applications have used internal elements of the JDK in ways that compromise both security and maintainability. In particular:

In Java 9, we improved both the security and the maintainability of the JDK by leveraging modules to limit access to its internal elements. Modules provide strong encapsulation, which means that

Strong encapsulation applies at both compile time and run time, including when compiled code attempts to access elements via reflection at run time. The non-public elements of exported packages, and all elements of unexported packages, are said to be strongly encapsulated.

In JDK 9 and later releases we strongly encapsulated all new internal elements, thereby limiting access to them. As an aid to migration, however, we deliberately chose not to strongly encapsulate, at run time, the content of packages that existed in JDK 8. Library and application code on the class path could thus continue to use reflection to access the non-public elements of java.* packages, and all elements of sun.* and other internal packages, for packages that existed in JDK 8. This arrangement is called relaxed strong encapsulation.

We released JDK 9 in September 2017. Most of the commonly-used internal elements of the JDK now have standard replacements. Developers have had over three years in which to migrate away from internal elements of the JDK to standard APIs such as java.lang.invoke.MethodHandles.Lookup::defineClass, java.util.Base64, and java.lang.ref.Cleaner. Many library, framework, and tool maintainers have completed that migration and released updated versions of their components. We are now ready to take the next step toward the strong encapsulation of all internal elements of the JDK — except for critical internal APIs such as sun.misc.Unsafe — as originally planned in Project Jigsaw.


Relaxed strong encapsulation is controlled by the launcher option --illegal-access. This option, introduced by JEP 261, is provocatively named in order to discourage its use. It presently works as follows:

As the next step toward strongly encapsulating all internal elements of the JDK, we propose to change the default mode of the --illegal-access option from permit to deny. With this change, packages that existed in JDK 8 and do not contain critical internal APIs will no longer be open by default; a complete list is available here. The sun.misc package will still be exported by the jdk.unsupported module, and will still be accessible via reflection.

We will also revise the related text in the Java Platform Specification to disallow the opening of any package by default in any Java Platform Implementation, unless that package is explicitly declared to be open in the declaration of its containing module.

The permit, warn, and debug modes of the --illegal-access option will continue to work. These modes allow end users to choose relaxed strong encapsulation if they wish.

We expect a future JEP to remove the --illegal-access option entirely. At that point it will not be possible to open all of the JDK 8 packages via a single command-line option. It will still be possible to use the --add-opens command-line option, or the Add-Opens JAR-file attribute, to open specific packages.

To prepare for the eventual removal of the --illegal-access option we will deprecate it for removal as part of this JEP. As a consequence, specifying that option to the java launcher will cause a deprecation warning to be issued.

Risks and Assumptions

The primary risk of this proposal is that existing Java code will fail to run. The kinds of code that will fail include, but are not limited, to:

We encourage all developers to:

Secondary risks

Examples of the impact of this change