Migration Guide
If you are moving from Oracle JDK to OpenJDK from the AdoptOpenJDK project, you'll probably have a few key questions on your mind. Firstly, you'll want to know what the differences are between Oracle JDK and AdoptOpenJDK and whether there are any steps you need to take to migrate. If you've looked at the home page, you'll also know that we provide AdoptOpenJDK binaries with a choice between OpenJDK and Eclipse OpenJ9 (with OpenJDK class libraries). The answers to common questions around these choices are covered in the sections that follow.
To understand which platforms are supported, see the Platform Support Matrix.
The following table illustrates the proprietary components that can be found in Oracle JDK 8 and the alternative technologies that are either planned or available to replace them. Click on the links to learn more about each component and any steps that might be necessary to adopt them.
| Oracle JDK 8 proprietary component | Alternative component | OpenJDK 8 | OpenJDK 11 |
|---|---|---|---|
| Java Web Start | IcedTea-Web | yes | no |
| JavaFX | OpenJFX | no | no |
| T2K font rendering engine | Freetype | yes | yes |
| Monotype Lucida fonts | Relicensed Lucida fonts | no (coming soon) | no (coming soon) |
| Ductus 2D renderer | Pisces/Marlin | yes (Pisces) | yes (Marlin) |
| Kodac Color Matching System (KCMS) library | LCMS | yes | yes |
| SNMP | Use JMX (or SNMP4J) | yes (not bundled) | yes (not bundled) |
| Sound drivers | Use Windows sound drivers | yes (not bundled) | yes (not bundled) |
| Java Flight Recorder (JFR) | Java Flight Recorder | no (coming soon) | yes |
| Java Mission Control (JMC) | Use JDK Mission Control | no (coming soon) | no (coming soon) |
Note: JavaFX, JFR, and JMC were all contributed by Oracle to the OpenJDK project for releases after Java 8.
IcedTea-Web
Java Web Start was deprecated by Oracle in Java SE 8 and removed in Java SE 9. IcedTea-Web can provide equivalent functionality for AdoptOpenJDK 8 users.
IcedTea-Web is available to download from the Iced-Tea Web project page in Linux, Windows, and Portable package formats.
IcedTea-Web is also available as an optional component of the AdoptOpenJDK installer for 64-bit Windows on OpenJDK 8 that you can select from the Custom Setup panel. You can also choose to associate JNLP files so that when a user clicks on the JNLP file, it is automatically opened with IcedTea-Web.
By default, IcedTea-Web is installed into the OpenJDK directory and has the same executable name (javaws.exe) as Java Web Start. To configure settings, such as security or certificates, start the control panel by running itweb-settings.exe.
Use IcedTea-Web in the same way as Java Web Start. For more information, see Developing a Java Web Start application and Deploying a Java Web Start application. Whilst IcedTea-Web is written to operate in the same way as Java Web Start there are a few known differences, which are raised as issues in the GitHub project. Work is ongoing to minimize or eliminate these differences.
IcedTea-Web 1.8.x and 2.0.x are compatible with AdoptOpenJDK 8 builds. We know that software which is based on IcedTea-Web supports the execution of OpenJDK 11 based JNLP applications but IcedTea-Web does not contain any tests to check OpenJDK 11 support and we do not bundle it with AdoptOpenJDK 11 builds.
Note: Currently, IcedTea-Web is bundled only with the Windows MSI installer for AdoptOpenJDK 8. The installers are available only for x64 Windows systems. Further work is underway to provide IcedTea-Web as an optional component of AdoptOpenJDK 8 installers for other platforms.
OpenJFX
Back in 2017, JavaFX was decoupled from the Oracle JDK and contributed to the OpenJDK community. The OpenJFX community is focused on OpenJFX 11+ and provides binaries that you can use with AdoptOpenJDK.
OpenJFX 8 is no longer being actively maintained. If you need this capability, we recommend upgrading to OpenJFX 11.
For more information, read the OpenJFX FAQ.
Freetype font rendering library
OpenJDK uses the open source FreeType font rendering library instead of the proprietary T2K font library.
Relicensed Lucida fonts
The Lucida fonts that are available in Oracle JDK 8 have a proprietary 3rd party license. AdoptOpenJDK intend to provide relicensed Lucida fonts. Work is ongoing to minimize any display issues when these fonts are rendered by Freetype and is expected to complete in 2Q 2019.
Pisces and Marlin
Oracle JDK 8 uses a proprietary 2D graphics renderer called Ductus, whereas OpenJDK uses an open-source renderer called Pisces. From OpenJDK 9, the Marlin renderer is in use. Work is planned at AdoptOpenJDK to either backport Marlin to OpenJDK 8 and/or minimize any display issues between the two. The outlook for completion is Q2 2019.
LCMS
OpenJDK uses the Little Color Matching System (LCMS) open source open source library instead of the proprietary Kodac CMS library.
JMX
The proprietary SNMP package shipped with Oracle JDK 8 is not present in OpenJDK. Use JMX as an alternative, or SNMP4J. These packages are not bundled with the AdoptOpenJDK binaries.
Windows sound drivers
Oracle JDK provides native sound drivers for Java 8 on Windows, which are not present in OpenJDK. Use the sound drivers that are available with Microsoft Windows instead.
Java Flight Recorder
Java Flight Recorder (JFR) was decoupled from the Oracle JDK and contributed to the OpenJDK community. Work is underway to backport JFR from OpenJDK 11 to OpenJDK 8. When this work is complete, AdoptOpenJDK will include JFR in OpenJDK 8 binaries.
JDK Mission Control
Java Mission Control (JMC) is being open sourced under the OpenJDK JDK Mission Control project. When available, JMC will be able to receive JFR events from OpenJDK 11 and eventually OpenJDK 8, when that backport is complete.
Eclipse OpenJ9 is an alternative JVM that implements the Java Virtual Machine Specification. You can think of it as a drop in replacement for the HotSpot VM, which is part of the reference implementation. Most Java applications should run on a runtime that contains the Eclipse OpenJ9 VM without changing anything. However, because it is an independent implementation there are some slight differences. You can learn about these differences by reading the New to OpenJ9? topic in the OpenJ9 user documentation.
Here are a few of the resources available to help you with migrating to AdoptOpenJDK:
- Ask questions directly by joining the AdoptOpenJDK Community Slack group.
- Learn more about the AdoptOpenJDK project, including build and test infrastructure, by reading the Technical Steering Committee documentation.
- For HotSpot VM documentation, see the HotSpot Runtime Overview.
- For OpenJ9 VM documentation, see the OpenJ9 user documentation.