Java migration planning: step by step.

For most organisations, migrating off Oracle JDK to a free OpenJDK distribution is the single largest, lowest-risk Java cost saving available — it can remove a per-employee subscription bill entirely. But it has to be run as a disciplined project. The good news is that it is mostly an inventory, testing and rollout exercise, not a software rewrite, because OpenJDK builds are compatible replacements for Oracle JDK at the same version. This is the step-by-step plan. Across more than 340 Java licensing engagements, migrations executed in this sequence have completed with no functional change to applications and have contributed to more than $180M in total client savings.

Why migration is mostly a project, not a rewrite

The fear that stops many organisations migrating is the assumption that “moving off Oracle Java” means changing their applications. It generally does not. As covered in our OpenJDK vs Oracle JDK comparison, Oracle JDK and the major OpenJDK distributions are built from the same source and are functionally compatible at the same major version. An application that runs on Oracle JDK 17 will, in the large majority of cases, run unchanged on a TCK-certified OpenJDK 17 build.

That reframes the work. Migration is not a development project; it is an asset-management and operations project. The effort goes into knowing exactly what you have, swapping the runtime in a controlled way, testing thoroughly, and rolling out without surprises. The steps below follow that logic.

Step 1 — Build a complete Java inventory

Every migration begins with discovery. You cannot migrate what you cannot see, and an incomplete inventory is the most common cause of a migration that drags or leaves residual Oracle JDK behind.

Discover Java across the whole estate: physical servers, virtual machines, desktops and laptops, cloud instances, containers and images, build pipelines, and embedded Java inside other applications. For each installation, capture:

• Vendor and distribution — Oracle JDK, or already a non-Oracle OpenJDK build.
• Major version and update level — 8, 11, 17, 21, and the precise build.
• Deployment context — which application or service it serves, and whether production, test or development.
• How it was installed — a package, a manual install, baked into a container image, bundled inside another product.
• Owner — the team responsible for the application.

Use scanning tooling, but verify the results; estates always contain Java that automated discovery misses, particularly inside container images and bundled in third-party software. The inventory feeds not just the migration but any renewal decision and any audit defence, so it is worth doing well.

Step 2 — Classify and triage every workload

With the inventory complete, sort every installation into categories. This triage decides what actually needs to move and in what order.

Then sequence the migration targets by risk and complexity. A sensible order runs from low-risk to high-risk: development and test environments first, then non-critical internal applications, then business-critical and customer-facing systems last, once the process is proven. Group workloads by Java version too — migrating all the Java 8 workloads, then all the Java 11, is more efficient than a random order.

Step 3 — Choose your OpenJDK distribution

Select the OpenJDK distribution — or, occasionally, two — that the estate will standardise on. The leading free, production-grade options are Eclipse Temurin, Amazon Corretto, Azul Zulu, Microsoft Build of OpenJDK, BellSoft Liberica and the Red Hat build of OpenJDK. All are TCK-certified and all ship quarterly security updates.

Choose against a few criteria:

• Support roadmap. Confirm the distribution commits to updating the Java LTS versions you run for as long as you intend to stay on them.
• Platform alignment. A distribution that aligns with your dominant cloud or OS can simplify operations.
• Commercial support need. Decide which workloads, if any, warrant a paid support contract, and pick a distribution that offers it on per-server terms.
• Version coverage. Ensure the distribution provides builds for every Java version in your estate, including older LTS releases.

Standardising on one primary distribution simplifies patching and governance later. Allow a second only where a specific platform genuinely requires it.

Step 4 — Run a representative pilot

Before any broad rollout, migrate a small, representative set of applications as a pilot. The pilot has two jobs: to prove the process technically, and — if a renewal is approaching — to make the exit option credible in negotiation.

Pick pilot applications that represent the estate's variety: a couple of different Java versions, a server application and perhaps a desktop one, something with meaningful dependencies. Migrate them: install the chosen OpenJDK build, point the application at it, and run it through full testing in a non-production environment, then a controlled production cutover with a rollback path ready.

Document everything — the effort per application, any issues, how they were resolved. The pilot output is both a tested runbook for the wider rollout and the evidence that the migration is real.

Step 5 — Test systematically

Testing is where migration confidence is built. For each workload moving from Oracle JDK to OpenJDK:

• Functional testing. Run the application's regression suite on the OpenJDK build. The aim is to confirm identical behaviour.
• Performance testing. Compare performance against the Oracle JDK baseline. Differences are usually negligible, but garbage-collector configuration and JVM flags should be reviewed.
• Integration testing. Confirm the application still interoperates correctly with the systems around it.
• Startup and configuration checks. Verify JVM arguments, certificate stores, and any environment-specific settings carry over. Most do; a few warrant explicit checking.
• Build-pipeline testing. Update CI/CD to build and test against the new JDK, so new releases are produced on OpenJDK from then on.

Where issues surface, they are typically minor and configuration-related rather than fundamental incompatibilities. Resolve them in test, update the runbook, and move on.

Step 6 — Roll out in phases

With the process proven and tested, execute the rollout in the risk-ordered sequence set in Step 2. Phasing is what keeps the migration disruption-free.

• Move in controlled waves. Migrate a batch of workloads, confirm stability, then proceed. Do not attempt the whole estate at once.
• Keep a rollback path. For each cutover, retain the ability to revert to Oracle JDK quickly until the workload is confirmed stable. (Note that running Oracle JDK still has licensing implications, so rollback is a short-term safety net, not a resting state.)
• Update infrastructure-as-code and images. Change base container images, VM templates, and configuration management so new deployments use OpenJDK by default. This stops the estate quietly re-acquiring Oracle JDK.
• Communicate with application owners. Each owning team should know when their workload moves and what to watch for.
• Track progress against the inventory. Tick off each migrated installation so you know precisely what remains.

Step 7 — Decommission Oracle JDK

Migration is not finished when applications run on OpenJDK — it is finished when Oracle JDK is gone. This step matters for licensing: leftover Oracle JDK installations are exactly what an Oracle audit looks for.

• Remove Oracle JDK binaries. Uninstall Oracle JDK from every server, desktop, and image once its workloads are confirmed on OpenJDK.
• Clean up download channels. Remove Oracle JDK from internal package repositories and software catalogues so it cannot be reinstalled by habit.
• Verify with a fresh scan. Re-run discovery to confirm no Oracle JDK remains. The target is a clean estate.
• Handle the subscription. If you held a Java SE subscription, ensure the migration completed before it lapsed, and serve any required non-renewal notice within the contractual window — see the 12-month renewal plan for timing.
• Document the end state. Keep a record showing the estate is now Oracle-JDK-free. It is valuable evidence if Oracle ever raises Java.

Step 8 — Govern to stay off the subscription

A migrated estate can quietly drift back. Someone downloads Oracle JDK to solve a problem; a new container image ships with it; an acquisition arrives with Oracle JDK installed. Without governance, the exposure regrows.

• Pipeline controls. Configure build and deployment pipelines to use approved OpenJDK builds and to flag or reject Oracle JDK.
• A standard, approved JDK catalogue. Make the chosen OpenJDK distribution the easy, default choice; make obtaining Oracle JDK require explicit approval.
• Procurement checks. Screen new third-party software and acquisitions for bundled Oracle Java before it enters the estate.
• Periodic re-scanning. A quarterly Java inventory refresh catches drift early, while it is small.
• Clear ownership. Assign responsibility for ongoing Java compliance so it does not fall between teams.

A continuous Java management programme institutionalises this, so the estate stays Oracle-JDK-free year on year and a future audit finds nothing to claim.

Frequently asked questions

This article is general information about Java migration, not legal advice. Migration specifics and licensing terms vary; consult a qualified independent Java licensing specialist on your estate.