Modernizing Java applications

You can modernize your enterprise Java applications, including WebSphere® Application Server traditional applications, to Liberty. To modernize an application, you first upload a migration plan or build and analyze your application, and then fix your application issues.

Beginning with version 1.1, you can use Application Modernization Accelerator Developer Tools with applications that are built with non-Maven tools, but with limitations. For more information, see Applications built with non-Maven build tools.

Before you begin

  1. Set up your enterprise Java environment.
  2. Install the Visual Studio Code extension, the Eclipse IDE plug-in, or the IntelliJ IDEA IDE plug-in.
Important: In the Eclipse IDE, for best results with a multimodule Java application, make sure that you import the aggregator module and each submodule as separate projects within the Eclipse workspace. If you import the top-level directory as a single project, IBM Application Modernization Accelerator Developer Tools might not successfully introspect your project.

Complete either the steps to upload your application migration plan or the steps to analyze your application. After you complete one set of steps, you can then fix issues with the migration. The steps to fix the issues are the same for both the migration plan steps and application analysis. After you fix the issues, you have a modernized application.

If you encounter a problem that uses Application Modernization Accelerator Developer Tools, refer to the Troubleshooting page.

Time required to analyze your code

The amount of time to analyze your application varies. The following times are typical.

Table 1. Time required to analyze
Time Application details
Seconds to a few minutes Fewer than 100 classes
2 to 10 minutes 20,000 to 50,000 lines of code
10 or more minutes 300,000 lines of code
Important:

When Application Modernization Accelerator Developer Tools analyzes your application, it excludes some third-party packages from code analysis by default. For more information, see Third-party packages that are excluded from application analysis.

Using a migration plan to modernize your application

The following steps assume that you are using IBM Application Modernization Accelerator to generate a migration plan. The migration plan contains a list of modernization issues that need to be addressed. It also contains automatically generated configuration information to enable the application to function properly in Liberty.

Important:
  • If you already uploaded and analyzed a migration plan for your project, uploading a new migration plan overwrites the existing analysis.
  • Before you modernize your application, do a full build of your application to help ensure that you are starting from a known good application build. This build also helps ensure that class files are up to date with the latest source code. They must be up to date before you run automations that add changes for Java version upgrades.

If you revert the changes to your code, you must click Return to upload / analyze and do a full analysis if you want to modernize your application again.

  1. In your IDE, right-click any item in the hierarchy in the directory of the application that you want to modernize, click Modernize Java Applications, then click Modernize to Liberty.
  2. On the Modernize <your application name> page, upload the migration plan.

    The IDE analyzes your project folder, gathers information about your application, and then uploads the migration plan that Application Modernization Accelerator generates.

    1. Click Upload migration plan.
    2. Select the application plan for the archive file from the list and click Open.

      When the process to upload the migration plan completes, the Modernize <your application name> page displays the following configuration files that are in the plan:

      • server.xml is the configuration file for Liberty and is required to start your application.
      • Containerfile is required only to build a container image for your Liberty application.

    3. Select the files to add to your project and then click Proceed.

      • (Required) Select the server.xml file.
      • (Optional) Select the Containerfile file only if you are building a container image for your Liberty application.

    When the upload of the migration plan completes, the issues to fix or review are displayed.

  3. If the analysis detects JAX-RPC services in your application, follow the directions on the screen to migrate JAX-RPC services to JAX-WS services.

  4. Fix issues with the application.

    Depending on the issues to fix, the ability to fix them can be automated or self-directed. The issues on the Additional information tab don't require a code change, but you might need to verify or test them and make a code change if you want.

Analyzing your application to modernize it

The following steps assume that you are analyzing your application instead of a using an Application Modernization Accelerator migration plan to modernize your application. The analysis provides you with a list of issues to address and a limited server configuration in the server.xml file. The server.xml file contains a list of features that your application uses, but it doesn't include other configuration information such as database connections or JMS configurations.

If you revert the changes to your code, you must click Return to upload / analyze and do a full analysis if you want to modernize your application again.

  1. In your IDE, right-click in the directory that you want to modernize, click Modernize Java Applications, then click Modernize to Liberty.

  2. On your Modernize <your application name> page, expand Analyze application, and click Start analysis.

  3. Select the analysis parameters, which define the rules that the application server is analyzed against.

    1. Select the application server source and the application server target.

    2. Optionally change the Java SE source, which is displayed automatically with a recommended value.

      The recommended value is based on the Java SE version that Application Modernization Accelerator Developer Tools recommends for the application server source. Your application server might be using a different Java SE version than what is recommended. If it is, then change the Java SE source to the version that your application server uses.

      For example, Application Modernization Accelerator Developer Tools recommends Java SE 8 for WebSphere Application Server V8.5.5 even though your application server might be using an earlier version of Java SE.

      Important: The minimum-supported Java version is Java 5.

    3. Select the Java SE target.

    4. Build the application and then analyze it.

      Application analysis is done on the application binary. The application must be built before analysis begins.

      • For Maven builds, you can either manually or automatically build the application.

        Click either Analyze after you manually build the application or Build and analyze to automatically build and analyze the application.

        After your application is built and analyzed, the issues to fix or review are displayed.

        When you click Build and analyze, the application is built at its current Java source version, so it can be analyzed for Java upgrade issues. Make sure to configure the IDE with the Java developer kit of the Java source version, so the IDE can successfully build the application.

      • For builds that don't use Maven, manually build the application, select the application binary, and then click Analyze.

        After your application is built and analyzed, the issues to fix or review are displayed.

  4. If the analysis detects JAX-RPC services in your application, follow the directions on the screen to migrate JAX-RPC services to JAX-WS services.

  5. Fix issues with the application.

    For Maven builds, depending on the issues to fix, the ability to fix them can be automated or self-directed.

    Since IBM Application Modernization Accelerator Developer Tools cannot run automations for builds that don't use Maven, the issues to fix are self-directed.

    The issues on the Additional information tab don't require a code change, but you might need to verify or test them and make a code change if you want.

Migrating JAX-RPC services to JAX-WS services

Beginning with IBM Application Modernization Accelerator Developer Tools version 1.1, you can modernize detected JAX-RPC services to JAX-WS services before you address any other modernization issues.
Important:
  • If you are migrating to Jakarta EE 9 or a later Jakarta EE version, migrate your JAX-RPC services to JAX-WS services first. Otherwise, the JAX-RPC source migration helper can't assist you because JAX-RPC services are not available beginning in Jakarta EE 9.
  • You must also migrate JAX-RPC services to JAX-WS before you make any other modernization fixes. If you do other modernization fixes first, the modernization might update Java EE to a version that does not support JAX-RPC services.

Either migrate JAX-RPC services to JAX-WS services manually or click Proceed. When you click Proceed, the JAX-RPC to JAX-WS source migration helper assists you with the migration.

The following steps assume that you clicked Proceed.

  1. Complete all the fixes for the .wsdl files.

    The JAX-RPC migration requires that you complete all the fixes for a .wsdl file before you work on another .wsdl file in the list.

    The following information is displayed on the main JAX-RPC migration page. Use it to complete the migration.
    Restart
    If you want to restart the migration, click Restart.
    Important:
    • When you click Restart, a message is displayed that says if you want to restart the migration, you must revert all code changes done with automated fixes and manual fixes. If you don't revert all the changes and restart the migration, .wsdl files that you previously ran automations for show up in the Unsupported (Manual migration required) section.
    • If you restarted the JAX-RPC migration without reverting your code changes, then click Restart again. Return to a version of the application code that existed before you changed the JAX-RPC flow through automated updates, manual updates, or both.
    Pending
    If you have a Pending section with one or more .wsdl files that are listed, select the section.
    Select each of the .wsdl files and complete the following work that is associated with it.
    1. Run automations.
      When you run automations, the following actions are done.
      • The application is modified to migrate the JAX-RPC services to JAX-WS services.
      • The Manual updates section is populated with directions and links so that you can manually update specific Java files.
      • The Review newly generated files section is populated with new Java parts that the recipes created.
    2. Complete manual updates for the specified Java files.
    3. Review newly generated files.
    4. Manually compile the application.
    Completed
    Select the section.

    A list of the completed .wsdl files is displayed and the list is automatically updated.

    Unsupported (Manual migration required)
    Select the section.
    If the .wsdl files have features that the JAX-RPC source migration helper does not support, the files are marked as unsupported. You can also mark .wsdl files as unsupported if you run the automations for them and they fail.
    • If the source migration helper added a .wsdl file to unsupported, manually migrate the JAX-RPC services in the .wsdl file.

      The source migration helper adds a .wsdl file to the unsupported section when the .wsdl file contains features that are not supported

    • If you marked a .wsdl file as unsupported, you can manually migrate the JAX-RPC services in the .wsdl file. You can alternatively restart the JAX-RPC services migration to run the automations for the .wsdl file.
    Unused (Safe to delete)
    Select the section to see your unused .wsdl files.

    You can delete the files since they are not used in the application.

    After you complete all the fixes for the .wsdl files, meaning that the Total WSDLs need to be fixed indicator is 0, the JAX-RPC migration is complete for the parts that the JAX-RPC source migration helper can help you with.

    Remember: Before you click the Build and analyze button that is displayed, manually migrate the .wsdl files in the unsupported section so that you complete the migration to JAX-WS services.
  2. Click Build and analyze.

    Your application that you migrated to JAX-WS services is rescanned for any remaining modernization issues.

  3. Fix issues with the application.

    For Maven builds, depending on the issues to fix, the ability to fix them can be automated or self-directed.

    For builds that don't use Maven, the issues to fix are self-directed.

    The issues on the Additional information tab don't require a code change, but you might need to verify or test them and make a code change if you want.

Fixing issues and reviewing additional information for your application

Depending on the issues to fix, the ability to fix them can be automated or self-directed. The issues on the Additional information tab don't require a code change, but you might need to verify or test them and make a code change if you want.

The Modernize <your application name> page lists the following information:

  • The application server source and the application server target
  • The Java SE version source and the Java SE version target
  • Links to a technology report, an inventory report, and an analysis report
  • Tabs for issues to fix, which can be automated or self-directed fixes, and additional information.

The target Java developer kit is required when you run automated fixes and when you build the application after the Java version target changes are made. Make sure that the target Java developer kit is configured for your IDE.

  • The plug-ins for the Eclipse IDE and the IntelliJ IDE automatically try to find the correct Java developer kit. The Java developer kit must matches the Java version target from the set of all configured Java developer kits in the IDEs.
  • In the Visual Studio Code IDE, you must manually change the Java developer kit configuration.
Completing automated fixes for Maven builds

If you have an Automated fixes tab with one or more fixes, select the tab.

Because Application Modernization Accelerator Developer Tools completes the fixes for you, you do not need to make any code changes.

  1. Expand the instructions and read them.
  2. Optionally open the issue to review the description of the issue.
  3. Click Run automated fixes.
    • The Automated fixes are fixed.
    • External issues remain in the list until you update the associated dependency.
  4. When Run automated fixes completes, click Rebuild and refresh to update the list of issues.
Important: If the automated fixes fail to run and produce compilation errors in the console output, make sure to update the version of the maven-compiler plug-in to 3.13.0 or newer.
Completing self-directed fixes

If you have a Self-directed fixes tab with one or more fixes, select the tab.

You change the code and determine how to fix the code.

  1. Expand the Instructions and follow the instructions.
  2. Expand each issue.
  3. Click Read more to expand the issue.
  4. Click the file that is listed in the issue. The file opens in the editor.
  5. As you fix issues, click Rebuild and refresh until all self-directed fixes are fixed.
Tip: For certain self-directed fixes, you might be able to use the generative AI capabilities in watsonx Code Assistant™ for Enterprise Java Applications.
Addressing additional information

If you have an Additional information tab with a number of one or more on it, select the tab.

The issues that are listed on the tab are determined the same way that issues on other tabs are determined. Although the additional information issues do not require a change to your code, review the issues so you can ensure that your application is working when your code is migrated.

The additional information might indicate issues, such as minor behavioral changes in an API, or connectivity concerns in databases or user registries, and what to do about them.

For example, you have a database that your application connects to. You read the issue for this situation. Then, you make sure that the host and port that are configured for the application are valid and accessible when the application is migrated.

  • Expand the instructions and follow them.

  • Click each issue.

    • Click Read more to expand the issue.
    • Click the link on the file that is listed in the issue to review the code.
Working on external issues outside the current application

While you work on fixes, some might be categorized as external issue occurrences outside the current application. The source code for these issues is in specified archives that are not part of the current source application.

If the archive is a library that your organization owns, complete the following steps.

  1. Open its associated source code as a separate application and use Application Modernization Accelerator Developer Tools to remediate the issues there.
  2. Update your current application to use the new remediated version.

If the archive is a library that your organization doesn’t own, complete the following step.

  • Update to a version that does not contain this issue.

    If no such version exists, you might need to use a different technology.