Search
SupportConsoleDevelopersStart a trialContact

Eclipse Plugin Guide

download PDF
Red Hat Application Migration Toolkit 4.0

Simplify Migration of Java Applications

Red Hat Customer Content Services

Abstract

This guide describes how to use the Red Hat Application Migration Toolkit Eclipse plugin to simplify migration of Java applications.

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 Red Hat Application Migration Toolkit (RHAMT) to assist with migrating applications.

Note

This guide uses Eclipse to refer to an installation of Eclipse or JBoss Developer Studio.

1.2. About Red Hat Application Migration Toolkit

What is Red Hat Application Migration Toolkit?

Red Hat Application Migration Toolkit (RHAMT) is an extensible and customizable rule-based tool that helps simplify migration of Java applications.

RHAMT examines application artifacts, including project source directories and application archives, then produces an HTML report that highlights areas needing changes. RHAMT 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 Red Hat Application Migration Toolkit Simplify Migration?

Red Hat Application Migration Toolkit 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 Red Hat Application Migration Toolkit.

1.3. About the Eclipse Plugin

The Eclipse plugin for Red Hat Application Migration Toolkit provides assistance directly in Eclipse and Red Hat JBoss Developer Studio for developers making changes for a migration or modernization effort. It analyzes your projects using RHAMT, 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.7 (Oxygen)
  • Red Hat JBoss Developer Studio 11.2

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.

Note

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 JBoss Developer Studio and install it.

Note

This guide uses Eclipse to refer to an installation of Eclipse or JBoss Developer Studio.

Install the Plugin

  1. Launch Eclipse.
  2. From the menu bar, select Help → Install New Software.

  3. Add the RHAMT update site.

    1. Next to the Work with field, click Add.
    2. In the Name field, enter RHAMT.
    3. In the Location field, enter http://download.jboss.org/jbosstools/oxygen/development/updates/rhamt/composite/ and press OK.
    4. Select all of the checkboxes under JBoss Tools - RHAMT and press Next.
  4. Review the installation details and press Next.
  5. Accept the terms of the license agreement and press Finish to install the plugin.
  6. Restart Eclipse for the changes to take effect.

Install the Plugin for an Offline Environment

  1. Download the Eclipse Plugin Repository.
  2. Launch Eclipse.
  3. From the menu bar, select Help → Install New Software.

  4. Add the RHAMT update site.

    1. Next to the Work with field, click Add.
    2. In the Name field, enter RHAMT - Offline.
    3. Next to the Location field, click Archive.
    4. Select the file downloaded in the first step and click OK.
    5. Select all of the checkboxes under JBoss Tools - RHAMT and press Next.
  5. Review the installation details and press Next.
  6. Accept the terms of the license agreement and press Finish to install the plugin.
  7. Restart Eclipse for the changes to take effect.

Chapter 3. Access the RHAMT Eclipse Tools

Once the plugin is installed, the RHAMT Eclipse tools are available in the RHAMT perspective. To open the RHAMT perspective, navigate to Window → Perspective → Open Perspective → Other. Select RHAMT 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 RHAMT perspective when using the Eclipse plugin to analyze projects.

Issue Explorer

This view allows you to explore the RHAMT issues for projects that have been analyzed.

If this view is not visible in the RHAMT Perspective, you can open it by selecting Window → Show View → Issue Explorer.

RHAMT Server

The RHAMT server is a separate process that executes the RHAMT analysis, flags the migration issues, and generates the reports.

You can start, stop, and view the status of the RHAMT server from the Issue Explorer.

Issue Details

This view shows detailed information about the selected RHAMT issue, including the hint, severity, and any additional resources.

If this view is not visible in the RHAMT Perspective, you can open it by selecting Window → Show View → Issue Details.

RHAMT Report

This view shows the HTML reports that are generated when RHAMT is executed. From the report landing page you can navigate to detailed reports, such as Application Details, Issues, and Dependencies.

Note that the RHAMT run configuration used must have the Generate Report option selected in order for the RHAMT reports to be generated.

If this view is not visible in the RHAMT Perspective, you can open it by selecting Window → Show View → RHAMT Report.

Chapter 4. Identify and Resolve Migration Issues

Follow these steps to use the Eclipse plugin to identify and resolve migration issues.

  1. Import the project to analyze into Eclipse.

  2. Create a run configuration. From the Issue Explorer, press the RHAMT button ( RHAMT button ).

    Select RHAMT button

    At a minimum, select the project to analyze. Set additional options as needed.

  3. Click Run to execute RHAMT.
  4. Review RHAMT issues listed in the Issue Explorer.
  5. Resolve RHAMT issues by manually updating code or by using quick fixes when available.
  6. Run RHAMT again as necessary. Use the drop down next to the Run button ( Run button ) to run an existing configuration.

4.1. Create an RHAMT Run Configuration

RHAMT run configurations can be created using the RHAMT button ( RHAMT 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 RHAMT 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 RHAMT 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 RHAMT HTML report. The report will be shown in the RHAMT Report tab and can be found in the Issue Explorer when you group by File.
Options
Set additional RHAMT options. Any option that is a boolean flag, such as enableTattletale, should use true as the value. See the RHAMT Command-line Arguments section of the CLI Guide for a description of each RHAMT argument.
Rules
Custom Rules Repositories
Select custom rulesets to include during analysis if you have imported or created any custom RHAMT rules in the Eclipse plugin. See Add Custom Rules for more information.

4.2. Execute RHAMT

Once a run configuration has been created, you can execute RHAMT 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 ( Run button ).

If the RHAMT server is not currently running, it will start once a run configuration is executed.

Note

If you do not plan on running RHAMT in the near future, it is recommended to stop the RHAMT server to conserve memory on your machine.

Once execution is complete, the Issue Explorer will be populated with RHAMT issues.

4.3. Review RHAMT Issues

Use the Issue Explorer to review migration issues identified by RHAMT. 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.

Issue Explorer group by options

Double-click the RHAMT 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 RHAMT issue, including its severity and how to address it.

4.4. Resolve RHAMT Issues

You can resolve RHAMT issues by updating the code manually or by applying a quick fix when available.

4.4.1. Resolve an Issue Manually

Review the RHAMT issue details and additional resources and update the source code as necessary. When you update a line of code marked as an RHAMT issue, the RHAMT issue will be marked with the stale icon ( Stale issue icon ) until the next time that RHAMT is run on the project.

You can also manually mark an RHAMT issue as fixed, which will mark the issue with the resolved icon ( Resolved issue icon ) until the next time that RHAMT is run on the project. To mark an issue as fixed, right-click the RHAMT issue in the Issue Explorer and select Mark as Fixed.

4.4.2. Resolve an Issue Using a Quick Fix

Some RHAMT 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 RHAMT 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 RHAMT 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.

  1. From the RHAMT perspective, open the Rulesets tab.

  2. Expand the System item to view core system rules, or expand the Custom item to view custom rules.

    Note

    In order to view system rules, the RHAMT server must be started.

  3. Expand the ruleset containing the rule you want to review.
  4. 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.

  1. From the RHAMT perspective, open the Rulesets tab.
  2. Click the import ruleset icon ( Import ruleset icon ).

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

    Note

    The XML rule file must use the .windup.xml or .rhamt.xml extension in order to be recognized as an RHAMT rule.

  4. 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.

  1. From the RHAMT perspective, open the Rulesets tab.
  2. Click the create ruleset icon ( Create ruleset icon ).
  3. Select the project and directory to save the new ruleset in.

  4. Enter the file name for the ruleset file.

    Note

    The XML rule file must use the .windup.xml or .rhamt.xml extension in order to be recognized as an RHAMT rule.

  5. Enter a ruleset ID, for example, my-ruleset-id.
  6. Optionally, check the Generate quickstart template checkbox to add basic rule templates to the ruleset file.
  7. Select Finish.
  8. 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.

Appendix A. Reference Material

A.1. RHAMT Issue Icon Legend

In the Issue Explorer and file editors, RHAMT issues use an icon to indicate their severity level and status. The following table describes the meaning of the various icons.

Table A.1. RHAMT Issue Icons
IconDescription
Mandatory

The issue is mandatory to fix for a successful migration.

Optional

The issue is optional to fix for migration.

Warning

The issue may potentially be an issue during migration.

Resolved

The issue has been resolved.

Stale

The issue is stale because the code marked as an issue has been modified since the last time that RHAMT was run on the project.

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.





Revised on 2018-04-04 12:21:15 EDT

 

Legal Notice

Copyright © 2018 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, 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 Software Collections 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.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.