Red Hat Training

A Red Hat training course is available for Red Hat Application Migration Toolkit

Chapter 2. Getting Started

2.1. Prerequisites

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

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.2.1.Final</version>
    <executions>
        <execution>
            <id>run-windup</id>
            <phase>package</phase>
            <goals>
                <goal>windup</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <offlineMode>true</offlineMode>
    </configuration>
</plugin>
[...]

    • offlineMode: Indicates to run in offline mode, disabling network features to improve performance.

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

  2. If using Java 11, then --add-modules=java.se must be added to the MAVEN_OPTS environment variable. When using older versions of Java this is not necessary, and you can proceed to the next step. 

    export MAVEN_OPTS=--add-modules=java.se
    Important

    Using the Maven plugin on Java 11 is provided as Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

    See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

  3. Build the project. 

    $ mvn clean install
  4. Access the generated reports.

2.3. Run the Maven Plugin with Multiple Modules

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.2.1.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>
    </configuration>
</plugin>

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

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

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

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.