Upgrading language versions with the Amazon Q Developer Agent for code transformation - Amazon Q Developer
Step 1: PrerequisitesStep 2: Configure your projectStep 3: Transform your code

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 3.8 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 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 and module settings.

If your modules use the same JDK and language level as your project, you don't need to update module settings.

  • Project SDK – The JDK used to compile your project.

  • Project language level – The Java version used in your project.

  • Module SDK – The JDK used to compile your module.

  • Module language level – The Java version used in your module.

  • Maven Runner JRE – The JDK you build your module with.

Update project and module settings

To update your SDK and language level settings for your project or module, complete the following steps:

  1. From your JetBrains IDE, choose File and then Project Structure.

  2. The Project Structure window opens. Under Project Settings, choose Project.

    1. To update your project JDK, choose from the dropdown list next to SDK.

    2. To update your project language, choose from the dropdown next to Language level.

  3. Under Project Settings, choose Modules.

    1. To update your module JDK, choose from the dropdown list next to SDK.

    2. To update your module language, choose from the dropdown next to Language level.

For more information, see Project structure settings and Module structure settings in the JetBrains documentation.

Update Maven settings

To update your Maven Runner JRE, complete the following steps:

  1. From your JetBrains IDE, choose the gear icon, and then choose Settings in the menu that appears.

  2. In the Settings window, choose Build, Execution, Deployment, then Build Tools, then Maven, and then Runner.

  3. In the JRE field, choose the JDK used to build the module you're transforming.

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 in the Apache Maven documentation.

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/aws-appconfig-java-sample.

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.

JetBrains

  1. Open the module that you want to upgrade in JetBrains. Make sure you’ve successfully built your project in the IDE.

  2. Choose the Amazon Q logo, and then enter /transform in the Amazon Q chat panel that opens.

  3. A Transform your application pop-up appears. Choose the project that you want to upgrade from the dropdown list, and then choose Transform.

  4. Amazon Q begins the transformation. You can view progress on the Transformation details tab.

  5. After the transformation is complete, you can verify the upgraded code before updating your project. To view the new code, go to the Transformation details tab and then choose View diff. In the Apply patch window that appears, choose a file to open a diff view with your source code and upgraded code.

  6. To accept the changes that Amazon Q made, choose View diff to open the Apply patch window. Select all the updated files, and choose OK to update your project in place.

  7. To get details about how your code was upgraded and suggested next steps, on the Transformation details tab, choose View transformation summary.

Visual Studio Code

  1. Open the project or workspace that you want to upgrade in VS Code. Make sure that you’ve successfully built your project in the IDE.

  2. Choose the Amazon Q logo, and then enter /transform in the Amazon Q chat panel that opens.

  3. Choose the project that you want to upgrade from the search bar at the top of the IDE.

  4. If Amazon Q can’t find the version of your source code, it prompts you to choose your code version. Choose the version that your source code is written in, and then choose Transform in the pop-up to proceed.

  5. If prompted, enter the JAVA_HOME path to your JDK. For more information, see Configure your VS Code project.

  6. Amazon Q begins the transformation. You can view progress on the Transformation Hub tab.

  7. After the transformation is complete, the Proposed Changes tab opens. To verify the upgraded code before updating your project, choose Download proposed changes. Choose a file to open a diff view with your source code and upgraded code.

  8. To accept the changes Amazon Q made, go to the Proposed Changes tab and choose Accept.

  9. To get details about how your code was upgraded and suggested next steps, on the Transformation Hub, choose the Views and More Actions ellipsis button, and then choose Show Transformation Summary.