Skip to content

adoption-migration-details.md

Latest commit

 

History

History
169 lines (110 loc) · 8.24 KB

adoption-migration-details.md

File metadata and controls

169 lines (110 loc) · 8.24 KB

Java Buildpack Migration: Adoption and Migration Details

Overview

The Go-based Java Buildpack introduces changes to default versions that may affect legacy applications. This document provides guidance on understanding these changes and migrating your applications smoothly.

Default Version Changes

Ruby-based Buildpack Defaults

  • Java Version: OpenJDK JRE 1.8.0_x
  • Tomcat Version: Tomcat 9.0.x

Go-based Buildpack Defaults

  • Java Version: OpenJDK JRE 17.x
  • Tomcat Version: Tomcat 10.x

Impact on Legacy Applications

If your application does not explicitly specify Java or Tomcat versions in its manifest.yml, the new defaults will apply after redeploying or restaging your application. This change can cause potential issues for legacy applications, particularly:

Tomcat 9 to Tomcat 10 Migration

The migration from Tomcat 9 to Tomcat 10 will likely require code modifications in your application due to the namespace change from javax.* to jakarta.*.

Important Note: Users of Tomcat 10 onwards should be aware that, as a result of the move from Java EE to Jakarta EE as part of the transfer of Java EE to the Eclipse Foundation, the primary package for all implemented APIs has changed from javax.* to jakarta.*. This will almost certainly require code changes to enable applications to migrate from Tomcat 9 and earlier to Tomcat 10 and later.

A migration tool has been developed to aid this process.

Java 8 to Java 17 Migration

Applications compiled with Java 8 should generally run on Java 17 without issues, as Java versions are backward compatible. However, there are edge cases to consider (see Adoption/Migration Details below).

When Changes Take Effect

Important: If you haven't explicitly set Tomcat or Java versions, your applications are currently using the Ruby-based buildpack defaults:

  • Tomcat 9 by default
  • Java 1.8.x by default

Starting with the Go-based Java Buildpack, they will be switched to:

  • Tomcat 10
  • Java 17

This change will take effect only after redeploy or restage.

How to Maintain Current Versions

If you want to continue using your current versions until their End-of-Life (EOL) dates, you need to explicitly specify them in your configuration files.

Specifying Tomcat Version

To continue using Tomcat 9, add the following to your manifest.yml:

env:
  JBP_CONFIG_TOMCAT: '{ tomcat: { version: "9.+" } }'

Specifying Java Version

To continue using an older Java version (e.g., Java 11), add the following to your manifest.yml:

env:
  JBP_CONFIG_OPEN_JDK_JRE: '{ jre: { version: 11.+ } }'

Breaking Changes

This section highlights significant breaking changes introduced in the Go-based Java Buildpack.

Custom JRE Usage

Custom JRE usage will be supported only as documented in the Custom JRE Usage Guide.

Changed Default Configuration

  • SpringAutoReconfigurationFramework is now disabled by default. Please note that SpringAutoReconfigurationFramework is deprecated, and the recommended alternative is java-cfenv.
  • JRE selection based on JBP_CONFIG_COMPONENTS is deprecated. The Go-based buildpack supports JRE selection based on JBP_CONFIG_<JRE_TYPE> as described in the README.

Frameworks Not Included

The following frameworks will not be migrated to the Go buildpack:

  • Takipi Agent (OverOps): Removed because the agent has moved behind a licensed login wall, making it inaccessible for automated buildpack integration.
  • Java Security: Rarely used and custom security policies should be implemented at the platform level or within application code.
  • Multi Buildpack: No longer needed as multi-buildpack support is now built into the libbuildpack architecture by default.
  • Spring Insight: Legacy monitoring tool that has been replaced by modern APM solutions (such as New Relic, AppDynamics, and Dynatrace).
  • Configuration based on resource overlay: This is more of an anti-pattern and requires a fork of the buildpack.

Adoption/Migration Details

There are two main aspects to consider when migrating to the Go-based Java Buildpack:

1. Migration from Java 8 to Later Java Versions

Compatibility: In general, Java versions are backward compatible. Even if an application is compiled with Java 8, it should run on any later version (including Java 17).

Exceptions: The main exception is if your application uses internal and/or undocumented Java APIs that might have been removed or changed in later versions. This should be a rather exceptional case.

Effort Required: For the vast majority of applications, there should be no effort involved in the Java version migration.

2. Migration from Java EE javax.* to Jakarta EE jakarta.*

When This Applies: If your application or its dependencies use any of the former Java EE javax.* packages, you will need to migrate to the Jakarta EE jakarta.* namespace.

Migration Approach: You can choose to use several (semi-)automated tools available to help run the migration. Some of these tools with detailed how-to guides include:

Recommended Migration Tools

  1. OpenRewrite - Automated source code refactoring

  2. Apache Tomcat Migration Tool - Binary transformation tool

  3. Apache TomEE Migration Guide - Comprehensive migration guide

Testing: It's always important to thoroughly test your scenarios after the migration to ensure all functionality works as expected.

Migration Strategy Recommendations

Option 1: Immediate Migration (Recommended)

  1. Review your application code and dependencies for javax.* usage
  2. Use one of the automated migration tools listed above
  3. Thoroughly test your application
  4. Deploy using the Go-based buildpack with default settings

Option 2: Staged Migration

  1. Phase 1: Explicitly set your current versions in manifest.yml: 
    env:
  JBP_CONFIG_TOMCAT: '{ tomcat: { version: "9.+" } }'
  JBP_CONFIG_OPEN_JDK_JRE: '{ jre: { version: 8.+ } }'
  2. Phase 2: Upgrade Java version first (if needed), test thoroughly
  3. Phase 3: Migrate to Jakarta EE namespace, upgrade to Tomcat 10, test thoroughly
  4. Phase 4: Remove explicit version configurations to use defaults

Option 3: Maintain Current Versions Until EOL

  1. Explicitly set both Tomcat 9 and your current Java version
  2. Plan migration before EOL dates
  3. Monitor EOL announcements for your versions

Additional Resources

Support and Feedback

If you encounter issues during migration or have questions:

  1. Review the buildpack documentation
  2. Check the RFC document for detailed technical information
  3. Open an issue in the Java Buildpack repository

Summary Checklist

Before deploying with the Go-based Java Buildpack:

  • Review your application for javax.* package usage
  • Decide on migration strategy (immediate, staged, or maintain current)
  • If maintaining current versions, update manifest.yml with explicit version configurations
  • If migrating, choose and run appropriate migration tool
  • Test thoroughly in non-production environment
  • Plan deployment and rollback strategy
  • Monitor application after deployment