CLI Guide

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

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.

The CLI is a command-line tool in the Migration Toolkit for Applications that allows users to assess and prioritize migration and modernization efforts for applications. It provides numerous reports that highlight the analysis without the overhead of the other tools. The CLI includes a wide array of customization options, and allows you to finely tune the MTA analysis options or integrate with external automation tools.

Before installing the CLI, verify that you meet the following prerequisites.

The extracted directory is known as RHAMT_HOME in this guide.

Use the following steps to run MTA against your application.

See MTA Command Examples below for examples of commands that use source code directories and archives located in the MTA GitHub repository.

MTA Command Examples

Running MTA on an Application Archive

The following command analyzes the com.acme and org.apache packages of the jee-example-app-1.0.0.ear example EAR archive for migrating from JBoss EAP 5 to JBoss EAP 7.

$ RHAMT_HOME/bin/rhamt-cli --input /path/to/jee-example-app-1.0.0.ear --output /path/to/report-output/ --source eap:5 --target eap:7 --packages com.acme org.apache

Running MTA on Source Code

The following command analyzes the org.jboss.seam packages of the seam-booking-5.2 example source code for migrating to JBoss EAP 6.

$ RHAMT_HOME/bin/rhamt-cli --sourceMode --input /path/to/seam-booking-5.2/ --output /path/to/report-output/ --target eap:6 --packages org.jboss.seam

Running Cloud-readiness Rules

The following command analyzes the com.acme and org.apache packages of the jee-example-app-1.0.0.ear example EAR archive for migrating to JBoss EAP 7. It also evaluates for cloud readiness.

$ RHAMT_HOME/bin/rhamt-cli --input /path/to/jee-example-app-1.0.0.ear --output /path/to/report-output/ --target eap:7 --target cloud-readiness --packages com.acme org.apache

Override MTA Properties

To override the default Fernflower decompiler, pass the -Dwindup.decompiler argument on the command line. For example, to use the Procyon decompiler, use the following syntax:

$ RHAMT_HOME/bin/rhamt-cli -Dwindup.decompiler=procyon --input INPUT_ARCHIVE_OR_DIRECTORY --output OUTPUT_REPORT_DIRECTORY --target TARGET_TECHNOLOGY --packages PACKAGE_1 PACKAGE_2

MTA CLI Bash Completion

The MTA CLI provides an option to enable bash completion for Linux systems, allowing the MTA command-line arguments to be auto completed by pressing Tab when entering the commands. For instance, when bash completion is enabled, entering the following displays a list of available arguments.

$ RHAMT_HOME/bin/rhamt-cli [TAB]

Enable Bash Completion

To enable bash completion for the current shell, execute the following command. After the prompt returns, follow the steps in Run the CLI.

$ source RHAMT_HOME/bash-completion/rhamt-cli

Enable Persistent Bash Completion

The following commands allow bash completion to persist across restarts; however, if bash completion is desired for the current shell then the steps in Enable Bash Completion must be followed.

MTA Help

To see the complete list of available arguments for the rhamt-cli command, open a terminal, navigate to the RHAMT_HOME directory, and execute the following command:

$ RHAMT_HOME/bin/rhamt-cli --help

When you execute Migration Toolkit for Applications, the report is generated in the OUTPUT_REPORT_DIRECTORY that you specify using the --output argument in the command line. Upon completion of execution, you will see the following message in the terminal with the location of the report.

Report created: OUTPUT_REPORT_DIRECTORY/index.html
              Access it at this URL: file:///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
├── archives/           // Archives extracted from the application
├── mavenized/          // Optional Maven project structure
├── reports/            // Generated HTML reports
├── stats/              // Performance statistics

Use a browser to open the index.html file located in the report output directory. See Review the Reports for information on navigating the MTA reports.

Access this report from the report landing page by clicking the Technologies link.

This report provides an aggregate listing of the technologies used, grouped by function, for the analyzed applications. It shows how the technologies are distributed, and is typically reviewed after analyzing a large number of applications to group the applications and identify patterns. It also shows the size, number of libraries, and story point totals of each application.

Clicking any of the headers, such as Markup, sorts the results in descending order. Selecting the same header again will resort the results in ascending order. The currently selected header is identified in bold, next to a directional arrow, indicating the direction of the sort.

Figure 3.11. Technologies Used Across Multiple Applications

Access this report from the report landing page by clicking the Dependencies Graph link.

It includes a list of all WARs and JARs, and graphs the relations between each of the included files. Each circle in the graph represents a unique dependency defined in the application. If a file is included as a dependency in multiple applications, these are linked in the graph.

In the below image we can see two distinct groups. On the left half we see a single WAR that defines several JARs as dependencies. On the right half we see the same dependencies used by multiple WARs, one of which is the seelcted overlord-commons-auth-2.0.11.Final.jar.

Figure 3.12. Dependency Graph Across Multiple Applications

The dependency graph may be adjusted by using any of the following.

Access these reports from the report landing page by clicking the Archives shared by multiple applications link. Note that this link is only available if there are applicable shared archives.

Figure 3.13. Archives Shared by Multiple Applications

This allows you to view the detailed reports for all archives that are shared across multiple applications.

Access this report from the report landing page by clicking the Rule providers execution overview link.

This report provides the list of rules that executed when running the MTA migration command against the application.

Figure 3.14. Rule Provider Execution Overview

Access this report from the report landing page by clicking the Migration Toolkit for Applications FreeMarker methods link.

This report lists all the registered functions and directives that were used to build the report. It is useful for debugging purposes or if you plan to build your own custom report.

Figure 3.15. FreeMarker Functions and Directives

Access this feedback form from the report landing page by clicking the Send feedback link.

This form allows you to rate the product, talk about what you like, and make suggestions for improvements.

Figure 3.16. Send Feedback Form

To export the report into a CSV file, run MTA with --exportCSV argument. A CSV file will be created in the directory specified by the --output argument for each application analyzed. All discovered issues, spanning all the analyzed applications, will be included in AllIssues.csv found in the root directory of the report.

Access the Report from the Application Report

If the CSV report is exported, then all of the CSV issues are available for download in the Issues Report. These issues may be downloaded by selecting the Download All Issues CSV button in the top-right section of the issues report, as seen in the following image.

Figure 4.1. Issues Report with CSV Download

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

The CSV formatted output file contains the following data fields:

You can generate a Maven project structure for the provided application by passing in the --mavenize flag when executing MTA.

The following example runs MTA using the jee-example-app-1.0.0.ear test application.

$ RHAMT_HOME/bin/rhamt-cli --input /path/to/jee-example-app-1.0.0.ear --output /path/to/output --target eap:6 --packages com.acme org.apache --mavenize

This generates the Maven project structure in the /path/to/output/mavenized directory.

You can also use the --mavenizeGroupId option to specify the <groupId> to be used for the POM files. If unspecified, MTA will attempt to identify an appropriate <groupId> for the application, or will default to com.mycompany.mavenized.

The /path/to/output/mavenized/APPLICATION_NAME/ directory will contain the following items:

The example jee-example-app-1.0.0.ear application is an EAR archive that contains a WAR and several JARs. There is a separate directory created for each of these artifacts. Below is the Maven project structure created for this application.

/path/to/output/mavenized/jee-example-app/
    jee-example-app-bom/pom.xml
    jee-example-app-ear/pom.xml
    jee-example-services2-jar/pom.xml
    jee-example-services-jar/pom.xml
    jee-example-web-war/pom.xml
    pom.xml

Review each of the generated files and customize as appropriate for your project. To learn more about Maven POM files, see the Introduction to the POM section of the Apache Maven documentation.

Root POM File

The root POM file for the jee-example-app-1.0.0.ear application can be found at /path/to/output/mavenized/jee-example-app/pom.xml. This file identifies the directories for all of the project modules.

The following modules are listed in the root POM for the example jee-example-app-1.0.0.ear application.

<modules>
  <module>jee-example-app-bom</module>
  <module>jee-example-services2-jar</module>
  <module>jee-example-services-jar</module>
  <module>jee-example-web-war</module>
  <module>jee-example-app-ear</module>
</modules>

The root POM is also configured to use the Red Hat JBoss Enterprise Application Platform Maven repository to download project dependencies.

BOM File

The Bill of Materials (BOM) file is generated in the directory ending in -bom. For the example jee-example-app-1.0.0.ear application, the BOM file can be found at /path/to/output/mavenized/jee-example-app/jee-example-app-bom/pom.xml. The purpose of this BOM is to have the versions of third-party dependencies used by the project defined in one place. For more information on using a BOM, see the Introduction to the Dependency Mechanism section of the Apache Maven documentation.

The following dependencies are listed in the BOM for the example jee-example-app-1.0.0.ear application

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>log4j</groupId>
      <artifactId>log4j</artifactId>
      <version>1.2.6</version>
    </dependency>
    <dependency>
      <groupId>commons-lang</groupId>
      <artifactId>commons-lang</artifactId>
      <version>2.5</version>
    </dependency>
  </dependencies>
</dependencyManagement>

Application POM Files

Each application module that can be mavenized has a separate directory containing its POM file. The directory name contains the name of the archive and ends in a -jar, -war, or -ear suffix, depending on the archive type.

Each application POM file lists that module’s dependencies, including:

For example, the POM file for the jee-example-app-1.0.0.ear EAR, /path/to/output/mavenized/jee-example-app/jee-example-app-ear/pom.xml, lists the following dependencies.

<dependencies>
  <dependency>
    <groupId>log4j</groupId>
    <artifactId>log4j</artifactId>
    <version>1.2.6</version>
  </dependency>
  <dependency>
    <groupId>org.jboss.seam</groupId>
    <artifactId>jee-example-web-war</artifactId>
    <version>1.0</version>
    <type>war</type>
  </dependency>
  <dependency>
    <groupId>org.jboss.seam</groupId>
    <artifactId>jee-example-services-jar</artifactId>
    <version>1.0</version>
  </dependency>
  <dependency>
    <groupId>org.jboss.seam</groupId>
    <artifactId>jee-example-services2-jar</artifactId>
    <version>1.0</version>
  </dependency>
</dependencies>