Red Hat Summit Red Hat SummitSupportKonsoleEntwicklerDemo startenKontakt

Dieser Inhalt ist in der von Ihnen ausgewählten Sprache nicht verfügbar.

Maven Plugin Guide

Red Hat Application Migration Toolkit 4.1

Integrate the Red Hat Application Migration Toolkit into the Maven build process.

Red Hat Customer Content Services

Abstract

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

Chapter 1. Introduction
Link kopieren

1.1. About the Maven Plugin Guide
Link kopieren

This guide is for engineers, consultants, and others who want to use Red Hat Application Migration Toolkit (RHAMT) to migrate Java applications or other components. It describes how to install and run the Maven plugin, review the generated reports, and take advantage of additional features.

1.2. About Red Hat Application Migration Toolkit
Link kopieren

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 Maven Plugin
Link kopieren

The Maven plugin for Red Hat Application Migration Toolkit integrates into the Maven build process, allowing developers to continuously evaluate migration and modernization efforts with each iteration of source code. It provides numerous reports that highlight the analysis results, and is designed for developers who want updates with each build.

Chapter 2. Getting Started
Link kopieren

2.1. Prerequisites
Link kopieren

Before using the Maven plugin, verify that you meet the following prerequisites.

  • Java Platform, JRE version 8+
  • A minimum of 4 GB RAM; 8 GB recommended
  • Maven version 3.2.5 or later
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.

2.2. Run the Maven Plugin
Link kopieren

The Maven plugin is executed by including a reference to the plugin inside your application’s pom.xml. When the application is built, the Maven plugin is executed and generates the reports for analysis.

To run the Maven plugin perform the following steps.

  1. Include the following plugin inside your application’s pom.xml: 

    [...]
<plugin>
    <groupId>org.jboss.windup.plugin</groupId>
    <artifactId>windup-maven-plugin</artifactId>
    <version>4.1.0.Final</version>
    <executions>
        <execution>
            <id>run-windup</id>
            <phase>package</phase>
            <goals>
                <goal>windup</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <offlineMode>true</offlineMode>
        <windupVersion>4.1.0.Final</windupVersion>
    </configuration>
</plugin>
[...]
    Copy to Clipboard Toggle word wrap
    • offlineMode: Indicates to run in offline mode, disabling network features to improve performance.

    • windupVersion: Version of RHAMT.

      The above example demonstrates the minimum required arguments. See RHAMT Maven Arguments for a detailed description of all available arguments.

  2. Build the project. 

    $ mvn clean install
    Copy to Clipboard Toggle word wrap
  3. Access the generated reports.

2.3. Run the Maven Plugin with Multiple Modules
Link kopieren

To use the Maven plugin in a project with multiple modules, place the configuration inside the parent’s pom.xml. During execution the Maven plugin will generate a single report that contains the analysis for the parent and any child modules.

Note

It is strongly recommended to set inherited to false in multi-module projects; otherwise, the Maven plugin will be executed when each child is compiled, resulting in multiple executions of the Maven plugin against the child modules. Setting inherited to false results in each project being analyzed a single time and drastically decreased run times.

To run the Maven plugin in a project with multiple modules perform the following steps.

  1. Include the following plugin inside the parent project’s pom.xml. The following is a sample pom.xml for a parent module. 

    <plugin>
    <groupId>org.jboss.windup.plugin</groupId>
    <artifactId>windup-maven-plugin</artifactId>
    <version>4.1.0.Final</version>
    <inherited>false</inherited>
    <executions>
        <execution>
            <id>run-windup</id>
            <phase>package</phase>
            <goals>
                <goal>windup</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <input>${project.basedir}</input>
        <offlineMode>true</offlineMode>
        <windupHome>/PATH/TO/CLI/</windupHome>
        <windupVersion>4.1.0.Final</windupVersion>
    </configuration>
</plugin>
    Copy to Clipboard Toggle word wrap

    This pom.xml deviates from the one in Run the Maven Plugin by the following attributes:

    • inherited: Defined at the plugin level, this attribute indicates whether or not this configuration should be used in child modules. Set to false for performance improvements.
    • input: Specifies the path to the directory containing the projects to be analyzed. This attribute defaults to {project.basedir}/src/main, and should be defined if the parent project does not have source code to analyze.

    • windupHome: A path to an extracted copy of the RHAMT CLI. This attribute is optional, but is recommended as a performance improvement.

      The above example demonstrates a set of recommended arguments. See RHAMT Maven Arguments for a detailed description of all available arguments.

  2. Build the parent project. During the build process the Maven plugin will execute against all children in the project without further configuration. 

    $ mvn clean install
    Copy to Clipboard Toggle word wrap
  3. Once completed, Access the generated reports as normal. This report contains the analysis for the parent and all children.

2.4. Access the Report
Link kopieren

When you execute Red Hat Application Migration Toolkit, the report is generated in the OUTPUT_REPORT_DIRECTORY that you specify using the outputDirectory argument in the pom.xml. Upon completion of the build, you will see the following message in the build log. 

Windup report created: OUTPUT_REPORT_DIRECTORY/index.html
Copy to Clipboard Toggle word wrap

The output directory contains the following files and subdirectories: 

OUTPUT_REPORT_DIRECTORY/
├── index.html          // Landing page for the report
├── EXPORT_FILE.csv     // Optional export of data in CSV format
├── graph/              // Generated graphs used for indexing
├── reports/            // Generated HTML reports
├── stats/              // Performance statistics
Copy to Clipboard Toggle word wrap

See the Review the Reports section of the RHAMT CLI Guide for information on the RHAMT reports and how to use them to assess your migration or modernization effort.

Chapter 3. Export the Report in CSV Format
Link kopieren

RHAMT provides the ability to export the report data, including the classifications and hints, to a flat file on your local file system. The export function currently supports the CSV file format, which presents the report data as fields separated by commas (,).

The CSV file can be imported and manipulated by spreadsheet software such as Microsoft Excel, OpenOffice Calc, or LibreOffice Calc. Spreadsheet software provides the ability to sort, analyze, evaluate, and manage the result data from an RHAMT report.

3.1. Export the Report
Link kopieren

To export the report into a CSV file, run RHAMT with exportCSV argument set to true. 

<exportCSV>true</exportCSV>
Copy to Clipboard Toggle word wrap

The CSV file will be created in the directory specified by the outputDirectory argument.

3.2. Import the CSV File into a Spreadsheet Program
Link kopieren

  1. Launch the spreadsheet software, for example, Microsoft Excel.
  2. Choose File → Open.
  3. Browse to the CSV exported file and select it.
  4. The data is now ready to analyze in the spreadsheet software.

For more information or to resolve any issues, check the help for your spreadsheet software.

3.3. Overview of the CSV Data Structure
Link kopieren

The CSV formatted output file contains the following data fields:

Rule Id
The ID of the rule that generated the given item.
Problem type
hint or classification
Title
The title of the classification or hint. This field summarizes the issue for the given item.
Description
The detailed description of the issue for the given item.
Links
URLs that provide additional information about the issue. A link consists of two attributes: the link and a description of the link.
Application
The name of the application for which this item was generated.
File Name
The name of the file for the given item.
File Path
The file path for the given item.
Line
The line number of the file for the given item.
Story points
The number of story points, which represent the level of effort, assigned to the given item.

Appendix A. Reference Material
Link kopieren

A.1. Maven plugin Arguments
Link kopieren

The following is a detailed description of the available RHAMT Maven plugin arguments.

Expand
Table A.1. RHAMT Maven plugin Arguments
ArgumentDescription

enableCompatibleFilesReport

Flag to enable generation of the Compatible Files report. Due to processing all files without found issues, this report may take a long time for large applications.

enableTattletale

Flag to enable generate a Tattletale report for each application.

excludePackages

A list of packages to exclude from evaluation. For example, entering "com.mycompany.commonutilities" would exclude all classes whose package name begins with "com.mycompany.commonutilities".

excludeTags

A list of tags to exclude. When specified, rules with these tags will not be processed.

explodedApps

Flag to indicate that the provided input directory contains source files for a single application. See the Input File Argument Tables for details.

exportCSV

Flag to export the report data to a CSV file on your local file system. RHAMT creates the file in the directory specified by the outputDirectory argument. The CSV file can be imported into a spreadsheet program for data manipulation and analysis. For details, see Export the Report in CSV Format.

includeTags

A list of tags to use. When specified, only rules with these tags will be processed.

inputDirectory

Specify the path to the directory containing the applications to be analyzed. This argument defaults to {project.basedir}/src/main/. See Specify the Input Directory for more information.

keepWorkDirs

Flag to instruct RHAMT to not delete temporary working files, such as the graph database and unzipped archives. This is useful for debugging purposes.

packages

A list of the packages to be evaluated by RHAMT. This argument is required. See Select Packages for more information.

offlineMode

Flag to operate in offline mode, disabling network access features, such as scheme validation. Used to improve performance.

outputDirectory

Specify the path to the directory to output the report information generated by RHAMT. This argument defaults to {project.build.directory}/windup-report. See Specify the Output Directory for more information.

overwrite

Flag to force delete the existing output directory specified by outputDirectory. Defaults to true.

Warning

Be careful not to specify a report output directory that contains important information!

sourceTechnologies

A list of one or more source technologies, servers, platforms, or frameworks to migrate from. This argument, in conjunction with the targetTechnologies argument, helps to determine which rulesets are used. See Set the Source Technology for more information.

sourceMode

Flag to indicate that the application to be evaluated contains source files rather than compiled binaries. Defaults to true. See the Input File Argument Tables for details.

targetTechnologies

A list of one or more target technologies, servers, platforms, or frameworks to migrate to. This argument, in conjunction with the sourceTechnologies argument, helps to determine which rulesets are used. See Set the Target Technology for more information.

userIgnorePath

Specify a location for RHAMT to identify files that should be ignored.

userRulesDirectory

Specify a location for RHAMT to look for custom RHAMT rules. The value can be a directory containing ruleset files or a single ruleset file. The ruleset files must use the .windup.xml or .rhamt.xml suffix.

windupHome

An optional argument that points to the root of an extracted RHAMT CLI. By referencing a local installation of the CLI, the Maven plugin has direct access to all of the indexes, resulting in a performance increase.

windupVersion

Specify the version of RHAMT.

A.1.1. Specify the Input Directory
Link kopieren

A path to the file or directory containing one or more applications to be analyzed. This defaults to {project.basedir}/src/main/.

Usage

<inputDirectory>INPUT_ARCHIVE_OR_DIRECTORY</inputDirectory>
Copy to Clipboard Toggle word wrap

Depending on whether the input file type provided to the inputDirectory argument is a file or directory, it will be evaluated as follows depending on the additional arguments provided.

Directory
Expand
--explodedApp--sourceModeNeither Argument

The directory is evaluated as a single application.

The directory is evaluated as a single application.

Each subdirectory is evaluated as an application.

File
Expand
--explodedApp--sourceModeNeither Argument

Argument is ignored; the file is evaluated as a single application.

The file is evaluated as a compressed project.

The file is evaluated as a single application.

A.1.2. Specify the Output Directory
Link kopieren

Specify the path to the directory to output the report information generated by RHAMT.

Usage

<outputDirectory>OUTPUT_REPORT_DIRECTORY</outputDirectory>
Copy to Clipboard Toggle word wrap

  • If omitted, the report will be generated in the {project.build.directory}/windup-report directory.
  • If the output directory exists, it will be overwritten based on the value of the overwrite argument. This argument defaults to true, and causes RHAMT to delete and recreate the directory.

A.1.3. Set the Source Technology
Link kopieren

A list of one or more source technologies, servers, platforms, or frameworks to migrate from. This argument, in conjunction with the targetTechnologies argument, helps to determine which rulesets are used.

Usage

<sourceTechnologies>
    <source>eap:6</source>
</sourceTechnologies>
Copy to Clipboard Toggle word wrap

The sourceTechnologies argument now provides version support, which follows the Maven version range syntax. This instructs RHAMT to only run the rulesets matching the specified versions. For example, <source>eap:5</source>.

A.1.4. Set the Target Argument
Link kopieren

A list of one or more target technologies, servers, platforms, or frameworks to migrate to. This argument, in conjunction with the sourceTechnologies argument, helps to determine which rulesets are used. This argument is required

Usage

<targetTechnologies>
  <target>eap:7</target>
</targetTechnologies>
Copy to Clipboard Toggle word wrap

The targetTechnologies argument now provides version support, which follows the Maven version range syntax. This instructs RHAMT to only run the rulesets matching the specified versions. For example, <target>eap:7</target>.

Warning

When migrating to JBoss EAP, be sure to specify the version in the target, for example, eap:6. Specifying only eap will run rulesets for all versions of JBoss EAP, including those not relevant to your migration path.

See Supported Migration Paths in the RHAMT Getting Started Guide for which JBoss EAP version is appropriate for your source platform.

A.1.5. Select Packages
Link kopieren

A list of the packages to be evaluated by RHAMT. It is highly recommended to use this argument.

Usage

<packages>
  <package>PACKAGE_1</package>
  <package>PACKAGE_2</package>
</packages>
Copy to Clipboard Toggle word wrap

  • In most cases, you are interested only in evaluating custom application class packages and not standard Java EE or third party packages. The PACKAGE_N argument is a package prefix; all subpackages will be scanned. For example, to scan the packages com.mycustomapp and com.myotherapp, use the following snippet in your pom.xml. 

    <packages>
  <package>com.mycustomapp</package>
  <package>com.myotherapp</package>
</packages>
    Copy to Clipboard Toggle word wrap
  • While you can provide package names for standard Java EE third party software like org.apache, it is usually best not to include them as they should not impact the migration effort.

A.2. Rule Story Points
Link kopieren

A.2.1. What are Story Points?
Link kopieren

Story points are an abstract metric commonly used in Agile software development to estimate the level of effort needed to implement a feature or change.

Red Hat Application Migration Toolkit uses story points to express the level of effort needed to migrate particular application constructs, and the application as a whole. It does not necessarily translate to man-hours, but the value should be consistent across tasks.

A.2.2. How Story Points are Estimated in Rules
Link kopieren

Estimating the level of effort for the story points for a rule can be tricky. The following are the general guidelines RHAMT uses when estimating the level of effort required for a rule.

Expand
Level of EffortStory PointsDescription

Information

0

An informational warning with very low or no priority for migration.

Trivial

1

The migration is a trivial change or a simple library swap with no or minimal API changes.

Complex

3

The changes required for the migration task are complex, but have a documented solution.

Redesign

5

The migration task requires a redesign or a complete library change, with significant API changes.

Rearchitecture

7

The migration requires a complete rearchitecture of the component or subsystem.

Unknown

13

The migration solution is not known and may need a complete rewrite.

A.2.3. Task Severity
Link kopieren

In addition to the level of effort, you can categorize migration tasks to indicate the severity of the task. The following categories are used to indicate whether a task must be completed or can be postponed.

Mandatory
The task must be completed for a successful migration. If the changes are not made, the resulting application will not build or run successfully. Examples include replacement of proprietary APIs that are not supported in the target platform.
Optional
If the migration task is not completed, the application should work, but the results may not be the optimal. If the change is not made at the time of migration, it is recommended to put it on the schedule soon after migration is completed. An example of this would be the upgrade of EJB 2.x code to EJB 3.

For more information on categorizing tasks, see Using Custom Rule Categories in the Rules Development Guide.

A.3. Additional Resources
Link kopieren

A.3.1. Get Involved
Link kopieren

To help make Red Hat Application Migration Toolkit cover most application constructs and server configurations, including yours, you can help with any of the following items.

  • Send an email to jboss-migration-feedback@redhat.com and let us know what RHAMT migration rules should cover.
  • Provide example applications to test migration rules.

  • Identify application components and problem areas that may be difficult to migrate.

    • Write a short description of these problem migration areas.
    • Write a brief overview describing how to solve the problem migration areas.
  • Try Red Hat Application Migration Toolkit on your application. Be sure to report any issues you encounter.

  • Contribute to the Red Hat Application Migration Toolkit rules repository.

    • Write a Red Hat Application Migration Toolkit rule to identify or automate a migration process.
    • Create a test for the new rule.
    • Details are provided in the Rules Development Guide.

  • Contribute to the project source code.

    • Create a core rule.
    • Improve RHAMT performance or efficiency.
    • See the Core Development Guide for information about how to configure your environment and set up the project.

Any level of involvement is greatly appreciated!

A.3.3. Known RHAMT Issues
Link kopieren

You can review known issues for RHAMT here: Open RHAMT issues.

A.3.4. Report Issues with RHAMT
Link kopieren

Red Hat Application Migration Toolkit uses JIRA as its issue tracking system. If you encounter an issue executing RHAMT, please file a JIRA Issue.

Note

If you do not have one already, you must sign up for a JIRA account in order to create a JIRA issue.

A.3.4.1. Create a JIRA Issue
Link kopieren

  1. Open a browser and navigate to the JIRA Create Issue page.

    If you have not yet logged in, click the Log In link at the top right side of the page and enter your credentials.

  2. Choose the following options and click the Next button.

    • Project

      For core RHAMT issues, choose Red Hat Application Migration Toolkit (WINDUP).

      For issues with RHAMT rules, choose: Red Hat Application Migration Toolkit rules (WINDUPRULE).

    • Issue Type: Bug

  3. On the next screen complete the following fields.

    • Summary: Enter a brief description of the problem or issue.
    • Environment: Provide the details of your operating system, version of Java, and any other pertinent information.
    • Description: Provide a detailed description of the issue. Be sure to include logs and exceptions traces.
    • Attachment: If the application or archive causing the issue does not contain sensitive information and you are comfortable sharing it with the RHAMT development team, attach it to the issue using the browse button.
  4. Click the Create button to create the JIRA issue.

Legal Notice
Link kopieren

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.
Nach oben
Red Hat logoGithubredditYoutubeTwitter

Lernen

Testen, kaufen und verkaufen

Communitys

Über Red Hat Dokumentation

Wir helfen Red Hat Benutzern, mit unseren Produkten und Diensten innovativ zu sein und ihre Ziele zu erreichen – mit Inhalten, denen sie vertrauen können. Entdecken Sie unsere neuesten Updates.

Mehr Inklusion in Open Source

Red Hat hat sich verpflichtet, problematische Sprache in unserem Code, unserer Dokumentation und unseren Web-Eigenschaften zu ersetzen. Weitere Einzelheiten finden Sie in Red Hat Blog.

Über Red Hat

Wir liefern gehärtete Lösungen, die es Unternehmen leichter machen, plattform- und umgebungsübergreifend zu arbeiten, vom zentralen Rechenzentrum bis zum Netzwerkrand.

Theme

© 2025 Red Hat