Maven 插件指南

Migration Toolkit for Applications 6.1

将 Migration Toolkit for Applications 集成到 Maven 构建过程中。

Red Hat Customer Content Services

摘要

本指南介绍了如何在 Red Hat OpenShift 的混合云环境中使用 Migration Toolkit for Applications Maven 插件来加快大规模应用程序现代化工作。

使开源包含更多

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。我们从这四个术语开始:master、slave、黑名单和白名单。由于此项工作十分艰巨,这些更改将在即将推出的几个发行版本中逐步实施。有关更多详情,请参阅我们的首席技术官 Chris Wright 提供的消息

第 1 章 简介

1.1. 关于 Maven 插件指南

本指南适用于希望使用 Migration Toolkit for Applications (MTA) 迁移 Java 应用程序或其他组件的工程师、顾问和其他组件。它描述了如何安装和运行 Maven 插件,检查生成的报告,并利用额外的功能。

1.2. 关于 Migration Toolkit for Applications

什么是 Migration Toolkit for Applications?

Migration Toolkit for Applications (MTA) 在 Red Hat OpenShift 的混合云环境中加速大规模应用程序现代化的过程。此解决方案会考虑整个迁移过程的详细情况,包括产品组合和应用程序级别的信息:库存、评估、分析和管理应用程序,以便更快地通过用户界面迁移到 OpenShift。

MTA 使用一个非常具体的问题调查,作为评估应用程序的基础,使您能够估计准备应用进行容器化所需的难度、时间和其他资源。您可以使用评估结果作为与利益相关者进行的讨论基础,以确定哪些应用程序可以被容器化,哪些需要大量的准备工作,哪些不适用于容器化。

MTA 会根据一个或多个规则集来对应用程序进行分析,并找出应用程序的哪些部分需要进行修改才可以对其进行现代化。

MTA 检查应用程序工件,包括项目源目录和应用程序存档,然后生成 HTML 报告突出显示需要更改的区域。MTA 支持许多迁移路径,包括:

  • 升级至 Red Hat JBoss Enterprise Application Platform 的最新版本
  • 从 Oracle WebLogic 或 IBM WebSphere Application Server 迁移到 Red Hat JBoss Enterprise Application Platform
  • 容器化应用程序并使之成为云就绪
  • 从 Java Spring Boot 迁移到 Quarkus
  • 从 OpenJDK 8 升级到 OpenJDK 11
  • 从 OpenJDK 11 升级到 OpenJDK 17
  • 将 EAP Java 应用程序迁移到 Azure App Service
  • 将 Spring Boot Java 应用程序迁移到 Azure 应用程序服务

有关用例和迁移路径的更多信息,请参阅适用于开发人员网页的 MTA

Migration Toolkit for Applications 如何简化迁移?

Migration Toolkit for Applications 会查找常见资源和在迁移应用程序时的已知问题。它为应用程序使用的技术提供了高级视图。

MTA 生成详细的报告,评估迁移或现代化路径。此报告可帮助您估算大型项目所需的工作量,并减少涉及的工作。

1.3. 关于 Maven 插件

用于应用程序的 Migration Toolkit 的 Maven 插件集成到 Maven 构建流程中,允许开发人员每次执行源代码时持续评估迁移和现代化工作。它提供了大量报告,突出显示分析结果,专为希望更新每个构建的开发人员而设计。

第 2 章 开始使用

2.1. 运行 Maven 插件

Maven 插件通过包含对应用的 pom.xml 文件中的插件的引用来运行。构建应用程序时,运行 Maven 插件并生成报告进行分析。

先决条件

  • 安装了 Java 开发套件 (JDK)。

    MTA 支持以下 JDK:

    • OpenJDK 11
    • Oracle JDK 11
  • 8 GB RAM
  • macOS 安装: maxproc 的值必须是 2048 或更高版本。
  • Maven settings.xml 文件配置为 Maven 使用 JBoss EAP Maven 存储库。
  • 要在 OpenJDK 17 或 Oracle JDK17 上运行 Maven 插件,首先需要在命令行上设置 MAVEN_OPTS:

    export MAVEN_OPTS="--add-modules=java.se --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.util=ALL-UNNAMED --add-opens java.base/java.util.stream=ALL-UNNAMED"

流程

  1. 将以下 <plugin> 加入到应用程序的 pom.xml 文件:

    [...]
    <plugin>
        <groupId>org.jboss.windup.plugin</groupId>
        <artifactId>mta-maven-plugin</artifactId>
        <version>6.1.3.GA1-redhat</version>
        <executions>
            <execution>
                <id>run-windup</id>
                <phase>package</phase>
                <goals>
                    <goal>windup</goal>
                </goals>
            </execution>
        </executions>
        <configuration>
            <target>eap:7</target> 1
        </configuration>
    </plugin>
    [...]
    1
    指定迁移目标。在配置中,必须至少提供一个迁移目标。
  2. --add-modules=java.se 添加到 MAVEN_OPTS 环境变量中。

    export MAVEN_OPTS=--add-modules=java.se
  3. 构建项目:

    $ mvn clean install

    您可以访问生成的报告。

2.2. 使用多个模块运行 Maven 插件

要在带有多个模块的项目中使用 Maven 插件,请将配置放在父的 pom.xml 中。在执行 Maven 插件期间,将生成单个报告,其中包含父模块和任何子模块的分析。

注意

强烈建议在多模块项目中将 inherited 设置为 false;否则,当每个子编译时,Maven 插件将会在编译每个子时运行,从而导致对子模块进行多个 Maven 插件执行。将 inherited 设置为 false 时,每个项目中都分析一次,并大大减少了启动时间。

若要在带有多个模块的项目中运行 Maven 插件,请执行以下步骤:

  1. 在父项目的 pom.xml 中包含以下插件。以下是父模块的 pom.xml 示例。

    <plugin>
        <groupId>org.jboss.windup.plugin</groupId>
        <artifactId>mta-maven-plugin</artifactId>
        <version>6.1.3.GA1-redhat</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>
            <target>eap:7</target> 1
            <windupHome>>/PATH/TO/CLI/<</windupHome>
        </configuration>
    </plugin>
    1
    指定迁移目标。在配置中,必须至少提供一个迁移目标。

    这个 pom.xml 文件与以下属性中的默认设置不同:

    • inherited :在插件级别上定义,此属性指示是否应在子模块中使用此配置。设置为 false 以提高性能。
    • input :指定包含要分析的项目的目录的路径。此属性默认为 {project.basedir}/src/main,并且应该定义父项目没有要分析的源代码。
    • windupHome :MTA CLI 的提取副本的路径。此属性为可选,但建议以提高性能。

      上面的示例演示了一组推荐的参数。

  2. 构建父项目。在构建过程中,Maven 插件针对项目中的所有子对象运行,而不进行进一步配置。

    $ mvn clean install
  3. 完成后,您可以访问生成的报告。此报告包含父项和所有子项的分析。

2.3. 访问报告

当您运行 Migration Toolkit for Applications 时,报告会在使用 pom.xml 中的 outputDirectory 参数指定的 OUTPUT_REPORT_DIRECTORY 中生成。在构建完成后,您会在构建日志中看到以下消息。

Windup report created: <OUTPUT_REPORT_DIRECTORY>/index.html

输出目录包含以下文件和子目录:

<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

有关 MTA 报告和使用方法评估迁移或现代化工作的信息,请参阅 MTA CLI 指南的审查报告部分。

第 3 章 以 CSV 格式导出报告

MTA 提供将报告数据(包括分类和提示)导出到本地文件系统上的平面文件的功能。导出功能当前支持 CSV 文件格式,其报告数据以逗号分开的字段显示(,)。

可以通过电子表格软件(如 Microsoft Excel、OpenOffice Calc 或 libreoffice Calc)导入和操作 CSV 文件。电子表格软件提供了从 MTA 报告排序、分析、评估和管理结果数据的功能。

3.1. 导出报告

要将报告导出为 CSV 文件,请运行将 exportCSV 参数设置为 true 的 MTA。

在由分析的每个应用程序的 --output 参数指定的目录中创建一个 CSV 文件。所有发现的问题(跨越所有分析的应用程序)都包含在 AllIssues.csv 文件中。

CSV 文件导出到由 outputDirectory 参数指定的目录中。

3.2. 将 CSV 文件导入到电子表格程序中

  1. 启动电子表格软件,如 Microsoft Excel。
  2. 选择 FileOpen
  3. 浏览 CSV 导出的文件并选择它。
  4. 数据现在已准备好在电子表格软件中进行分析。

3.3. 关于 CSV 数据结构

CSV 格式化输出文件包含以下数据字段:

规则 Id
生成给定项目的规则 ID。
问题类型
hintclassification
标题
classificationhint 的标题。此字段总结了给定项目的问题。
描述
给定项目问题的详细描述。
links
提供有关此问题的其他信息的 URL。链接由两个属性组成:链接和描述。
Application
生成此项目的应用程序的名称。
文件名
给定项的文件名。
文件路径
给定项目的文件路径。
给定项的文件行号。
故事点
代表给定项目的工作水平的故事点数。

附录 A. 参考材料

A.1. 关于 Maven 插件参数

以下是可用 MTA Maven 插件参数的详细描述。

表 A.1. MTA Maven 插件参数

参数描述

analyzeKnownLibraries

用于分析应用程序中嵌入的已知软件工件的标志。默认情况下,MTA 仅分析应用程序代码。

注意

这个选项可能会导致执行时间较长,并报告大量迁移问题。

customLoggingPropertiesFile

一个到包含 java.util.logging.LogManager 日志记录配置的 logging.properties 文件的绝对路径。如果指定路径无效,或者未指定 选项,则日志记录将恢复为使用 Maven 插件中包含的 logging.properties 文件。

disableTattletale

可禁用 Tattletale 报告的生成标志。如果同时将 enableTattletaledisableTattletale 设定为 true,则 disableTattletale 会被忽略,但仍会生成 Tattletale 报告。

enableCompatibleFilesReport

启用生成可组合文件报告的标志。由于处理的所有文件都未发现问题,对于大型应用程序,此报告可能需要很长时间才能完成。

enableTattletale

用于为每个应用程序生成 Tattletale 报告的标志。当 eap 位于包含的目标中时,默认启用这个选项。如果同时将 enableTattletaledisableTattletale 设定为 true,则 disableTattletale 会被忽略,但仍会生成 Tattletale 报告。

enableTransactionAnalysis

[技术预览] 标记来启用生成交易报告,该报告显示调用堆栈,该堆栈对关系数据库表执行操作。Enable Transaction Analysis 功能支持 Spring Data JPA,以及用于 SQL 语句执行的传统的 preparedStatement() 方法。它不支持 ORM 框架,如 Hibernate。

注意

enableTransactionAnalysis 只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议(SLA)支持,且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能,并有机会在开发阶段提供反馈意见。

excludePackages

要从评估中排除的软件包列表。例如,输入 "com.mycompany.commonutilities" 将排除所有软件包名称以"com.mycompany.commonutilities"开头的类。

excludeTags

要排除的标签列表。指定后,不会处理具有这些标签的规则。

explodedApps

指定提供的输入目录包含单个应用程序的源文件的标志。

exportCSV

标志,将报告数据导出到本地文件系统中的 CSV 文件。MTA 在由 outputDirectory 参数指定的目录中创建 文件。CSV 文件可导入到电子表格程序,以便进行数据操作和分析。

includeTags

要使用的标签列表。指定后,仅处理具有这些标签的规则。

inputDirectory

指定包含要分析的应用程序的目录路径。此参数默认为 {project.basedir}/src/main/

keepWorkDirs

标记指示 MTA 不删除临时工作文件,如图形数据库和解压缩存档。这对于调试非常有用。

legacyReports

标记指示 MTA 生成旧格式报告,而不是新格式报告。

软件包

MTA 要评估的软件包列表。此参数是必需的。

offlineMode

以离线模式运行的标记,禁用网络访问功能,如验证方案。用于提高性能。

outputDirectory

指定输出 MTA 生成的报告信息的目录路径。此参数默认为 {project.build.directory}/windup-report

覆盖

用于强制删除 outputDirectory 指定的现有输出目录的标志。默认值为 true

警告

请注意不要指定包含重要信息的报告输出目录!

sourceTechnologies

从迁移的一个或多个源技术、服务器、平台或框架的列表。这个参数与 targetTechnologies 参数结合使用有助于确定使用哪个规则集。

sourceMode

用于表示要评估的应用包含源文件而非编译的二进制文件的标志。默认值为 true

targetTechnologies

要迁移至的一个或多个目标技术、服务器、平台或框架的列表。这个参数与 sourceTechnologies 参数结合使用有助于确定使用哪个规则集。

userIgnorePath

指定 MTA 以确定应忽略的文件的位置。

userRulesDirectory

指定用于查找自定义 MTA 规则的位置。该值可以是包含规则集文件或单个规则集文件的目录。ruleset 文件必须使用 .windup.xml 后缀。

windupHome

指向提取的 MTA CLI 的 root 可选参数。通过引用 CLI 的本地安装,Maven 插件可直接访问所有索引,从而提高了性能。

windupVersion

指定要运行的 MTA 版本。默认情况下,这是 Maven 插件的构建版本。

A.1.1. 指定输入目录

包含要分析的一个或多个应用程序的文件或目录的路径。默认为 {project.basedir}/src/main/

使用方法

<inputDirectory>
    <INPUT_ARCHIVE_OR_DIRECTORY>
</inputDirectory>

A.1.2. 评估输入文件

根据为 inputDirectory 参数提供的输入文件类型,它会根据提供的附加参数进行评估,如下所示。

目录
--explodedApp--sourceMode没有参数

目录作为单个应用进行评估。

目录作为单个应用进行评估。

每个子目录都作为应用进行评估。

File
--explodedApp--sourceMode没有参数

参数将被忽略;该文件将评估为单个应用。

该文件作为压缩的项目进行评估。

该文件作为单个应用进行评估。

A.1.3. 指定输出目录

指定输出 MTA 生成的报告信息的目录路径。

使用方法

<outputDirectory>
    <OUTPUT_REPORT_DIRECTORY>
</outputDirectory>

  • 如果省略,则报告将在 {project.build.directory}/windup-report 目录中生成。
  • 如果存在输出目录,它将根据 overwrite 参数的值覆盖。此参数默认为 true,并让 MTA 删除并重新创建 目录。

A.1.4. 设置源技术

从迁移的一个或多个源技术、服务器、平台或框架的列表。这个参数与 targetTechnologies 参数结合使用有助于确定使用哪个规则集。

使用方法

<sourceTechnologies>
    <source>eap:6</source>
</sourceTechnologies>

现在,SourceTechnologies 参数提供版本支持,它遵循 Maven 版本范围语法。这指示 MTA 仅运行与指定版本匹配的规则集。例如,<source>eap:5</source>

A.1.5. 设置目标参数

要迁移至的一个或多个目标技术、服务器、平台或框架的列表。这个参数与 sourceTechnologies 参数结合使用有助于确定使用哪个规则集。这个参数是必需的

使用方法

<targetTechnologies>
  <target>eap:7</target>
</targetTechnologies>

targetTechnologies 参数现在提供版本支持,它遵循 Maven 版本范围语法。这指示 MTA 仅运行与指定版本匹配的规则集。例如,<target>eap:7</target>

警告

迁移到 JBoss EAP 时,请务必在目标中指定版本,例如 eap:6。仅指定 eap 将针对所有版本的 JBoss EAP 运行规则集,包括与您的迁移路径无关。

有关相应 JBoss EAP 版本的 Migration Toolkit for Applications 简介,请参阅支持的迁移路径

A.1.6. 选择软件包

MTA 要评估的软件包列表。强烈建议您使用此参数。

使用方法

<packages>
  <package>
    <PACKAGE_1>
  </package>
  <package>
    <PACKAGE_2>
  </package>
</packages>

  • 在大多数情况下,您只想评估自定义应用程序类软件包而不是标准 Java EE 或第三方软件包。<PACKAGE_N> 参数是一个软件包前缀;所有子软件包都会被扫描。例如,要扫描软件包 com.mycustomappcom.myotherapp,请在 pom.xml 中使用下列代码片段:

    <packages>
      <package>com.mycustomapp</package>
      <package>com.myotherapp</package>
    </packages>
  • 虽然您可以为标准 Java EE 第三方软件(如 org.apache )提供软件包名称,但通常最好不要包含它们,因为它们不会影响迁移工作。

A.2. 默认日志属性

Maven 插件包括的默认 logging.properties 文件如下。此配置省略了许多额外的消息,同时允许您查看 Maven 插件的进度。

默认 logging.properties 文件

# Licensed under the Eclipse Public License version 1.0, available at
# http://www.eclipse.org/legal/epl-v10.html
#

# Additional loggers to configure (the root logger is always configured)
#loggers=
handlers=java.util.logging.ConsoleHandler
.level=INFO
#java.util.logging.ConsoleHandler.level=INFO

#loggers=org.jboss.forge,org.jboss.weld,org.xnio,org.jboss.forge,org.ocpsoft.rewrite,org.jboss.windup.graph.GraphModelScanner,org.jboss.windup.reporting.xml.ClassificationHandler,org.jboss.windup.graph.GraphTyp$
org.jboss.forge.level=SEVERE
org.janusgraph.level=SEVERE
org.janusgraph.diskstorage.berkeleyje.BerkeleyJEKeyValueStore.level=SEVERE
org.janusgraph.diskstorage.berkeleyje.level=SEVERE
org.jboss.weld.level=SEVERE
org.xnio.level=SEVERE
org.jboss.forge.level=SEVERE
org.ocpsoft.rewrite.level=SEVERE
org.jboss.windup.graph.GraphModelScanner.level=SEVERE
org.jboss.windup.reporting.xml.ClassificationHandler.level=SEVERE
org.jboss.windup.graph.GraphTypeManager.level=SEVERE
org.jboss.windup.graph.GraphContextImpl.level=SEVERE
org.jboss.windup.rules.files.FileMapping.level=SEVERE
org.jboss.windup.exec.level=SEVERE
org.jboss.windup.config.level=SEVERE
com.thinkaurelius.level=SEVERE
org.jboss.windup=INFO

A.3. 关于规则故事点

A.3.1. 什么是故事点?

故事点是敏捷软件开发中常用的抽象指标,用于估算实施功能或更改所需的工作量水平

应用的 Migration Toolkit for Applications 使用故事点来代表迁移特定应用程序构造所需的工作程度,以及整个应用程序。它不一定转换为“人-小时”,但该值在不同的任务间应保持一致。

A.3.2. 故事点如何在规则中估计

估算一个规则的故事点的工作量水平可能很棘手。以下是估算规则所需工作量时,使用的一般准则 MTA。

努力级别故事点描述

信息

0

迁移过程中具有非常低或没有优先级的信息。

微小

1

迁移是一个微小的变化或一个简单的库交换,没有或有最小的 API 更改。

复杂

3

迁移任务所需的更改比较复杂,但有一个已包括在文档中的解决方案。

重新设计

5

迁移任务需要重新设计或完整的库更改,并有显著的 API 更改。

架构重组

7

迁移会需要组件或子系统的完全的架构重组。

Unknown

13

迁移解决方案并非已知的,可能需要进行彻底的重写。

A.3.3. 任务类别

除了工作程度外,您还可以对迁移任务进行分类,以指明任务的严重性。下列类别用于对问题进行分组,以帮助确定迁移的工作量。

Mandatory(必需)
必须成功完成该任务才能成功迁移。如果没有进行任何更改,则生成的应用不会成功构建或运行。例如,替换在目标平台中不支持的专有 API。
选填
如果没有完成迁移任务,应用程序应该可以正常工作,但结果可能不是最佳。如果迁移时没有进行任何更改,建议在迁移完成后尽快按计划设置。其中一个示例是将 EJB 2.x 代码升级到 EJB 3。
Potential
应在迁移过程中检查该任务,但没有足够的详细信息来确定任务是否成功完成。当没有直接兼容类型时,这将迁移第三方专有类型。
信息
该任务会包括告知您存在某些文件。可能需要将它们检查或修改为现代化工作的一部分,但通常不需要进行更改。其中一个示例就是一个日志记录依赖项或 Maven pom.xml

有关分类任务的更多信息,请参阅使用自定义规则类别

A.4. 其他资源

A.4.1. 参与

为了帮助应用程序的 Migration Toolkit for Applications 包括大多数应用程序结构和服务器配置,您可以使用以下项目帮助:

  • 发送电子邮件到 jboss-migration-feedback@redhat.com,并告知我们应该覆盖的 MTA 迁移规则。
  • 提供示例应用程序来测试迁移规则。
  • 识别迁移可能很难迁移的应用程序组件和问题区域。

    • 编写这些问题迁移区域的简短描述。
    • 编写简短概述,了解如何解决问题迁移区域。
  • 在应用程序上尝试 Migration Toolkit for Applications。请务必报告您遇到的任何问题。
  • 对应用程序规则存储库的 Migration Toolkit 提供贡献。

    • 编写 Migration Toolkit for Applications 规则以识别或自动迁移过程。
    • 为新规则创建一个测试。
    • 规则开发指南中提供了详细信息。
  • 为项目源代码贡献代码。

    • 创建核心规则。
    • 提高 MTA 性能或效率。

任何级别的参与都非常感谢!

A.4.3. 报告问题

MTA 使用 JIRA 作为其问题跟踪系统。如果您遇到执行 MTA 的问题,请提交 JIRA 问题





更新于 2023-10-26

法律通告

Copyright © 2023 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, 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.