Maven 插件指南
将 Red Hat Application Migration Toolkit 集成到 Maven 构建流程中。
摘要
第 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)是一个可扩展、可自定义的基于规则的工具,可帮助简化 Java 应用程序的迁移。
MTA 检查应用程序工件(包括项目源目录和应用程序存档),然后生成突出显示需要更改的区域的 HTML 报告。MTA 可用于将 Java 应用程序从先前版本的 红帽 JBoss 企业应用平台 或从其他容器迁移,如 Oracle® WebLogic Server 或 IBM® WebSphere® 应用服务器。
应用程序的迁移工具如何表示迁移?
在迁移应用程序时,应用程序迁移工具会查找常见资源和关注技术和已知问题点。目标是在应用程序所使用的技术中提供高级别视图,并提供详细的报告机构可用于估算、记录以及将企业应用程序迁移到 Java EE 和红帽 JBoss 企业应用平台。
如何了解更多信息?
请参阅 入门指南,了解有关 Migration Toolkit for Applications 中的功能、支持的配置、系统要求以及可用工具的更多信息。
1.3. 关于 Maven 插件
适用于应用的 Migration Toolkit 的 Maven 插件集成到 Maven 构建流程中,允许开发人员每次执行源代码时持续评估迁移和现代化工作。它提供了大量报告,突出显示分析结果,专为希望更新每个构建的开发人员而设计。
第 2 章 开始使用
2.1. 前提条件
在使用 Maven 插件前,请验证您是否满足以下先决条件:
- Java 平台,JRE 版本 8+
- 至少 4 GB RAM;建议 8 GB
- Maven 版本 3.2.5 或更高版本
如果您正在运行 macOS,建议将用户进程数上限、maxproc 设定为至少 2048,以及最大打开文件数,maxfiles 则设为 100000。
2.2. 运行 Maven 插件
Maven 插件通过包含对应用的 pom.xml 中的插件的引用来执行。构建应用程序时,将执行 Maven 插件并生成报告进行分析。
若要运行 Maven 插件,可执行下列步骤:
在应用程序的
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:表示以离线模式运行,从而禁用网络功能来提高性能。上例演示了最低要求参数。有关所有可用 参数的详情,请参阅 MTA Maven 参数。
如果使用 Java 11,则必须将
--add-modules=java.se添加到MAVEN_OPTS环境变量。如果不需要使用较旧版本的 Java,您可以继续下一步。export MAVEN_OPTS=--add-modules=java.se
重要在 Java 11 上使用 Maven 插件仅作为技术预览提供。技术预览功能不包括在红帽生产服务级别协议(SLA)中,且其功能可能并不完善。因此,红帽不建议在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能,并有机会在开发阶段提供反馈意见。
有关技术预览功能支持范围 的信息,请参阅红帽客户门户网站中的技术预览功能支持范围。
构建项目。
$ mvn clean install
- 访问生成的报告。
2.3. 使用多个模块运行 Maven 插件
要在带有多个模块的项目中使用 Maven 插件,请将配置放在父的 pom.xml 中。在执行 Maven 插件期间,将生成单个报告,其中包含父模块和任何子模块的分析。
强烈建议在多模块项目 中继承 为 false;否则,当每个子编译时,将执行 Maven 插件,从而导致对子模块进行多个 Maven 插件执行。将 inherited 设置为 false 时,每个项目中都分析一次,并大大减少了启动时间。
若要在带有多个模块的项目中运行 Maven 插件,请执行以下步骤:
在父项目的
pom.xml中包含以下插件。以下是父模块的pom.xml示例。<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>这个
pom.xml与通过 以下属性运行 Maven 插件时的名称:-
inherited:在插件级别上定义,此属性指示是否应在子模块中使用此配置。设置为false以提高性能。 -
input:指定包含要分析的项目的目录的路径。此属性默认为{project.basedir}/src/main,并且应该定义父项目没有要分析的源代码。 windupHome:MTA CLI 的提取副本的路径。此属性为可选,但建议以提高性能。上面的示例演示了一组推荐的参数。有关所有可用 参数的详情,请参阅 MTA Maven 参数。
-
构建父项目。在构建过程中,Maven 插件将针对项目中的所有子项执行,而不进行进一步配置。
$ mvn clean install
- 完成后,以正常方式 访问生成的报告。此报告包含父项和所有子项的分析。
2.4. 访问报告
在为 Applications 执行 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。CSV 文件将在分析的每个应用程序的 --output 参数指定的目录中创建。所有发现的问题(跨越所有分析的应用程序)都将包括在 AllIssues.csv 中。
<exportCSV>true</exportCSV>
CSV 文件将在 outputDirectory 参数指定的目录中创建。
3.2. 将 CSV 文件导入到 Spreadsheet 程序
- 启动电子表格软件,如 Microsoft Excel。
- 选择 File → Open。
- 浏览 CSV 导出的文件并选择它。
- 数据现在已准备好在电子表格软件中进行分析。
有关更多信息或解决任何问题,请查看电子表格软件的帮助。
3.3. CSV 数据结构概述
CSV 格式化输出文件包含以下数据字段:
- 规则 Id
- 生成给定项目的规则 ID。
- 问题类型
- hint 或 classification
- 标题
- classification 或 hint 的标题。此字段总结了给定项目的问题。
- 描述
- 给定项目问题的详细描述。
- links
- 提供有关此问题的其他信息的 URL。链接由两个属性组成:链接和描述。
- Application(应用程序)
- 生成此项目的应用程序的名称。
- 文件名
- 给定项的文件名。
- 文件路径
- 给定项目的文件路径。
- 行
- 给定项的文件行号。
- 故事点
- 代表给定项目的工作水平的故事点数。
附录 A. 参考资料
A.1. Maven 插件参数
以下是可用 MTA Maven 插件参数的详细描述。
表 A.1. MTA Maven 插件参数
| 参数 | 描述 |
|---|---|
| customLoggingPropertiesFile |
一个到包含 |
| disableTattletale |
可禁用 Tattletale 报告的生成标志。如果同时将 |
| enableCompatibleFilesReport | 启用生成可组合文件报告的标志。由于处理的所有文件都未发现问题,对于大型应用程序,此报告可能需要很长时间才能完成。 |
| enableTattletale |
用于为每个应用程序生成 Tattletale 报告的标志。当 |
| excludePackages | 要从评估中排除的软件包列表。例如,输入 "com.mycompany.commonutilities" 将排除所有软件包名称以"com.mycompany.commonutilities"开头的类。 |
| excludeTags | 要排除的标签列表。指定后,不会处理具有这些标签的规则。 |
| explodedApps | 指定提供的输入目录包含单个应用程序的源文件的标志。详情请参阅 输入文件机构表。 |
| exportCSV |
标志,将报告数据导出到本地文件系统中的 CSV 文件。MTA 在由 |
| includeTags | 要使用的标签列表。指定后,仅处理具有这些标签的规则。 |
| inputDirectory |
指定包含要分析的应用程序的目录路径。此参数默认为 |
| keepWorkDirs | 标记指示 MTA 不删除临时工作文件,如图形数据库和解压缩存档。这对于调试非常有用。 |
| 软件包 | MTA 要评估的软件包列表。此参数是必需的。如需更多信息,请参阅选择软件包。 |
| offlineMode | 以离线模式运行的标记,禁用网络访问功能,如验证方案。用于提高性能。 |
| outputDirectory |
指定输出 MTA 生成的报告信息的目录路径。此参数默认为 |
| 覆盖 |
用于强制删除 警告 请注意不要指定包含重要信息的报告输出目录! |
| sourceTechnologies |
从迁移的一个或多个源技术、服务器、平台或框架的列表。这个参数与 |
| sourceMode |
用于表示要评估的应用包含源文件而非编译的二进制文件的标志。默认为 |
| targetTechnologies |
要迁移至的一个或多个目标技术、服务器、平台或框架的列表。这个参数与 |
| userIgnorePath | 指定 MTA 以确定应忽略的文件的位置。 |
| userRulesDirectory |
指定用于查找自定义 MTA 规则的位置。该值可以是包含规则集文件或单个规则集文件的目录。ruleset 文件必须使用 |
| windupHome | 指向提取的 MTA CLI 的 root 可选参数。通过引用 CLI 的本地安装,Maven 插件可直接访问所有索引,从而提高了性能。 |
| windupVersion | 指定要运行的 MTA 版本。默认情况下,这是 Maven 插件的构建版本。 |
A.1.1. 指定输入目录
包含要分析的一个或多个应用程序的文件或目录的路径。默认为 {project.basedir}/src/main/。
使用
<inputDirectory>INPUT_ARCHIVE_OR_DIRECTORY</inputDirectory>
根据为 inputDirectory 参数提供的输入文件类型,它会根据提供的附加参数进行评估,如下所示。
- 目录
--explodedApp --sourceMode 没有参数 目录作为单个应用进行评估。
目录作为单个应用进行评估。
每个子目录都作为应用进行评估。
- File
--explodedApp --sourceMode 没有参数 参数将被忽略;该文件将评估为单个应用。
该文件作为压缩的项目进行评估。
该文件作为单个应用进行评估。
A.1.2. 指定输出目录
指定输出 MTA 生成的报告信息的目录路径。
使用
<outputDirectory>OUTPUT_REPORT_DIRECTORY</outputDirectory>
-
如果省略,则报告将在
{project.build.directory}/windup-report目录中生成。 -
如果存在输出目录,它将根据
overwrite参数的值覆盖。此参数默认为true,并让 MTA 删除并重新创建 目录。
A.1.3. 设置 Source Technology
从迁移的一个或多个源技术、服务器、平台或框架的列表。这个参数与 targetTechnologies 参数结合使用有助于确定使用哪个规则集。
使用
<sourceTechnologies>
<source>eap:6</source>
</sourceTechnologies>
现在,SourceTechnologies 参数提供版本支持,它遵循 Maven 版本范围语法。这指示 MTA 仅运行与指定版本匹配的规则集。例如,<source>eap:5</source>。
A.1.4. 设置目标机构
要迁移至的一个或多个目标技术、服务器、平台或框架的列表。这个参数与 sourceTechnologies 参数结合使用有助于确定使用哪个规则集。这个参数是必需的
使用
<targetTechnologies> <target>eap:7</target> </targetTechnologies>
targetTechnologies 参数现在提供版本支持,它遵循 Maven 版本范围语法。这指示 MTA 仅运行与指定版本匹配的规则集。例如,<target>eap:7</target>。
迁移到 JBoss EAP 时,请务必在目标中指定版本,例如 eap:6。仅指定 eap 将针对所有版本的 JBoss EAP 运行规则集,包括与您的迁移路径无关。
请参阅适用于您的源平台的 MTA 入门指南中的 支持的迁移路径。
A.1.5. 选择软件包
MTA 要评估的软件包列表。强烈建议您使用此参数。
使用
<packages> <package>PACKAGE_1</package> <package>PACKAGE_2</package> </packages>
在大多数情况下,您只想评估自定义应用程序类软件包而不是标准 Java EE 或第三方软件包。
PACKAGE_N参数是一个软件包前缀;将扫描所有子软件包。例如,要扫描软件包com.mycustomapp和com.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 文件如下。此配置省略了许多额外的消息,同时允许您查看 Maven 插件的进度。
# # Copyright 2013-2014 Red Hat, Inc. and/or its affiliates. # # 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. 什么是问题?
故事点是敏捷软件开发中常用的抽象指标,用于估算实施功能或更改所需的工作量水平。
应用程序迁移工具套件使用故事点来表达迁移特定应用程序构造所需的工作级别,以及整个应用程序。它不一定转换为“人-小时”,但该值在不同的任务间应保持一致。
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. Involved
为了帮助为应用程序制作 Migration Toolkit for Applications 包括大多数应用程序构建和服务器配置,您可以使用以下任何项目的帮助:
- 发送电子邮件到 jboss-migration-feedback@redhat.com,并告知我们应该覆盖的 MTA 迁移规则。
- 提供示例应用程序来测试迁移规则。
识别迁移可能很难迁移的应用程序组件和问题区域。
- 编写这些问题迁移区域的简短描述。
- 编写简短概述,了解如何解决问题迁移区域。
- 在应用程序上尝试 Migration Toolkit for Applications。请务必 报告您遇到的任何问题。
对应用程序规则存储库的 Migration Toolkit 提供贡献。
- 编写 Migration Toolkit for Applications 规则以识别或自动迁移过程。
- 为新规则创建一个测试。
- 《规则开发指南 》中提供了详细信息。
为项目源代码贡献代码。
- 创建核心规则。
- 提高 MTA 性能或效率。
- 有关如何配置您的环境并设置项目的信息,请参阅核心开发指南。
任何级别的参与都非常感谢!
A.4.2. 重要链接
- MTA 论坛:https://developer.jboss.org/en/windup
MTA JIRA 问题跟踪器
- MTA 邮件列表:jboss-migration-feedback@redhat.com
- Twitter 上的 MTA :@JBossWindup
-
MTA IRC 频道:Server FreeNode (
irc.freenode.net), channel#windup(transcripts).
A.4.3. 已知的 MTA 问题
您可以在此查看 MTA 的已知问题: 打开 MTA 问题。
A.4.4. 报告 MTA 的问题
Migration Toolkit for Applications 使用 JIRA 作为其问题跟踪系统。如果您在执行 MTA 时遇到问题,请提交 JIRA 问题。
如果还没有,则必须注册 JIRA 帐户才能创建 JIRA 问题。
A.4.4.1. 创建 JIRA 问题
打开浏览器并导航到 JIRA Create Issue 页面。
如果您还没有登录,点页面右上方的 Log In 链接并输入您的凭证。
选择以下选项并单击" 下一步" 按钮。
项目
对于核心 MTA 问题,请选择 Red Hat Application Migration Toolkit (WINDUP)。
对于 MTA 规则的问题,请选择: Red Hat Application Migration Toolkit 规则(WINDUPRULE)。
- 问题类型 :error
在下一屏幕中,完成以下字段。
- Summary :输入问题的简短描述或问题。
- 环境 :提供您的操作系统、Java 版本和其他相关信息的详细信息。
- 描述 :提供问题的详细描述。确保包括日志和异常追踪。
- 附加 :如果应用程序或存档导致问题不包含敏感信息,并且您已熟悉与 MTA 开发团队共享,则使用 浏览 按钮将其附加到问题。
- 单击 Create 按钮以创建 JIRA 问题。
修订 2022-11-12 22:52:37 +1000