Better tools for adjusting to strong encapsulation

Tue Mar 21 18:04:07 UTC 2017

Lest folks think they can now sit back and relax until JDK 10,
I'd like to point out that there are some cases where what has
happened in 9 is that a very small number of old deprecated
and non-standard APIs have actually been removed, and some
small number of APIs adjusted in behaviour.
Whilst these changes are generally tangential to the module system,
its advent made it necessary to determine what was supported and standard.

No "kill switch" will bring those back, so affected apps will
still need to migrate for JDK 9.

The JDK 9 migration guide should cover the specifics of these APIs.

-phil.

On 03/21/2017 07:48 AM, mark.reinhold at oracle.com wrote:
> By now we've heard quite a bit of feedback, both publicly and privately,
> from developers who've migrated existing applications to JDK 9.  This can
> be a non-trivial task, involving the iterative construction of a set of
> command-line workarounds, since some popular libraries and frameworks use
> the core reflection API to access internal APIs of the JDK.  On JDK 9
> such components no longer work out-of-the-box because most internal APIs
> are now strongly encapsulated in order to improve the integrity of the
> platform.
>
> In order to make it easier to adjust to the strong encapsulation of
> internal APIs in JDK 9, in both the short term and over the long term,
> we've introduced a temporary "big kill switch", described below.  This
> switch will only be supported in JDK 9.  It's already available in the
> current Jigsaw EA builds [1], and will shortly be merged into JDK 9.
>
> Background
> ----------
>
> Diagnosing the failures of libraries and frameworks that access internal
> APIs of the JDK and then working around those failures is possible, but
> tedious.  The initial symptom is usually an `IllegalAccessException` or
> an `InaccessibleObjectException`.  The workaround is to use an
> `--add-opens` command-line option whose arguments are based upon the
> information shown in the exception message.  A large application that
> uses several reflective components may suffer many such failures, so this
> process may have to be repeated many times, resulting in a long list of
> command-line options that will typically be recorded in a launch script
> or an @-file.
>
> These options are tedious to construct but, additionally, there's a
> significant risk that once they're baked into a file they'll never be
> removed, even long after the problems that they work around have been
> resolved.  An application that needs some workarounds today might not
> benefit as well as it could from strong encapsulation in the long term,
> after all of the reflective components that it uses have been fixed to
> replace their use of JDK-internal APIs with proper exported APIs.
>
> To help the entire ecosystem migrate to the modular Java platform we want
> to motivate such fixes as strongly as we possibly can, especially in the
> near term.  We can do that by making it easier for you to get an existing
> application to work while also ensuring that the run-time system reports
> illegal reflective-access operations in a way that allows you to identify
> which libraries and frameworks on your class path require illegal access
> in order to work.  If a component's maintainers have already released a
> new, fixed version that no longer requires illegal access then you can
> consider upgrading to that version.  If, however, a component still needs
> to be fixed then we encourage you to contact its maintainers and ask them
> to stop using JDK-internal APIs [2].
>
> With all this in mind we've introduced a "big kill switch", described
> below, together with some new warning messages.  This switch will be
> supported in JDK 9, in order to enable application migration and motivate
> fixes to libraries and frameworks.  It will not be supported in JDK 10 or
> later releases, in order to motivate fixes to libraries and frameworks
> sooner rather than later.  If this switch were to be supported long-term
> then that would tend to reduce the pressure on maintainers to fix their
> components.
>
> New command-line option: `--permit-illegal-access`
> --------------------------------------------------
>
> If this option is present at run time then it will permit illegal access
> operations by code in any unnamed module (i.e., code on the class path)
> to members of types in any named module via the standard reflective APIs
> (`java.lang.reflect` and `java.lang.invoke`), including in particular
> those that would otherwise result in an `IllegalAccessException` or an
> `InaccessibleObjectException`.
>
>              +----------------------------------------------+
>              | This option will only be supported in JDK 9. |
>              |         It will be removed in JDK 10.        |
>              +----------------------------------------------+
>
> This option does not permit illegal access operations by code in named
> modules to members of types in other named modules; for that you must
> use the `--add-opens` or `--add-exports` options.  Those options can be
> combined with `--permit-illegal-access`.
>
> Warnings of illegal reflective-access operations
> ------------------------------------------------
>
> When an illegal reflective access operation succeeds due to the use of
> the `--permit-illegal-access` option, or the use of an `--add-opens` or
> `--add-exports` option, then a warning message of the following form is
> written to the error stream:
>
>      WARNING: Illegal access by $PERPETRATOR to $VICTIM (permitted by $OPTION)
>
> where:
>
>    - $PERPETRATOR is the fully-qualified name of the type containing
>      the code that invoked the reflective operation in question plus
>      the code source (i.e., JAR-file path), if available,
>
>    - $VICTIM is a string that describes the member being accessed,
>      including the fully-qualified name of the enclosing type, and
>
>    - $OPTION is the name of the command-line option that enabled this
>      access, when that can be determined, or the first one of those
>      options if more than one option had that effect.
>
> The run-time system attempts to suppress duplicate warnings for the same
> $PERPETRATOR and $VICTIM, but it's not always practical to do so.
>
> For deeper diagnosis you can request a stack trace on each such warning
> by setting the system property `sun.reflect.debugModuleAccessChecks` to
> the value `access`, though this detail might change.  (That property can
> also be helpful to diagnose mysterious failures due to illegal-access
> exceptions that are caught and suppressed.)
>
> In addition to displaying a warning on each illegal access operation, the
> run-time system also shows new initial warning messages at startup time.
> If `--permit-illegal-access` is used then a warning reports the imminent
> demise of that option in the next major release.  If either `--add-opens`
> or `--add-exports` are used then a warning reports a count of each type
> of option used (i.e., opens vs. exports).
>
> Here are some examples of these messages, from running Jython on a very
> recent Jigsaw build:
>
>    $ java --permit-illegal-access -jar jython-standalone-2.7.0.jar
>    WARNING: --permit-illegal-access will be removed in the next major release
>    WARNING: Illegal access by jnr.posix.JavaLibCHelper (file:/tmp/jython-standalone-2.7.0.jar) to method sun.nio.ch.SelChImpl.getFD() (permitted by --permit-illegal-access)
>    WARNING: Illegal access by jnr.posix.JavaLibCHelper (file:/tmp/jython-standalone-2.7.0.jar) to field sun.nio.ch.FileChannelImpl.fd (permitted by --permit-illegal-access)
>    WARNING: Illegal access by jnr.posix.JavaLibCHelper (file:/tmp/jython-standalone-2.7.0.jar) to field java.io.FileDescriptor.fd (permitted by --permit-illegal-access)
>    WARNING: Illegal access by org.python.core.PySystemState (file:/tmp/jython-standalone-2.7.0.jar) to method java.io.Console.encoding() (permitted by --permit-illegal-access)
>    Jython 2.7.0 (default:9987c746f838, Apr 29 2015, 02:25:11)
>    [OpenJDK 64-Bit Server VM (Oracle Corporation)] on java9-internal
>    Type "help", "copyright", "credits" or "license" for more information.
>    >>> ^D
>    $
>
>
> [1] http://openjdk.java.net/projects/jigsaw/ea
> [2] This will usually but not always be possible, since there are still a
>      few critical internal APIs without exported replacements, per JEP 260
>      (http://openjdk.java.net/jeps/260).