Red Hat SummitEclipse Plugin Guide
Identify and resolve migration issues by running the Red Hat Application Migration Toolkit against your applications in Eclipse.
Abstract
Chapter 1. Introduction
1.1. About the Eclipse Plugin Guide
This guide is for engineers, consultants, and others who want to use the Eclipse plugin for Migration Toolkit for Applications (MTA) to assist with migrating applications.
This guide uses Eclipse to refer to an installation of Eclipse or Red Hat Developer Studio.
1.2. About Migration Toolkit for Applications
What is Migration Toolkit for Applications?
Migration Toolkit for Applications (MTA) is an extensible and customizable rule-based tool that helps simplify migration of Java applications.
MTA examines application artifacts, including project source directories and application archives, then produces an HTML report that highlights areas needing changes. MTA can be used to migrate Java applications from previous versions of Red Hat JBoss Enterprise Application Platform or from other containers, such as Oracle® WebLogic Server or IBM® WebSphere® Application Server.
How Does Migration Toolkit for Applications Simplify Migration?
Migration Toolkit for Applications looks for common resources and highlights technologies and known trouble spots when migrating applications. The goal is to provide a high-level view into the technologies used by the application and provide a detailed report organizations can use to estimate, document, and migrate enterprise applications to Java EE and Red Hat JBoss Enterprise Application Platform.
How Do I Learn More?
See the Getting Started Guide to learn more about the features, supported configurations, system requirements, and available tools in the Migration Toolkit for Applications.
1.3. About the Eclipse Plugin
The Eclipse plugin for Migration Toolkit for Applications provides assistance directly in Eclipse and Red Hat Developer Studio for developers making changes for a migration or modernization effort. It analyzes your projects using MTA, marks migration issues in the source code, provides guidance to fix the issues, and offers automatic code replacement when possible.
1.4. Supported Configurations
The Eclipse plugin is tested in following development environments.
- Eclipse 4.8 (Photon)
- Red Hat Developer Studio 12.9
Chapter 2. Install the Eclipse Plugin
Review the supported configurations to make sure that you are using a development environment that is compatible with the Eclipse plugin.
If you are running macOS, it is recommended to set the maximum number of user processes, maxproc, to at least 2048, and the maximum number of open files, maxfiles, to 100000.
If you do not already have an existing installation, download Eclipse or Red Hat Developer Studio and install it.
This guide uses Eclipse to refer to an installation of Eclipse or Red Hat Developer Studio.
Prerequisites
- If you are using Eclipse, and not Red Hat Developer Studio, then you must install JBoss Tools before installing the Eclipse Plugin.
Install the Plugin
- Launch Eclipse.
- From the menu bar, select Help → Install New Software.
Add the MTA update site.
- Next to the Work with field, click Add.
-
In the Name field, enter
MTA. -
In the Location field, enter
http://download.jboss.org/jbosstools/photon/stable/updates/rhamt/and press OK. - Select all of the checkboxes under JBoss Tools - RHAMT and press Next.
- Review the installation details and press Next.
- Accept the terms of the license agreement and press Finish to install the plugin.
- Restart Eclipse for the changes to take effect.
Install the Plugin for an Offline Environment
- Download the Eclipse Plugin Repository.
- Launch Eclipse.
- From the menu bar, select Help → Install New Software.
Add the MTA update site.
- Next to the Work with field, click Add.
-
In the Name field, enter
MTA - Offline. - Next to the Location field, click Archive.
- Select the file downloaded in the first step and click OK.
- Select all of the checkboxes under JBoss Tools - RHAMT and press Next.
- Review the installation details and press Next.
- Accept the terms of the license agreement and press Finish to install the plugin.
- Restart Eclipse for the changes to take effect.
Chapter 3. Access the MTA Eclipse Tools
Once the plugin is installed, the MTA Eclipse tools are available in the MTA perspective. To open the MTA perspective, navigate to Window → Perspective → Open Perspective → Other. Select MTA and press OK.
Review the plugin components and then get started identifying and resolving migration issues. You can also view the embedded help for the plugin by selecting Help → Getting Started in Eclipse.
3.1. Eclipse Plugin Components
The following components are available in the MTA perspective when using the Eclipse plugin to analyze projects.
- Issue Explorer
This view allows you to explore the MTA issues for projects that have been analyzed.
If this view is not visible in the MTA Perspective, you can open it by selecting Window → Show View → Issue Explorer.
- MTA Server
The MTA server is a separate process that executes the MTA analysis, flags the migration issues, and generates the reports.
You can start, stop, and view the status of the MTA server from the Issue Explorer.
- Issue Details
This view shows detailed information about the selected MTA issue, including the hint, severity, and any additional resources.
If this view is not visible in the MTA Perspective, you can open it by selecting Window → Show View → Issue Details.
- MTA Report
This view shows the HTML reports that are generated when MTA is executed. From the report landing page you can navigate to detailed reports, such as Application Details, Issues, and Dependencies.
Note that the MTA run configuration used must have the Generate Report option selected in order for the MTA reports to be generated.
If this view is not visible in the MTA Perspective, you can open it by selecting Window → Show View → MTA Report.
Chapter 4. Identify and Resolve Migration Issues
Follow these steps to use the Eclipse plugin to identify and resolve migration issues.
- Import the project to analyze into Eclipse.
Create a run configuration. From the Issue Explorer, press the MTA button (
).
At a minimum, select the project to analyze. Set additional options as needed.
- Click Run to execute MTA.
- Review MTA issues listed in the Issue Explorer.
- Resolve MTA issues by manually updating code or by using quick fixes when available.
-
Run MTA again as necessary. Use the drop down next to the Run button (
) to run an existing configuration.
4.1. Create an MTA Run Configuration
MTA run configurations can be created using the MTA button (
). A run configuration specifies the project to analyze, migration path, and additional options for the execution. You can create multiple run configurations, and each must have a unique name.
Input
- Migration Path
- Select a migration path, which determines which MTA rulesets are used. The migration path defaults to Anything to EAP 7, but can be changed to any supported migration path.
- Projects
- Select one or more projects to analyze. Hold the Ctrl key to select multiple projects in the list.
- Packages
- Select one or more packages to scan. It is recommended to select only those packages that you need to analyze to reduce the overall MTA execution time. If no packages are selected, all packages in the project will be scanned. Hold the Ctrl key to select multiple packages in the list.
Options
- Report
- Check the Generate Report checkbox if you want to generate the MTA HTML report. The report will be shown in the MTA Report tab and can be found in the Issue Explorer when you group by File.
- Options
-
Set additional MTA options. Any option that is a boolean flag, such as
enableTattletale, should usetrueas the value. See the MTA Command-line Arguments section of the CLI Guide for a description of each MTA argument.
Rules
- Custom Rules Repositories
- Select custom rulesets to include during analysis if you have imported or created any custom MTA rules in the Eclipse plugin. See Add Custom Rules for more information.
4.2. Execute MTA
Once a run configuration has been created, you can execute MTA using that configuration in one of the following ways:
- Select the run configuration from the Run Configurations dialog and click Run.
-
Select a recent run configuration from the drop down next to the Run button (
).
If the MTA server is not currently running, it will start once a run configuration is executed.
If you do not plan on running MTA in the near future, it is recommended to stop the MTA server to conserve memory on your machine.
Once execution is complete, the Issue Explorer will be populated with MTA issues.
4.3. Review MTA Issues
Use the Issue Explorer to review migration issues identified by MTA. Different icons indicate the issue’s severity and state.
Change how issues are grouped by adjusting the Group By selections: Severity, Migration Rule, and File.
Double-click the MTA issue in the Issue Explorer to open the associated line of code in an editor. Right-click and select Issue Details to view information about the MTA issue, including its severity and how to address it.
4.4. Resolve MTA Issues
You can resolve MTA issues by updating the code manually or by applying a quick fix when available.
4.4.1. Resolve an Issue Manually
Review the MTA issue details and additional resources and update the source code as necessary. When you update a line of code marked as an MTA issue, the MTA issue will be marked with the stale icon (
) until the next time that MTA is run on the project.
You can also manually mark an MTA issue as fixed, which will mark the issue with the resolved icon (
) until the next time that MTA is run on the project. To mark an issue as fixed, right-click the MTA issue in the Issue Explorer and select Mark as Fixed.
4.4.2. Resolve an Issue Using a Quick Fix
Some MTA issues provide a quick fix, which assists in making the necessary edits to address the issue. See the icon legend to see the icons that indicate the MTA issue has a quick fix available.
- Preview a Quick Fix
- Right-click the issue and select Preview Quick Fix. This will bring up a window that allows you to preview the change. From here, you can apply the fix or close the window.
- Apply a Quick Fix
- Right-click the issue and select Apply Quick Fix. This will update the source code as required and will mark the MTA issue as resolved.
Chapter 5. Add Custom Rules
By default, the Eclipse plugin comes with a core set of system rules for identifying migration and modernization issues. You can browse the existing rules from the Eclipse plugin.
You can also create your own rules for identifying issues specific to your applications. You can either import an existing custom ruleset or create a custom ruleset directly in the Eclipse plugin.
5.1. Browse Rules
You can view both system and custom rules from the Eclipse plugin.
- From the MTA perspective, open the Rulesets tab.
Expand the System item to view core system rules, or expand the Custom item to view custom rules.
NoteIn order to view system rules, the MTA server must be started.
- Expand the ruleset containing the rule you want to review.
- Double-click the rule to open the rule in a viewer. You can select the Source tab to view the XML source of the rule.
5.2. Import a Custom Ruleset
You can import an existing custom ruleset into the Eclipse plugin to use during analysis of your projects.
- From the MTA perspective, open the Rulesets tab.
-
Click the import ruleset icon (
).
Browse to and select the XML rule file to import.
NoteThe XML rule file must use the
.windup.xmlor.rhamt.xmlextension in order to be recognized as an MTA rule.- The custom ruleset is now shown under the Custom item in the Rulesets tab.
This custom ruleset can now be selected in run configurations when analyzing projects.
See the Rules Development Guide to learn more about creating custom XML rules.
5.3. Create a Custom Ruleset
You can create a new custom ruleset in the Eclipse plugin to use during analysis of your projects.
- From the MTA perspective, open the Rulesets tab.
-
Click the create ruleset icon (
).
- Select the project and directory to save the new ruleset in.
Enter the file name for the ruleset file.
NoteThe XML rule file must use the
.windup.xmlor.rhamt.xmlextension in order to be recognized as an MTA rule.-
Enter a ruleset ID, for example,
my-ruleset-id. - Optionally, check the Generate quickstart template checkbox to add basic rule templates to the ruleset file.
- Select Finish.
- The new ruleset file opens in an editor and you can add and edit rules in the file. You can also select the Source tab to edit the XML source for the ruleset file.
This new ruleset can now be selected in run configurations when analyzing projects.
See the Rules Development Guide to learn more about creating custom XML rules.
5.4. Submit a Custom Ruleset
Once a custom ruleset has been created it can be submitted for inclusion within the official MTA rule repository. This allows your custom rules to be reviewed and included in subsequent releases of MTA, enhancing the applications and server configurations that MTA analyzes.
- From the MTA perspective, open the Rulesets tab.
-
Click the dropdown icon (
).
- Click Submit Ruleset from the options that appear. This will launch a new page in your browser.
On the page that appears complete the following fields.
- In the Summary field, enter in the purpose of the rule. This becomes the title of the submission.
- In the Code Sample text field, enter an example of source code that the rule should run against.
- Click Choose Files and navigate to the saved rule to attach it.
- In the Description text field, enter in a brief description of the rule.
- Once all information has been entered, click Submit to complete the submission.
Appendix A. Reference Material
A.1. MTA Issue Icon Legend
In the Issue Explorer and file editors, MTA issues use an icon to indicate their severity level and status. The following table describes the meaning of the various icons.
| Icon | Description |
|---|---|
 | The issue is mandatory to fix for a successful migration. |
 | The issue is optional to fix for migration. |
 | The issue may potentially be an issue during migration. |
| The issue has been resolved. |
| The issue is stale because the code marked as an issue has been modified since the last time that MTA was run on the project. |
 | A quick fix is available for this issue, which is mandatory to fix for a successful migration. |
 | A quick fix is available for this issue, which is optional to fix for migration. |
 | A quick fix is available for this issue, which may potentially be an issue during migration. |
A.2. Install JBoss Tools into Eclipse
The Eclipse Plugin depends on JBoss Tools, and therefore these dependencies must be installed for MTA to function successfully. The following instructions detail installing JBoss Tools on an Eclipse installation.
Install JBoss Tools
- From the menu bar, select Help → Eclipse Marketplace.
-
In the Find field, enter
JBoss Toolsand press Enter to search for the project. - Scroll down until you see JBoss Tools in the list and press Install next to this project.
- Review the selected features and press Confirm. It is recommended to accept the defaults to install the required dependencies for MTA.
-
Ensure that the first radio button,
Keep my installation the same and modify the items being installed to be compatible, is selected. - Review the selected packages and click Confirm.
- Accept the terms of the license agreement and click Finish.
- Click Install anyway to accept the certificates.
- Click Select all to trust all of the specified certificates, and then click Accept selected.
- Restart Eclipse for the changes to take effect.
Revised on 2022-11-10 16:17:54 UTC
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}