CINXE.COM

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=us-ascii" /><meta http-equiv="Content-Type" content="text/html; charset=us-ascii" /><title>JEP 260: Encapsulate Most Internal APIs</title><link rel="shortcut icon" href="/images/nanoduke.ico" /><link rel="stylesheet" type="text/css" href="/page.css" /><script type="text/javascript" src="/page.js"><noscript></noscript></script><script src="https://cdn.usefathom.com/script.js" data-site="KCYJJPZX" defer="yes"></script><style type="text/css" xml:space="preserve"> TABLE { border-collapse: collapse; padding: 0px; margin: 1em 0 1em 2em; } TR:first-child TH, TR:first-child TD { padding-top: 0; } TH, TD { padding: 0px; padding-top: .5ex; vertical-align: baseline; text-align: left; } TD + TD, TH + TH { padding-left: 1em; } TD:first-child, TH:first-child, TD.jep { text-align: right; } TABLE.head TD:first-child { font-style: italic; padding-left: 2em; white-space: nowrap; } PRE { padding-left: 2em; margin: 1ex 0; font-size: inherit; } TABLE PRE { padding-left: 0; margin: 0; } TABLE.jeps TD:first-child + TD, TABLE.jeps TD:first-child + TD + TD { padding-left: .5em; } TABLE.jeps TD:first-child, TABLE.jeps TD:first-child + TD, TABLE.jeps TD:first-child + TD + TD { font-size: smaller; } TABLE.jeps TD.cl { font-size: smaller; padding-right: 0; text-align: right; } TABLE.jeps TD.cm { font-size: smaller; padding-left: .1em; padding-right: .1em; } TABLE.jeps TD.cr { font-size: smaller; padding-left: 0; } TABLE.jeps TD.z { padding-left: 0; padding-right: 0; } TABLE.head TD { padding-top: 0; } </style></head><body><div id="main"><h1>JEP 260: Encapsulate Most Internal APIs</h1><table class="head"><tr><td>Author</td><td>Mark Reinhold</td></tr><tr><td>Owner</td><td>Chris Hegarty</td></tr><tr><td>Type</td><td>Feature</td></tr><tr><td>Scope</td><td>JDK</td></tr><tr><td>Status</td><td>Closed / Delivered</td></tr><tr><td>Release</td><td>9</td></tr><tr><td>Discussion</td><td>jigsaw dash dev at openjdk dot java dot net</td></tr><tr><td>Effort</td><td>M</td></tr><tr><td>Duration</td><td>L</td></tr><tr><td>Blocks</td><td><a href="261">JEP 261: Module System</a></td></tr><tr><td>Relates to</td><td><a href="396">JEP 396: Strongly Encapsulate JDK Internals by Default</a></td></tr><tr><td></td><td><a href="403">JEP 403: Strongly Encapsulate JDK Internals</a></td></tr><tr><td>Reviewed by</td><td>Alan Bateman, Alex Buckley, Brian Goetz, John Rose, Paul Sandoz</td></tr><tr><td>Endorsed by</td><td>Brian Goetz</td></tr><tr><td>Created</td><td>2015/08/03 18:29</td></tr><tr><td>Updated</td><td>2024/04/28 18:11</td></tr><tr><td>Issue</td><td><a href="https://bugs.openjdk.org/browse/JDK-8132928">8132928</a></td></tr></table><div class="markdown"><h2 id="Summary">Summary</h2> <p>Encapsulate most of the JDK's internal APIs by default so that they are inaccessible at compile time, and prepare for a future release in which they will be inaccessible at run time. Ensure that critical, widely-used internal APIs are not encapsulated, so that they remain accessible until supported replacements exist for all or most of their functionality.</p> <h2 id="Non-Goals">Non-Goals</h2> <p>This JEP does not define replacements for any internal APIs; that work is or will be covered by separate JEPs and, where appropriate, JSRs.</p> <p>This JEP does not commit to preserve the compatibility of any internal APIs across releases; they continue to remain unstable and subject to change without notice.</p> <h2 id="Motivation">Motivation</h2> <p>Some popular libraries make use of non-standard, unstable, and unsupported APIs that are internal implementation details of the JDK and <a href="http://web.archive.org/web/19980215011039/http://java.sun.com/products/jdk/faq/faq-sun-packages.html">were never intended for external use</a>. In the modular JDK (<a href="http://openjdk.java.net/jeps/200">JEP 200</a>), limiting access to these APIs by leveraging the module system (<a href="http://openjdk.java.net/jeps/261">JEP 261</a>) improves the integrity and security of the platform since many of these internal APIs define privileged, security-sensitive operations. In the long run this change will reduce the costs borne by the maintainers of the JDK itself and by the maintainers of libraries and applications that, knowingly or not, make use of these internal APIs.</p> <h2 id="Description">Description</h2> <p>Based upon analyses of various large collections of code, including Maven Central, and also feedback received since the release of JDK 8 and its <a href="https://wiki.openjdk.java.net/display/JDK8/Java+Dependency+Analysis+Tool">dependency analysis tool</a> (<code>jdeps</code>), we divide the JDK's internal APIs into two broad categories:</p> <ul> <li> <p><em>Non-critical internal APIs</em> which do not appear to be used by code outside of the JDK or are used by outside code merely for convenience, <em>i.e.</em>, for functionality that is available in supported APIs or can easily be provided by libraries (<em>e.g.</em>, <code>sun.misc.BASE64Decoder</code>); and</p> </li> <li> <p><em>Critical internal APIs</em> which provide critical functionality that would be difficult, if not impossible, to implement outside of the JDK itself (<em>e.g.</em>, <code>sun.misc.Unsafe</code>).</p> </li> </ul> <p>Critical internal APIs are encapsulated in JDK 9, or not, according to whether supported replacements exist in JDK 8. A supported replacement is one that was either part of the Java SE 8 standard, <em>i.e.</em>, in a <code>java.*</code> or <code>javax.*</code> package, or else JDK-specific and annotated with <code>@jdk.Exported</code>, typically in a <code>com.sun.*</code> or <code>jdk.*</code> package. In detail:</p> <ul> <li> <p>Critical internal APIs for which supported replacements exist in JDK 8 are encapsulated in JDK 9.</p> </li> <li> <p>Critical internal APIs for which supported replacements did not exist in JDK 8 are not encapsulated in JDK 9. A detailed list is provided below.</p> </li> <li> <p>Critical internal APIs for which supported replacements exist in JDK 9 are deprecated and will be either encapsulated or removed in a future release.</p> </li> </ul> <p>All non-critical internal APIs are encapsulated in JDK 9.</p> <p>Internal APIs that are encapsulated in JDK 9 are inaccessible at compile time. They can be made accessible at compile time via the <code>--add-exports</code> <a href="http://openjdk.java.net/jeps/261#Breaking-encapsulation">command-line option</a>. At run time they remain accessible if they were in JDK 8 but in a future release they will become inaccessible, at which point the <code>--add-exports</code> or <code>--add-opens</code> options can be used to make them accessible at run time as well. The <code>--illegal-access</code> option <a href="http://openjdk.java.net/jeps/261#Relaxed-strong-encapsulation">controls the run-time accessibility of these APIs</a> and can be used to emulate the future run-time inaccessibility of internal APIs.</p> <h3 id="Critical-internal-APIs-not-encapsulated-in-JDK-9">Critical internal APIs not encapsulated in JDK 9</h3> <p>The critical internal APIs that are not encapsulated in JDK 9, because supported replacements did not exist in JDK 8, are listed here.</p> <ul> <li> <p><code>sun.misc.{Signal,SignalHandler}</code></p> </li> <li> <p><code>sun.misc.Unsafe</code> (The functionality of many of the methods in this class is available via <em>variable handles</em> (<a href="http://openjdk.java.net/jeps/193">JEP 193</a>).)</p> </li> <li> <p><code>sun.reflect.Reflection::getCallerClass(int)</code> (The functionality of this method is available in the stack-walking API defined by <a href="http://openjdk.java.net/jeps/259">JEP 259</a>.)</p> </li> <li> <p><code>sun.reflect.ReflectionFactory</code></p> </li> <li> <p><code>com.sun.nio.file.{ExtendedCopyOption,ExtendedOpenOption, ExtendedWatchEventModifier,SensitivityWatchEventModifier}</code></p> </li> </ul> <p>These APIs are defined in, and exported by, the JDK-specific <code>jdk.unsupported</code> module. This module is present in full JRE and JDK images. These APIs are thus accessible by default to code on the class path, and accessible to code in modules if those modules declare dependences upon the <code>jdk.unsupported</code> module.</p> <blockquote> <p><strong>Critical internal APIs for which replacements are introduced in JDK 9 are deprecated in JDK 9 and will be either encapsulated or removed in a future release.</strong></p> </blockquote> <p>A consequence of <code>jdk.unsupported</code> exporting and opening the <code>sun.misc</code> and <code>sun.reflect</code> packages is that all non-critical internal APIs in those packages were either moved to some other package or removed, as appropriate. Standard and JDK modules that are not upgradeable should not depend upon the <code>jdk.unsupported</code> module, but instead use proper internal APIs.</p> <p>Maintainers of libraries that use critical internal APIs for which replacements exist in JDK 9 may wish to use <a href="http://openjdk.java.net/jeps/238">Multi-Release JAR Files (JEP 238)</a> in order to ship single artifacts that use the old APIs on releases prior to JDK 9 and the replacement APIs on later releases.</p> <h2 id="Risks-and-Assumptions">Risks and Assumptions</h2> <p>If some widely-used critical internal API was not identified as critical, and that API was moved or removed, then applications that depend upon it will fail.</p> <p>If some widely-used critical internal API was not identified as critical but still exists then applications that depend upon it may cause a warning to be issued in this release and will fail in a future release.</p> <p>The short-term workaround for both such situations is for the end user to expose the API via the above-mentioned command-line option; in the longer term, in a later release the API could be moved to the <code>jdk.unsupported</code> module and exported for external use.</p> <p>The non-critical internal APIs previously present in the <code>sun.misc</code> and <code>sun.reflect</code> packages have been either moved or removed. Existing code that depends upon them may not work correctly.</p> <h2 id="Dependences">Dependences</h2> <p><a href="http://openjdk.java.net/jeps/200">JEP 200 (The Modular JDK)</a> defines the modular structure of the JDK, and <a href="http://openjdk.java.net/jeps/261">JEP 261 (Module System)</a> implements the module system.</p> </div></div><div id="sidebar"><div id="openjdk-sidebar-logo"><a href="/"><img alt="OpenJDK logo" width="91" height="25" src="/images/openjdk2.svg" /></a></div><div class="links"><div class="link"><a href="/install/">Installing</a></div><div class="link"><a href="/guide/#contributing-to-an-openjdk-project">Contributing</a></div><div class="link"><a href="/guide/#reviewing-and-sponsoring-a-change">Sponsoring</a></div><div class="link"><a href="/guide/">Developers' Guide</a></div><div class="link"><a href="/groups/vulnerability/report">Vulnerabilities</a></div><div class="link"><a href="https://jdk.java.net">JDK GA/EA Builds</a></div></div><div class="links"><div class="links"><a href="https://mail.openjdk.org">Mailing lists</a></div><div class="link"><a href="https://wiki.openjdk.org">Wiki</a> · <a href="/irc">IRC</a></div><div class="link"><a href="https://mastodon.social/@openjdk" rel="me">Mastodon</a></div><div class="link"><a href="https://bsky.app/profile/openjdk.org">Bluesky</a></div></div><div class="links"><div class="links"><a href="/bylaws">Bylaws</a> · <a href="/census">Census</a></div><div class="link"><a href="/legal/">Legal</a></div></div><div class="links"><div class="links"><a href="/workshop"><b>Workshop</b></a></div></div><div class="links"><div class="links"><a href="/jeps/0"><b>JEP Process</b></a></div></div><div class="links"><div class="about">Source code</div><div class="link"><a href="https://github.com/openjdk/">GitHub</a></div><div class="link"><a href="https://hg.openjdk.org">Mercurial</a></div></div><div class="links"><div class="about">Tools</div><div class="link"><a href="http://git-scm.org/">Git</a></div><div class="link"><a href="/jtreg/">jtreg harness</a></div></div><div class="links"><div class="about">Groups</div><div class="link"><a href="/groups/">(overview)</a></div><div class="link"><a href="/groups/adoption">Adoption</a></div><div class="link"><a href="/groups/build">Build</a></div><div class="link"><a href="/groups/client-libs">Client Libraries</a></div><div class="link"><a href="/groups/csr">Compatibility & Specification Review</a></div><div class="link"><a href="/groups/compiler">Compiler</a></div><div class="link"><a href="/groups/conformance">Conformance</a></div><div class="link"><a href="/groups/core-libs">Core Libraries</a></div><div class="link"><a href="/groups/gb">Governing Board</a></div><div class="link"><a href="/groups/hotspot">HotSpot</a></div><div class="link"><a href="/groups/ide-support">IDE Tooling & Support</a></div><div class="link"><a href="/groups/i18n">Internationalization</a></div><div class="link"><a href="/groups/jmx">JMX</a></div><div class="link"><a href="/groups/members">Members</a></div><div class="link"><a href="/groups/net">Networking</a></div><div class="link"><a href="/groups/porters">Porters</a></div><div class="link"><a href="/groups/quality">Quality</a></div><div class="link"><a href="/groups/security">Security</a></div><div class="link"><a href="/groups/serviceability">Serviceability</a></div><div class="link"><a href="/groups/vulnerability">Vulnerability</a></div><div class="link"><a href="/groups/web">Web</a></div></div><div class="links"><div class="about">Projects</div><div class="link">(<a href="/projects/">overview</a>, <a href="/projects/archive">archive</a>)</div><div class="link"><a href="/projects/amber">Amber</a></div><div class="link"><a href="/projects/babylon">Babylon</a></div><div class="link"><a href="/projects/crac">CRaC</a></div><div class="link"><a href="/projects/code-tools">Code Tools</a></div><div class="link"><a href="/projects/coin">Coin</a></div><div class="link"><a href="/projects/cvmi">Common VM Interface</a></div><div class="link"><a href="/projects/guide">Developers' Guide</a></div><div class="link"><a href="/projects/dio">Device I/O</a></div><div class="link"><a href="/projects/duke">Duke</a></div><div class="link"><a href="/projects/galahad">Galahad</a></div><div class="link"><a href="/projects/graal">Graal</a></div><div class="link"><a href="/projects/icedtea">IcedTea</a></div><div class="link"><a href="/projects/jdk7">JDK 7</a></div><div class="link"><a href="/projects/jdk8">JDK 8</a></div><div class="link"><a href="/projects/jdk8u">JDK 8 Updates</a></div><div class="link"><a href="/projects/jdk9">JDK 9</a></div><div class="link"><a href="/projects/jdk">JDK</a> (…, <a href="/projects/jdk/23">23</a>, <a href="/projects/jdk/24">24</a>, <a href="/projects/jdk/25">25</a>)</div><div class="link"><a href="/projects/jdk-updates">JDK Updates</a></div><div class="link"><a href="/projects/jmc">JMC</a></div><div class="link"><a href="/projects/jigsaw">Jigsaw</a></div><div class="link"><a href="/projects/kona">Kona</a></div><div class="link"><a href="/projects/kulla">Kulla</a></div><div class="link"><a href="/projects/lanai">Lanai</a></div><div class="link"><a href="/projects/leyden">Leyden</a></div><div class="link"><a href="/projects/lilliput">Lilliput</a></div><div class="link"><a href="/projects/locale-enhancement">Locale Enhancement</a></div><div class="link"><a href="/projects/loom">Loom</a></div><div class="link"><a href="/projects/jmm">Memory Model Update</a></div><div class="link"><a href="/projects/metropolis">Metropolis</a></div><div class="link"><a href="/projects/mlvm">Multi-Language VM</a></div><div class="link"><a href="/projects/nashorn">Nashorn</a></div><div class="link"><a href="/projects/nio">New I/O</a></div><div class="link"><a href="/projects/openjfx">OpenJFX</a></div><div class="link"><a href="/projects/panama">Panama</a></div><div class="link"><a href="/projects/penrose">Penrose</a></div><div class="link"><a href="/projects/aarch32-port">Port: AArch32</a></div><div class="link"><a href="/projects/aarch64-port">Port: AArch64</a></div><div class="link"><a href="/projects/bsd-port">Port: BSD</a></div><div class="link"><a href="/projects/haiku-port">Port: Haiku</a></div><div class="link"><a href="/projects/macosx-port">Port: Mac OS X</a></div><div class="link"><a href="/projects/mips-port">Port: MIPS</a></div><div class="link"><a href="/projects/mobile">Port: Mobile</a></div><div class="link"><a href="/projects/ppc-aix-port">Port: PowerPC/AIX</a></div><div class="link"><a href="/projects/riscv-port">Port: RISC-V</a></div><div class="link"><a href="/projects/s390x-port">Port: s390x</a></div><div class="link"><a href="/projects/sctp">SCTP</a></div><div class="link"><a href="/projects/shenandoah">Shenandoah</a></div><div class="link"><a href="/projects/skara">Skara</a></div><div class="link"><a href="/projects/sumatra">Sumatra</a></div><div class="link"><a href="/projects/tsan">Tsan</a></div><div class="link"><a href="/projects/valhalla">Valhalla</a></div><div class="link"><a href="/projects/verona">Verona</a></div><div class="link"><a href="/projects/visualvm">VisualVM</a></div><div class="link"><a href="/projects/wakefield">Wakefield</a></div><div class="link"><a href="/projects/zero">Zero</a></div><div class="link"><a href="/projects/zgc">ZGC</a></div></div><div class="buttons"><a href="https://oracle.com"><img alt="Oracle logo" width="100" height="13" src="/images/oracle.svg" /></a></div></div><div id="footer"> © 2025 Oracle Corporation and/or its affiliates <br /><a href="/legal/tou/">Terms of Use</a> · License: <a href="/legal/gplv2+ce.html">GPLv2</a> · <a href="https://www.oracle.com/us/legal/privacy/">Privacy</a> · <a href="https://openjdk.org/legal/openjdk-trademark-notice.html">Trademarks</a></div><script type="text/javascript" src="/8TumUkcu3/xKyv/i/nAxGdn1c2QK3s/baLEfJbpY3Vz/YyZNWVcPAQ/JRYDMHAa/DVgB"></script></body></html>