Migration guide

Behavioural parity

If your application relies on legacy TLS protocols (TLS 1.0/1.1) or weak ciphers, it will fail to negotiate, but that is upstream OpenJDK 25 behaviour, not an Eliya overlay. Those protocols are disabled by default in any modern JDK distribution. If legacy interoperability is truly required, override at the JVM level: -Djava.security.properties==<path-with-relaxed-policy> (double equals overrides rather than appends).

Side-by-side with SDKMAN!

SDKMAN! manages JDK versions on developer machines: once registration is live, it lets you install Eliya alongside your current JDK and switch per shell. For servers and CI, use the .deb / .rpm packages or the tarball with update-alternatives (below). Safest path: your existing runtime stays default until you explicitly change it.

First-time SDKman setup (skip if already installed):

Install and switch to Eliya:

sdk use is per-shell. sdk default is permanent.

System-wide on Linux (update-alternatives)

For machine-wide default replacement after installing the tar.gz archive to /opt/eliya:

The priority value 2500 ensures Eliya is preferred over distro-packaged OpenJDK installations (typically 1500–2000) while still allowing manual override via update-alternatives --config java. Adjust to taste for your environment.

When .deb and .rpm packages ship in Q4 2026, they register these alternatives automatically.

Enable Eliya operational-readiness defaults (optional)

After switching runtimes your application will run unchanged. To opt into Eliya's Phase 1 operational-readiness ergonomics (heap-dump-on-OOM with structured path, exit-on-OOM, Native Memory Tracking summary, predictable crash log path, container support reinforced, diagnostic VM options unlocked), add the single flag:

Details on what this flag activates: flags reference.

For teams currently running APM tools (AppDynamics, Dynatrace, New Relic, Elastic APM, Datadog), migrating to Eliya is additive: you don't lose APM dashboards, you gain forensic data capture that APM cannot provide. For teams in compliance-restricted environments where SaaS APM was prohibited, Eliya provides observability capability previously inaccessible. The architectural distinction is documented in JVM forensics vs APM.

Vendor-specific notes

From Corretto

Behavioural parity is high; Corretto is also built from upstream OpenJDK 25. The most notable Corretto-specific feature is the Corretto Crypto Provider (ACCP): AWS-optimised cryptographic implementations. Eliya does not bundle ACCP, but applications that benefit from ACCP can add it as an explicit Maven/Gradle dependency on any JDK, including Eliya. For FIPS-validated cryptography, Eliya's FIPS variant ships in Phase 2 with a FIPS-validated provider preinstalled; sign up on the security page.

From Temurin / Adoptium

Direct swap. Both are vanilla OpenJDK builds. Eliya adds opt-in operational-readiness defaults via -XX:EliyaProfile=Production; Temurin's philosophy is to ship vanilla OpenJDK without overlays. Both are valid choices; Eliya is for teams who want operational-readiness configured by default today, with continuous observability following in Phase 2; Temurin is for teams who prefer to configure observability themselves.

From Azul Zulu

Direct swap for Zulu Community. Azul Platform Prime uses a different JVM (Falcon JIT, C4 GC); swapping to Eliya reverts to standard HotSpot behaviour. Benchmark before committing.

From Oracle JDK

The primary motivation is usually licensing. Oracle JDK under the "No-Fee Terms and Conditions" licence has restrictions Eliya does not. Oracle's Flight Recorder is the same code as the OpenJDK version shipped in Eliya.

From Liberica / BellSoft

Direct swap for Liberica Standard JDK. Liberica Full JDK bundles JavaFX; Eliya does not. If your application uses JavaFX, either stay on Liberica Full or add OpenJFX as an explicit dependency.

From SapMachine

Direct swap. SapMachine is SAP's OpenJDK build, used heavily inside SAP HANA-adjacent workloads. Same upstream OpenJDK base; SapMachine adds SAP-specific patches that are irrelevant outside SAP's ecosystem. Eliya is a clean alternative if you're not coupled to the SAP-specific bits.

From Microsoft Build of OpenJDK

Direct swap. Microsoft Build of OpenJDK is the default JDK on many Azure services; switching to Eliya is purely a runtime choice and doesn't affect Azure service compatibility. Eliya runs identically on Azure App Service, AKS, and VMs.

From Red Hat OpenJDK

Direct swap. Red Hat OpenJDK is bundled with RHEL and CentOS Stream. If your motivation for moving is observability defaults or the Phase 2–4 trajectory, Eliya is additive; if your motivation is keeping the Red Hat support contract, stay on Red Hat OpenJDK.

From IBM Semeru (OpenJ9)

Not a direct swap. Semeru uses the OpenJ9 JVM, a different runtime from HotSpot, with different GC implementations, JIT behaviour, and memory characteristics. Eliya is HotSpot-based. Switching requires benchmark validation and possibly heap-size retuning. Most heap-tuning advice for OpenJ9 does not transfer to HotSpot.

From GraalVM

Not a direct swap. GraalVM uses the Graal JIT compiler (not C1/C2) and optionally Native Image (ahead-of-time compilation). Application performance characteristics differ. Eliya is a HotSpot/C1+C2 runtime; switching means giving up Graal's polyglot and Native Image capabilities. If you rely on Native Image specifically, Eliya is not a replacement; if you rely on Graal JIT for peak throughput, benchmark before committing.

Diagnostic data portability

Diagnostic artifacts captured on other OpenJDK distributions work on Eliya:

• JFR recordings are binary-compatible across OpenJDK distributions at the same major version. Recordings captured on Corretto 25 or Temurin 25 can be analysed by Eclipse MAT, JMC, or (Phase 2) asymm eliya analyze-heap on Eliya 25.
• HPROF heap dumps are standardised across JVMs. Eclipse MAT reports on the same dump regardless of source.
• GC logs use upstream OpenJDK unified logging format. Tools like GCViewer and gceasy.io parse them identically across distributions.

Migrating runtimes does not lose access to historical diagnostic data or require re-analysis.

Build tooling

Maven, Gradle, Ant, sbt, and other build tools work identically on Eliya; the JDK is invoked the same way, the modular runtime image is in the same location, and Maven Toolchain definitions work without modification:

Rollback

Switching back to your previous JDK is the same procedure in reverse.

Via SDKman:

Via update-alternatives:

Select your previous JDK from the numbered list.

Application-side rollback. Remove -XX:EliyaProfile=Production from your JVM arguments. Without the flag, even with Eliya as the runtime, behaviour is identical to upstream OpenJDK 25, so a rollback by simply removing the flag (rather than reverting the runtime) is also valid.

Eliya's defaults are opt-in. Reverting requires no migration of diagnostic data, no code changes, no configuration changes beyond JVM runtime selection.

What you're migrating into

This page describes today's migration: Phase 1 of Eliya. The Eliya trajectory matters for migration planning:

• Phase 1 (current): Production operational-readiness defaults via EliyaProfile=Production (this page).
• Phase 2: Bundled local diagnostic tooling (Eclipse MAT headless, async-profiler), FIPS-validated variant, asymm eliya CLI expansion. No migration changes: same Eliya distribution, expanded capability.
• Phase 3 (target 2027): Asymm Forensics: cross-correlation platform analysing JFR + heap dumps + thread dumps + GC logs + crash logs together. Local execution, no SaaS dependency.
• Phase 4 (demand-gated): Compliance-aligned profiles (EliyaProfile=PCIDSS, =HIPAA, =SOX, =FedRAMP, plus combined profiles like =Healthcare-Payment for industries needing multiple frameworks). No migration changes: same runtime, additional profile values.

The migration path you adopt today (Eliya runtime + EliyaProfile=Production) remains the foundation across all phases. Phase 2/3/4 additions are additive; no further migration required.

For the consolidated phase-by-phase trajectory and demand-gating mechanics, see the roadmap page. For positioning relative to APM tools and other JDK distributions, see JVM forensics vs APM and Choosing a JDK in 2026.