Introduction to the Migration Toolkit for Applications

Migration Toolkit for Applications 5.1

Learn how to use the Migration Toolkit for Applications to migrate and modernize Java applications and components.

Red Hat Customer Content Services


This guide provides information to help you get started with the Migration Toolkit for Applications.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

Chapter 1. Introduction

1.1. About the Introduction to the Migration Toolkit for Applications

This guide is for engineers, consultants, and others who want to use the Migration Toolkit for Applications (MTA) to migrate Java applications or other components. It provides an overview of the Migration Toolkit for Applications and how to get started using the tools to plan and execute your migration.

Chapter 2. About the Migration Toolkit for Applications

What is the Migration Toolkit for Applications?

The Migration Toolkit for Applications (MTA) is an extensible and customizable rule-based tool that simplifies the migration and modernization of Java applications.

MTA examines application artifacts, including project source directories and application archives, and then produces an HTML report highlighting areas needing changes. MTA supports many migration paths including the following examples:

  • Migrating from enterprise application servers to Red Hat JBoss Enterprise Application Platform
  • Containerizing applications and making them cloud-ready
  • Migrating from Spring Boot to Quarkus
  • Updating OpenJDK versions

For more information about use cases and migration paths, see the MTA for developers web page.

How does the Migration Toolkit for Applications simplify migration?

The Migration Toolkit for Applications looks for common resources and known trouble spots when migrating applications. It provides a high-level view of the technologies used by the application.

MTA generates a detailed report evaluating a migration or modernization path. This report can help you to estimate the effort required for large-scale projects and to reduce the work involved.

2.1. MTA Features

The Migration Toolkit for Applications (MTA) provides a number of capabilities to assist with planning and executing migration projects.

Planning and work estimation
MTA assists project managers by detailing the type of work and estimation of effort to complete the tasks. Level of effort is represented in MTA reports as story points. Actual estimates will be based on the skills required and the classification of migration work needed.
Identifying migration issues and providing solutions
MTA identifies migration issues and highlights specific points in the code where an issue occurs. MTA suggests code changes and provides additional resources to help engineers resolve the specific issue.
Detailed reporting
MTA produces numerous reports to give both high-level views of the migration effort and details of specific migration tasks. You can view migration issues across all applications, charts and summary information about issues in an application, a breakdown of issues by module in the application, reports of technologies used, and dependencies on other applications and services. You can also examine source files to see the line of code where an issue occurs. See the CLI Guide for more information on the available MTA reports.
Built-in rules and migration paths
MTA comes with a core set of rules to provide migration assistance for several common migration paths. These rules identify the use of proprietary functionality from other application servers or deprecated subsystems from previous versions of JBoss EAP. MTA also contains rules to identify common migration issues, such as hard-coded IP addresses and JNDI lookups.
Rule extensibility and customization
MTA provides the ability to create powerful and complex rules. You can expand upon the core set of rules provided by MTA and create rules to identify additional issues that are important for your migration project. You can also override core rules and create custom rule categories. See the Rules Development Guide for more information on customizing MTA rules.
Ability to analyze source code or application archives
MTA can evaluate application archives or source code, and can evaluate multiple applications together. It can identify archives that are shared across multiple applications, which can help with more accurate effort estimation.

2.2. About MTA rules

The Migration Toolkit for Applications (MTA) contains rule-based migration tools that analyze the APIs, technologies, and architectures used by the applications you plan to migrate. In fact, the MTA analysis process is implemented using MTA rules. MTA uses rules internally to extract files from archives, decompile files, scan and classify file types, analyze XML and other file content, analyze the application code, and build the reports.

MTA builds a data model based on the rule execution results and stores component data and relationships in a graph database, which can then be queried and updated as needed by the migration rules and for reporting purposes.

MTA rules use the following rule pattern:


MTA provides a comprehensive set of standard migration rules out-of-the-box. Because applications may contain custom libraries or components, MTA allows you to write your own rules to identify use of components or software that may not be covered by the existing ruleset.

If you plan to write your own custom rules, see the Rules Development Guide for detailed instructions.

Chapter 3. Supported configurations

3.1. Supported migration paths

The Migration Toolkit for Applications (MTA) supports migrations from third-party enterprise application servers, such as Oracle WebLogic Server, to JBoss Enterprise Application Platform (JBoss EAP) and upgrades to the latest release of JBoss EAP.

MTA provides a comprehensive set of rules to assess the suitability of your applications for containerization and deployment on Red Hat OpenShift Container Platform (RHOCP). You can run an MTA analysis to assess your applications' suitability for migration to multiple target platforms.

The following table describes the most common supported migration paths.

Table 3.1. Supported migration paths: Source platform ⇒ target

Source platform ⇒JBoss EAP 6JBoss EAP 7RHOCPOpenJDK 8 & 11Apache Camel 3Spring Boot on Red Hat RuntimesQuarkus

Oracle WebLogic Server




IBM WebSphere Application Server




JBoss EAP 4





JBoss EAP 5




JBoss EAP 6





JBoss EAP 7





Oracle JDK






Apache Camel 2





Spring Boot




Java application






[a] Although MTA does not currently provide rules for this migration path, Red Hat Consulting can assist with migration from any source platform to JBoss EAP 7.

3.2. System requirements

3.2.1. Software

  • OpenJDK 1.8, OpenJDK 11, Oracle JDK 1.8, Oracle JDK 11
  • MTA is tested on Linux, Windows, and macOS. Other operating systems with Java 8+ support should work equally well.

3.2.2. Hardware

The following memory and disk space requirements are the minimum needed to run MTA. If your application is very large or you need to evaluate multiple applications, you may want to increase these values to improve performance.

For tips on how to optimize performance, see the Optimizing MTA performance section of the MTA CLI Guide.

  • A minimum of 4 GB RAM. For better performance, a quad-core processor with 8 GB RAM is recommended. This allows 3 - 4 GB RAM for use by the JVM.
  • A minimum of 4 GB of free disk space. A fast disk, especially a solid-state drive (SSD), should improve performance.

Chapter 4. About the tools

The Migration Toolkit for Applications (MTA) provides several tools to assist you in the various stages of your migration and modernization efforts. Review the details of each tool to determine which is right for your project.

4.1. About the CLI

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 MTA analysis options or integrate with external automation tools.

For more information on using the CLI, see the MTA CLI Guide.

4.2. About the web console

The web console for the Migration Toolkit for Applications allows a team of users to assess and prioritize migration and modernization efforts for a large number of applications. It allows you to group applications into projects for analysis and provides numerous reports that highlight the results.

For more information on using the web console, see the MTA Web Console Guide.

4.3. About the MTA plugin

The MTA plugin for the Migration Toolkit for Applications provides assistance directly in Eclipse and Red Hat CodeReady 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.

4.4. About the Maven Plugin

The Maven plugin for the Migration Toolkit for Applications 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.

For more information on using the Maven plugin, see the MTA Maven Plugin Guide.

Chapter 5. Planning your application migration

5.1. Goals of assessing a migration

Many organizations are faced with the challenges of keeping their existing business operations running, while also trying to innovate. There are typically increased expectations to deliver new functionality faster and to reduce cost.

When assessing a migration or modernization effort, it is important to address the challenges that are specific to your organization. Common challenges that organizations face are limited budgets, lack of in-house skills, perceived risks, no known predictable process, and accurate effort estimation in a timely manner.

In general, the goals when assessing a large-scale middleware migration or modernization effort are the following:

  • Predicting the level of effort and cost
  • Scheduling application migrations and handling conflicts
  • Identifying all potential risks at a code, infrastructure, process, or knowledge level
  • Predicting the return on investment to make the business case
  • Identifying and mitigating risks to the business
  • Minimizing disruption to existing business operations

Red Hat has developed a strategy to minimize risk and make application migration and modernizations more efficient.

5.2. Red Hat’s application migration approach

Red Hat has defined a strategy to make large-scale application migrations to Red Hat JBoss Middleware quantifiable, less costly, less risky, and easier to complete.

Migrating from proprietary or outdated middleware platforms to Red Hat JBoss Middleware gives you lightweight, modular, and cloud-ready middleware with a supporting application infrastructure to make teams more productive. JBoss Middleware and other Red Hat technologies also provide great opportunities to modernize your application development and delivery, allowing you to innovate more quickly.

5.2.1. Best practices

Red Hat recommends the following practices when planning and executing a migration or modernization:

  • Create a centralized collaboration platform for information sharing.

    Comprehensive and accessible documentation is important so that knowledge can be easily shared and to ensure that effort is not duplicated by solving the same issue twice. It is recommended to document the following items:

    • A step-by-step guide for migrating or modernizing an application from scratch.
    • A collection of solutions to known and encountered issues.
    • Information about the new platform.
    • A record of the changes made to specific pilot projects.
  • Reuse, automate, and standardize as much as possible.

    Consider reusing existing components instead of creating new ones. Automate processes related to the application lifecycle, such as builds, configuration, deployment, and tests. Standardize and document software packaging format, configuration management, libraries, and dependencies.

  • Use a proven and repeatable methodology.

    The recommendation is to follow a practical approach and make as few changes as possible to get a functionally identical application.

  • Involve Red Hat technical expertise early for the chosen Red Hat Middleware components.

    This is crucial to make your migrations and modernizations low risk, predictable, and efficient. Contact Red Hat Consulting for assistance.

5.2.2. Methodology

Red Hat’s recommended methodology is a proven, scalable approach that helps you to incrementally plan and conduct a migration or modernization.

Figure 5.1. Red Hat migration methodology

Red Hat migration methodology

The approach consists of the following phases:

Explore the technologies and identify concerns, organization requirements and challenges. Discuss options and potential approaches.
Identify and mitigate the biggest risks from an application, infrastructure, process, and knowledge perspective. Establish a strategy for the solution. Prove the technology and build the business case.
Scale the modernization or migration iteratively by executing the previously defined strategy according to a well-defined delivery model. Discover phase

Figure 5.2. Red Hat migration methodology: Discover phase

Red Hat Migration Methodology: Discover

The Discover phase is when you gather all stakeholders and decision-makers together to understand the current state and business drivers, and to determine the migration or modernization needs.

In this phase, you explore technologies and discuss potential approaches. Identify the existing pain points, concerns, requirements, and some potential challenges. Define the high-level business priorities and scope the assessment. Determine in what ways you want to modernize your application development and delivery to allow you to innovate more rapidly.

Typically, this can be covered in a day in a workshop with Red Hat experts. Design phase

Figure 5.3. Red Hat migration methodology: Design phase

Red Hat migration methodology: Design

The Design phase is when you identify all risks, define a strategy and target architecture, prove the technology, and build the business case. This phase consists of the following steps:


Examine the existing infrastructure, architecture, technologies, and applications. Identify dependencies, knowledge, processes, and lifecycles. Define the desired infrastructure, architecture, technologies, and applications. Determine the feasibility and potential risks. Draft a plan and provide rough estimates.

Analyzing applications using the Migration Toolkit for Applications web console or CLI helps to determine dependencies, potential risks, and relative effort. See the Web Console Guide or CLI Guide for information on how to use these tools.

Solve and document the identified technical risks, for example, high risk items and issues with unknown effort. Build and shape the new platform infrastructure. Refine the estimates based on the outcomes.

Choose a small set of representative applications to transform. Finalize the target platform infrastructure as necessary. Update the documentation as the process is fine-tuned. This pilot consists of one or several iterations of the migration execution, which is scaled during the Deploy phase.

Use the Migration Toolkit for Applications MTA plugin to accelerate the code migration. See the Eclipse and Red Hat CodeReady Studio Plugin Guide for information on how to use the MTA plugin.

Based on the outcomes of the previous steps, sharpen the estimates and refine the project plan. Define the rollout strategy to be used in the Deploy phase to complete the migration. Prepare and schedule the relevant technical enablement courses. Deploy phase

Figure 5.4. Red Hat migration methodology: Deploy phase

Red Hat migration methodology: Deploy

The Deploy phase is when you execute the plan created in the Design phase. In this phase, you scale the overall transformation process to complete the plan and bring all applications to their new production environment.

The plan is executed in iterations to deliver value incrementally. With each iteration, you continuously validate against the plan and document findings to improve the next sprint.

The use of the Migration Toolkit for Applications MTA plugin increases speed in each iteration. It can be used with Eclipse or Red Hat CodeReady Studio, and marks migration issues directly in the source code, provides inline hints, and offers code change suggestions. See the Eclipse and Red Hat CodeReady Studio Plugin Guide for information on how to use the MTA plugin.

Appendix A. Reference material

A.1. Additional resources

A.1.1. Getting involved

To help the Migration Toolkit for Applications cover most application constructs and server configurations, including yours, you can help with any of the following items.

  • Send an email to and let us know what MTA 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 Migration Toolkit for Applications on your application. Be sure to report any issues you encounter.
  • Contribute to the Migration Toolkit for Applications rules repository.

    • Write a Migration Toolkit for Applications 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 MTA 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.1.3. Reporting issues

MTA uses Jira as its issue tracking system. If you encounter an issue executing MTA, submit a Jira issue.

Revised on 2021-08-02 12:17:10 UTC

Legal Notice

Copyright © 2021 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 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, the Red Hat 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 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.