Eclipse and Red Hat CodeReady Studio Guide

Migration Toolkit for Runtimes 1.0

Identify and resolve migration issues by analyzing your applications with the MTR plugin for Eclipse or Red Hat CodeReady Studio.

Red Hat Customer Content Services

Abstract

This guide describes how to use the MTR plugin for Eclipse or Red Hat CodeReady Studio to simplify the migration of Java applications.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

Chapter 1. Introduction

1.1. About the MTR plugin for Eclipse and Red Hat CodeReady Studio

You can migrate and modernize applications by using the Migration Toolkit for Runtimes (MTR) plugin for Eclipse and Red Hat CodeReady Studio.

The MTR plugin analyzes your projects using customizable rulesets, marks issues in the source code, provides guidance to fix the issues, and offers automatic code replacement, if possible.

1.2. About the Migration Toolkit for Runtimes

What is the Migration Toolkit for Runtimes?

The Migration Toolkit for Runtimes (MTR) is an extensible and customizable rule-based tool that simplifies the migration and modernization of Java applications.

MTR examines application artifacts, including project source directories and application archives, and then produces an HTML report highlighting areas needing changes. MTR supports many migration paths including the following examples:

  • Upgrading to the latest release of Red Hat JBoss Enterprise Application Platform
  • Migrating from Oracle WebLogic or IBM WebSphere Application Server to Red Hat JBoss Enterprise Application Platform
  • Containerizing applications and making them cloud-ready
  • Migrating from Java Spring Boot to Quarkus
  • Updating from Oracle JDK to OpenJDK
  • Upgrading from OpenJDK 8 to OpenJDK 11
  • Upgrading from OpenJDK11 to OpenJDK 17
  • Migrating EAP Java applicatons to Azure
  • Migrating Spring Boot Java applications to Azure

For more information about use cases and migration paths, see the MTR for developers web page.

How does the Migration Toolkit for Runtimes simplify migration?

The Migration Toolkit for Runtimes looks for common resources and known trouble spots when migrating applications. It provides a high-level view of the technologies used by the application.

MTR generates a detailed report evaluating a migration or modernization path. This report can help you to estimate the effort required for large-scale projects and to reduce the work involved.

How do I learn more?

See the Introduction to the Migration Toolkit for Runtimes to learn more about the features, supported configurations, system requirements, and available tools in the Migration Toolkit for Runtimes.

Chapter 2. Installing the MTR plugin

You can install the MTR plugin in a connected or a restricted network environment.

2.1. Installing in a connected environment

You can install the MTR plugin in a connected environment.

The MTR plugin has been tested with the Eclipse IDE for Java Enterprise Developers 2022-03 and Red Hat CodeReady Studio 12.21.3.GA.

Prerequisites

Procedure

  1. Launch Eclipse or CodeReady Studio.
  2. From the menu bar, select Help → Install New Software.
  3. Next to the Work with field, click Add.
  4. In the Name field, enter MTR.
  5. In the Location field, enter http://download.jboss.org/jbosstools/photon/stable/updates/mtr/ and click OK.
  6. Select all the JBoss Tools - MTR check boxes and click Next.
  7. Review the installation details and click Next.
  8. Accept the terms of the license agreement and click Finish.
  9. Restart Eclipse or CodeReady Studio.

2.2. Installing in a disconnected environment

You can install the MTR plugin in a disconnected network environment.

The MTR plugin has been tested with the Eclipse IDE for Java Enterprise Developers 2022-03 and Red Hat CodeReady Studio 12.21.3.GA.

Prerequisites

Procedure

  1. On a computer with network access, navigate to the Migration Toolkit for Runtimes download site and download the migrationtoolkit-mtr-eclipse-plugin-repository file.
  2. Launch Eclipse or CodeReady Studio.
  3. From the menu bar, select Help → Install New Software.
  4. Next to the Work with field, click Add.
  5. In the Name field, enter MTR.
  6. Next to the Location field, click Archive.
  7. Select the migrationtoolkit-mtr-eclipse-plugin-repository file and click OK.
  8. Select all the JBoss Tools - MTR check boxes and click Next.
  9. Review the installation details and click Next.
  10. Accept the terms of the license agreement and click Finish.
  11. Restart Eclipse or CodeReady Studio.

2.3. Accessing the MTR tools

You can access the MTR plugin tools in the MTR perspective.

Prerequisites

  • You must restart the Eclipse IDE or Red Hat CodeReady Studio after installing the MTR plugin.

Procedure

  1. Click Window → Perspective → Open Perspective → Other.

  2. Select MTR and click OK.

    The following components are displayed:

    • Issue Explorer displays the migration issues identified by the MTR plugin.

    • MTR Server is a separate process that analyzes projects, flags migration issues, and generates reports.

      You can start, stop, and view the status of the MTR server in the Issue Explorer.

    • Issue Details displays detailed information about a selected issue, including the hint, severity, and any additional resources.

    • MTR Report is an HTML report generated by the MTR plugin. From the report landing page you can navigate to detailed reports, such as Application Details, Issues, and Dependencies.

      Note

      The report is not generated by default. You must select the Generate Report option in the run configuration.

Chapter 3. Analyzing your projects with the MTR plugin

You can analyze your projects with the MTR plugin by creating a run configuration, running an analysis, and then reviewing and resolving migration issues detected by the MTR plugin.

3.1. Creating a run configuration

You can create a run configuration in the Issue Explorer. A run configuration specifies the project to analyze, migration path, and additional options.

You can create multiple run configurations. Each run configuration must have a unique name.

Prerequisite

  • You must import your projects into the Eclipse IDE or CodeReady Studio.

Procedure

  1. In the Issue Explorer, click the MTR icon ( MTR button ) to create a run configuration.

  2. On the Input tab, complete the following fields:

    1. Select a migration path.
    2. Beside the Projects field, click Add and select one or more projects.

    3. Beside the Packages field, click Add and select one or more the packages.

      Note

      Specifying the packages for analysis reduces the run time. If you do not select any packages, all packages in the project are scanned.

  3. On the Options tab, you can select Generate Report to generate an HTML report. The report is displayed in the Report tab and saved as a file.

    Other options are displayed. See About MTR command-line arguments in the CLI Guide for details.

  4. On the Rules tab, you can select custom rulesets that you have imported or created for the MTR plugin.
  5. Click Run to start the analysis.

3.2. Analyzing projects

You can analyze your projects by running the MTR plugin with a saved run configuration.

Procedure

  1. In the MTR perspective, click the Run button ( Run button ) and select a run configuration.

    The MTR plugin analyzes your projects. The Issue Explorer displays migration issues that are detected with the ruleset.

  2. When you have finished analyzing your projects, stop the MTR server in the Issue Explorer to conserve memory.

3.3. Reviewing issues

You can review issues identified by the MTR plugin.

Procedure

  1. Click Window → Show View → Issue Explorer.

  2. Optional: Filter the issues by clicking the Options menu kebab , selecting Group By and an option.

    Issue Explorer "Group By" options

  3. Right-click and select Issue Details to view information about the issue, including its severity and how to address it.

    The following icons indicate the severity and state of an issue:

    Table 3.1. Issue icons

    IconDescription
    Mandatory

    The issue must be fixed for a successful migration.

    Optional

    The issue is optional to fix for migration.

    Warning

    The issue might need to be addressed during migration.

    Resolved

    The issue was resolved.

    Stale

    The issue is stale. The code marked as an issue was modified since the last time that MTR identified it as an issue.

    Mandatory with quick fix

    A quick fix is available for this issue, which is mandatory to fix for a successful migration.

    Optional with quick fix

    A quick fix is available for this issue, which is optional to fix for migration.

    Warning with quick fix

    A quick fix is available for this issue, which may potentially be an issue during migration.

  4. Double-click an issue to open the associated line of code in an editor.

3.4. Resolving issues

You can resolve issues detected by the MTR plugin by performing one of the following actions:

  • You can double-click the issue to open it in an editor and edit the source code.

    The issue displays a Stale icon ( Stale ) until the next time you run the MTR plugin.

  • You can right-click the issue and select Mark as Fixed.
  • If the issue displays a Quick Fix icon ( Mandatory with quick fix Optional with quick fix Warning with quick fix ), you can right-click the issue and select Preview Quick Fix and then Apply Quick Fix.

Chapter 4. Managing rules

The MTR plugin comes with a core set of System rules for analyzing projects and identifying migration and modernization issues.

You can create and import custom rulesets.

4.1. Viewing rules

You can view system and custom rules, if any, for the MTR plugin.

Prerequisites

  • To view system rules, the MTR server must be running.

Procedure

  1. Click the Rulesets tab.
  2. Expand System to view system rulesets or Custom to view custom rulesets.
  3. Expand a ruleset.
  4. Double-click a rule to open it in a viewer.
  5. Click the Source tab to view the XML source of the rule.

4.2. Creating a custom ruleset

You can create a custom ruleset in the MTR perspective.

See the Rules Development Guide to learn more about creating custom XML rules.

Procedure

  1. Click the Rulesets tab.
  2. Click the Create Ruleset icon ( Create ruleset icon ).
  3. Select a project and a directory for the ruleset.

  4. Enter the file name.

    Note

    The file must have the extension .windup.xml.

  5. Enter a ruleset ID, for example, my-ruleset-id.
  6. Optional: Select Generate quickstart template to add basic rule templates to the file.
  7. Click Finish.
  8. The ruleset file opens in an editor and you can add and edit rules in the file.
  9. Click the Source tab to edit the XML source of the ruleset file.

You can select the new ruleset when you create a run configuration.

4.3. Importing a custom ruleset

You can import a custom ruleset into the MTR plugin to analyze your projects.

Prerequisites

  • Custom ruleset file with a .windup.xml extension.

    See the Rules Development Guide for information about creating rulesets.

Procedure

  1. Click the Rulesets tab.
  2. Click the Import Ruleset icon ( Import ruleset icon ).

  3. Browse to and select the XML rule file to import.

    The custom ruleset is displayed when you expand Custom on the Rulesets tab.

4.4. Submitting a custom ruleset

You can submit your custom ruleset for inclusion in the official MTR rule repository. This allows your custom rules to be reviewed and included in subsequent releases of MTR.

Procedure

  1. Click the Rulesets tab.
  2. Click the Arrow icon ( Dropdown ) and select Submit Ruleset.

  3. Complete the following fields:

    • Summary: Describe the purpose of the rule. This becomes the title of the submission.
    • Code Sample: Enter an example of the source code that the rule should run against.
    • Description: Enter a brief description of the rule.
  4. Click Choose Files and select the ruleset file.
  5. Click Submit.

Legal Notice

Copyright © 2023 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.