Skip to content

Commit 414d303

Browse files
ivzhelevivzhelev
authored
Create adoption-migration-details.md
1 parent cd4bd7b commit 414d303

1 file changed

Lines changed: 169 additions & 0 deletions

File tree

‎adoption-migration-details.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# Java Buildpack Migration: Adoption and Migration Details
2+
3+
## Overview
4+
5+
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.
6+
7+
## Default Version Changes
8+
9+
### Ruby-based Buildpack Defaults
10+
- **Java Version**: OpenJDK JRE 1.8.0_x
11+
- **Tomcat Version**: Tomcat 9.0.x
12+
13+
### Go-based Buildpack Defaults
14+
- **Java Version**: OpenJDK JRE 17.x
15+
- **Tomcat Version**: Tomcat 10.x
16+
17+
## Impact on Legacy Applications
18+
19+
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:
20+
21+
### Tomcat 9 to Tomcat 10 Migration
22+
23+
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.*`.
24+
25+
**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.
26+
27+
A [migration tool](https://github.com/apache/tomcat-jakartaee-migration) has been developed to aid this process.
28+
29+
### Java 8 to Java 17 Migration
30+
31+
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).
32+
33+
## When Changes Take Effect
34+
35+
**Important**: If you haven't explicitly set Tomcat or Java versions, your applications are currently using the Ruby-based buildpack defaults:
36+
- Tomcat 9 by default
37+
- Java 1.8.x by default
38+
39+
**Starting with the Go-based Java Buildpack, they will be switched to:**
40+
- Tomcat 10
41+
- Java 17
42+
43+
**This change will take effect only after redeploy or restage.**
44+
45+
## How to Maintain Current Versions
46+
47+
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.
48+
49+
### Specifying Tomcat Version
50+
51+
To continue using Tomcat 9, add the following to your `manifest.yml`:
52+
53+
```yaml
54+
env:
55+
JBP_CONFIG_TOMCAT: '{ tomcat: { version: "9.+" } }'
56+
```
57+
58+
### Specifying Java Version
59+
60+
To continue using an older Java version (e.g., Java 11), add the following to your `manifest.yml`:
61+
62+
```yaml
63+
env:
64+
JBP_CONFIG_OPEN_JDK_JRE: '{ jre: { version: 11.+ } }'
65+
```
66+
67+
## Breaking Changes
68+
69+
This section highlights significant breaking changes introduced in the Go-based Java Buildpack.
70+
71+
### Custom JRE Usage
72+
73+
Custom JRE usage will be supported only as documented in the [Custom JRE Usage Guide](custom-jre-usage.md).
74+
75+
### Changed Default Configuration
76+
77+
- **SpringAutoReconfigurationFramework is now disabled by default.** Please note that `SpringAutoReconfigurationFramework` is deprecated, and the recommended alternative is [java-cfenv](httpss://github.com/pivotal-cf/java-cfenv).
78+
- **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](https://github.com/cloudfoundry/java-buildpack/blob/feature/go-migration/README.md#jre-selection).
79+
80+
### Frameworks Not Included
81+
82+
The following frameworks will not be migrated to the Go buildpack:
83+
84+
- **Takipi Agent (OverOps)**: Removed because the agent has moved behind a licensed login wall, making it inaccessible for automated buildpack integration.
85+
- **Java Security**: Rarely used and custom security policies should be implemented at the platform level or within application code.
86+
- **Multi Buildpack**: No longer needed as multi-buildpack support is now built into the `libbuildpack` architecture by default.
87+
- **Spring Insight**: Legacy monitoring tool that has been replaced by modern APM solutions (such as New Relic, AppDynamics, and Dynatrace).
88+
- **Configuration based on resource overlay**: This is more of an anti-pattern and requires a fork of the buildpack.
89+
90+
## Adoption/Migration Details
91+
92+
There are two main aspects to consider when migrating to the Go-based Java Buildpack:
93+
94+
### 1. Migration from Java 8 to Later Java Versions
95+
96+
**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).
97+
98+
**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.
99+
100+
**Effort Required**: For the vast majority of applications, there should be no effort involved in the Java version migration.
101+
102+
### 2. Migration from Java EE `javax.*` to Jakarta EE `jakarta.*`
103+
104+
**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.
105+
106+
**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:
107+
108+
#### Recommended Migration Tools
109+
110+
1. **OpenRewrite** - Automated source code refactoring
111+
- [Migration Recipe: JavaxMigrationToJakarta](https://docs.openrewrite.org/recipes/java/migrate/jakarta/javaxmigrationtojakarta)
112+
113+
2. **Apache Tomcat Migration Tool** - Binary transformation tool
114+
- [Tomcat Jakarta EE Migration Tool](https://github.com/apache/tomcat-jakartaee-migration)
115+
116+
3. **Apache TomEE Migration Guide** - Comprehensive migration guide
117+
- [TomEE: javax to jakarta Migration](https://tomee.apache.org/javax-to-jakarta.html)
118+
119+
**Testing**: It's always important to thoroughly test your scenarios after the migration to ensure all functionality works as expected.
120+
121+
## Migration Strategy Recommendations
122+
123+
### Option 1: Immediate Migration (Recommended)
124+
1. Review your application code and dependencies for `javax.*` usage
125+
2. Use one of the automated migration tools listed above
126+
3. Thoroughly test your application
127+
4. Deploy using the Go-based buildpack with default settings
128+
129+
### Option 2: Staged Migration
130+
1. **Phase 1**: Explicitly set your current versions in `manifest.yml`:
131+
```yaml
132+
env:
133+
JBP_CONFIG_TOMCAT: '{ tomcat: { version: "9.+" } }'
134+
JBP_CONFIG_OPEN_JDK_JRE: '{ jre: { version: 8.+ } }'
135+
```
136+
2. **Phase 2**: Upgrade Java version first (if needed), test thoroughly
137+
3. **Phase 3**: Migrate to Jakarta EE namespace, upgrade to Tomcat 10, test thoroughly
138+
4. **Phase 4**: Remove explicit version configurations to use defaults
139+
140+
### Option 3: Maintain Current Versions Until EOL
141+
1. Explicitly set both Tomcat 9 and your current Java version
142+
2. Plan migration before EOL dates
143+
3. Monitor EOL announcements for your versions
144+
145+
## Additional Resources
146+
147+
- [OpenRewrite: JavaxMigrationToJakarta Recipe](https://docs.openrewrite.org/recipes/java/migrate/jakarta/javaxmigrationtojakarta)
148+
- [Apache Tomcat Jakarta EE Migration Tool](https://github.com/apache/tomcat-jakartaee-migration)
149+
- [Apache TomEE: javax to jakarta Migration Guide](https://tomee.apache.org/javax-to-jakarta.html)
150+
- [RFC-0050: Java Buildpack Migration to Golang](https://raw.githubusercontent.com/cloudfoundry/community/refs/heads/main/toc/rfc/rfc-0050-java-buildpack-migration-to-golang.md)
151+
152+
## Support and Feedback
153+
154+
If you encounter issues during migration or have questions:
155+
1. Review the [buildpack documentation](../README.md)
156+
2. Check the [RFC document](https://github.com/cloudfoundry/community/pull/1392) for detailed technical information
157+
3. Open an issue in the [Java Buildpack repository](https://github.com/cloudfoundry/java-buildpack)
158+
159+
## Summary Checklist
160+
161+
Before deploying with the Go-based Java Buildpack:
162+
163+
- [ ] Review your application for `javax.*` package usage
164+
- [ ] Decide on migration strategy (immediate, staged, or maintain current)
165+
- [ ] If maintaining current versions, update `manifest.yml` with explicit version configurations
166+
- [ ] If migrating, choose and run appropriate migration tool
167+
- [ ] Test thoroughly in non-production environment
168+
- [ ] Plan deployment and rollback strategy
169+
- [ ] Monitor application after deployment

0 commit comments

Comments
 (0)