This Guide provides resources to assist developers of Rhino Deployable Units (DUs) to migrate those DUs to run on Rhino 3 (or later) on JDK11.

Rhino 3 and later run only on JDK 11.0.4 and later. There are considerable changes between JDK8 and JDK11 which may mean that deployable units which build and run on older JDK/Rhino platforms no longer build on JDK11 or run on Rhino 3.

Background resources

There are many resources on the web for changes between JDK8 and JDK11. https://blog.codefx.org/java/java-11-migration-guide/#Migrating-From-Java-8-To-Java-11 has been found to be particularly useful.

Quantifying issues before you start

Before you undertake a migration it is good to have some idea of how much effort will be involved.

The jdeps tool, new in JDK8 and enhanced subsequently, has an option --jdk-internals to scan jar files for references to JDK internals.

Using this tool on the .jar file(s) for your DU(s) can be valuable in determining what, if any, code will need to be rewritten to no longer access JDK internals.

Using this tool on the .jar file(s) for any third party libraries you deploy can be valuable in determining whether they will need upgrading.

For example:

$jdeps --jdk-internals netty-common-4.0.12.jar
netty-common-4.0.12.jar -> JDK removed internal API
netty-common-4.0.12.jar -> jdk.unsupported
   io.netty.util.internal.PlatformDependent0          -> sun.misc.Cleaner                                   JDK internal API (JDK removed internal API)
   io.netty.util.internal.PlatformDependent0          -> sun.misc.Unsafe                                    JDK internal API (jdk.unsupported)
   io.netty.util.internal.chmv8.ConcurrentHashMapV8   -> sun.misc.Unsafe                                    JDK internal API (jdk.unsupported)
   io.netty.util.internal.chmv8.ConcurrentHashMapV8$1 -> sun.misc.Unsafe                                    JDK internal API (jdk.unsupported)
   io.netty.util.internal.chmv8.ConcurrentHashMapV8$TreeBin -> sun.misc.Unsafe                                    JDK internal API (jdk.unsupported)
   io.netty.util.internal.chmv8.CountedCompleter      -> sun.misc.Unsafe                                    JDK internal API (jdk.unsupported)
   io.netty.util.internal.chmv8.CountedCompleter$1    -> sun.misc.Unsafe                                    JDK internal API (jdk.unsupported)
   io.netty.util.internal.chmv8.ForkJoinPool          -> sun.misc.Unsafe                                    JDK internal API (jdk.unsupported)
   io.netty.util.internal.chmv8.ForkJoinPool$2        -> sun.misc.Unsafe                                    JDK internal API (jdk.unsupported)
   io.netty.util.internal.chmv8.ForkJoinPool$WorkQueue -> sun.misc.Unsafe                                    JDK internal API (jdk.unsupported)
   io.netty.util.internal.chmv8.ForkJoinTask          -> sun.misc.Unsafe                                    JDK internal API (jdk.unsupported)
   io.netty.util.internal.chmv8.ForkJoinTask$1        -> sun.misc.Unsafe                                    JDK internal API (jdk.unsupported)
   io.netty.util.internal.chmv8.Striped64             -> sun.misc.Unsafe                                    JDK internal API (jdk.unsupported)
   io.netty.util.internal.chmv8.Striped64$1           -> sun.misc.Unsafe                                    JDK internal API (jdk.unsupported)
   io.netty.util.internal.chmv8.Striped64$Cell        -> sun.misc.Unsafe                                    JDK internal API (jdk.unsupported)
Warning: JDK internal APIs are unsupported and private to JDK implementation that are
subject to be removed or changed incompatibly and could break your application.
Please modify your code to eliminate dependence on any JDK internal APIs.
For the most recent update on JDK internal API replacements, please check:
https://wiki.openjdk.java.net/display/JDK8/Java+Dependency+Analysis+Tool
JDK Internal API                         Suggested Replacement
----------------                         ---------------------
sun.misc.Cleaner                         Use java.lang.ref.PhantomReference @since 1.2 or java.lang.ref.Cleaner @since 9
sun.misc.Unsafe                          See http://openjdk.java.net/jeps/260
Tip

Run this tool on the jars bundled inside your DU, not on the DU jar itself.

Java development environment

You will need a Java 11 JDK, version 11.0.4 or later. For security reasons it is strongly recommended that you use the latest JDK version from a supported vendor or the same JDK version used for the target production deployment. Your options for obtaining a JDK are:

  • The Java SE Development Kit from Oracle. (You cannot use this in production environments without a license from Oracle.)

  • The OpenJDK package in the CentOS, Red Hat, or Fedora package repositories: yum install java-11-openjdk-devel

  • AdoptOpenJDK on other Linux distributions. Select the HotSpot JVM, not Eclipse OpenJ9.

Note These JDK recommendations for development may differ from those supported by production Rhino installations. For guidance on production deployments, please see the Rhino Compatibility Guide.

If using Ant, version 1.10.5 or later is required.

Migration process

Starting with your leaf dependencies, work though the stages for each DU using JDK11:

build → deploy → run

Problems you will encounter

  • Use of (no longer visible) JDK internals.

    Solved by rewriting the code to not do that. Specific solutions depend on which part of the JDK internals was being used. The jdeps tool mentioned below will point out the new official way to achieve the same thing in many cases.

  • Use of (no longer visible) JDK internals by third party libraries.

    Solved by upgrading the third party libraries to later versions which do not have the problem.

  • API changes in upgraded third party libraries.

    Solved by rewriting code to build against the upgraded library’s API.

  • Removal of JAXB module from JDK

  • Removal of JavaBeans Activation Framework from the JDK

    Both of these problems were solved by building and deploying Library DUs to provide the removed libraries, and referencing those libraries in the SLEE deployment descriptors for the DUs that used them.

Note

For more information on solutions for problems encountered, see common problems
Next page