Upgrading language versions with the Amazon Q Developer Agent for code transformation
The Amazon Q Developer Agent for code transformation can upgrade the code language version of your files in place. You can transform a module in JetBrains and a project or entire workspace in Visual Studio Code.
Amazon Q first builds your code in the source language version and verifies that it has the information necessary to transform your code. After Amazon Q successfully transforms your code, you verify and accept the changes in your integrated development environment (IDE). For more information, see How the Amazon Q Developer Agent for code transformation works.
Currently, Amazon Q can upgrade Java 8 and Java 11 code to Java 17 code.
Topics
Step 1: Prerequisites
Before you continue, make sure you’ve completed the steps in Set up Amazon Q in your IDE.
Make sure that the following prerequisites are met before you begin a Code Transformation job:
-
Your project is a Java 8 or Java 11 project built on Maven.
-
Your project successfully builds with Maven in your IDE. Amazon Q Developer Agent for code transformation supports Maven 2.8, but we recommend Maven 3.9.5 or later.
-
Your project source JDK is available locally and is the version of your source code. For example, if you are transforming Java 8 code, your local JDK installation should be JDK 8.
-
Your project builds in 55 minutes or less.
-
Your project is configured correctly, and the correct JDK version is specified. For more information, see Step 2: Configure your project.
-
Your project doesn't require access to resources on your private network, including a virtual private cloud (VPC) or on-premise network. For example, if your project contains unit tests that connect to a database in your network, the transformation will fail.
-
Your project doesn't use plugins that package languages other than Java in your Java project. For example, if your project uses the frontend-maven-plugin
for executing front-end JavaScript code in addition to your Java source code, the transformation will fail. -
Your project doesn't use
pom.xml
file dependency version ranges. For example, if yourpom.xml
file includes<version>[1.0.0,)</version>
, the transformation will fail. For more information, see Version Range Specificationin the Apache Maven Project documentation. -
Your local network allows uploads to Amazon S3 buckets that Amazon Q uses to transform your code. For more information, see Allow access to Amazon S3 buckets in data perimeters.
-
Your minimum compiler version for the
maven-compiler-plugin
is v13.13.0.
Step 2: Configure your project
To configure your project, use the following information for the IDE you're using.
Configure a project in JetBrains
To configure your project in JetBrains, you might need to specify the following Project Structure settings:
-
Project SDK – The JDK used to compile your project. This must be specified in order to build your project.
-
Project language level – The Java language used in your project. This must be specified if the Java version used in your project is different from your JDK version.
-
Module language level – The Java language used in your module. This must be specified if the Java version used in your modules is different from your project or JDK version.
You might need to adjust these settings if you are using an unsupported JDK, but your project or modules use a supported language version. For example, if you’re transforming a Java 8 project, but you’re using JDK 18, you must set your project language level to Java 8.
Additionally, if your project contains multiple modules that use different language versions, you must set the language level for the module you’re transforming.
Update project settings
To update your project SDK, project language, or module language settings, complete the following steps:
-
From your JetBrains IDE, choose File and then Project Structure.
-
The Project Structure window opens. Under Project Settings, choose Project.
-
To update your JDK, choose from the dropdown menu next to SDK.
-
To update your project language, choose from the dropdown next to Language level.
-
-
Under Project Settings, choose Modules.
-
To update your module language, choose from the dropdown next to Language level.
-
For more information, see
Project structure settings
Configure a project in VS Code
To configure your project in VS Code, your project must contain the following:
-
A
pom.xml
file in the project root folder -
A
.java
file in the project directory
If your project contains a Maven wrapper executable (mvnw
for
macOS or mvnw.cmd
for Windows), make sure
it’s at the root of your project. Amazon Q will use the wrapper, and no other Maven
configuration is necessary.
If you aren’t using a Maven wrapper, install Maven. For more information, see
Installing Apache
Maven
After installing Maven, add it to your PATH
variable. For more
information, see How do I add Maven to my PATH?
Your Java runtime
variable should also be pointing to a JDK and not to a
JRE. To confirm your configuration is correct, run mvn -v
. The output
should show your Maven version and the runtime
variable pointing to the
path to your JDK.
Step 3: Transform your code
Before you transform your own code, you might want to test that your IDE is setup
correctly by transforming a sample project. Following is a sample GitHub project that is
eligible for code transformation:
https://github.com/aws-samples/qct-sample-java-8-app
To test your IDE setup, download and unzip the sample project, and complete the following steps for your IDE. If you are able to view the proposed changes and transformation summary, you are ready to transform your own code project. If the transformation fails, your IDE is not configured correctly. To address configuration issues, review Step 2: Configure your project and Troubleshooting.
Note
If you navigate away from your IDE before the transformation starts, the transformation will fail and you will have to restart.
To upgrade the language version of your code project or module, complete the following steps for your IDE.