迁移指南

Red Hat JBoss Enterprise Application Platform 7.4

将应用程序从一个主 Red Hat JBoss Enterprise Application Platform 版本迁移到下一个版本的说明。

Red Hat Customer Content Services

摘要

本指南提供有关将应用程序从以前版本的 Red Hat JBoss Enterprise Application Platform 中进行迁移的信息。

提供有关 JBoss EAP 文档的反馈

要报告错误或改进文档,请登录到 Red Hat JIRA 帐户并提交问题。如果您没有 Red Hat Jira 帐户,则会提示您创建一个帐户。

流程

  1. 单击以下链接 以创建 ticket
  2. 请包含 文档 URL章节编号 并描述问题
  3. Summary 中输入问题的简短描述。
  4. Description 中提供问题或功能增强的详细描述。包括一个指向文档中问题的 URL。
  5. Submit 创建问题,并将问题路由到适当的文档团队。

使开源包含更多

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

第 1 章 简介

本指南介绍了在 Red Hat JBoss Enterprise Application Platform 7 上成功运行和部署 Red Hat JBoss Enterprise Application Platform 6 应用程序所需的更改。它提供有关此版本中可用的新功能、已弃用和不支持的功能的信息,以及防止应用行为更改所需的应用程序和服务器配置更新。

它还提供有关有助于迁移的工具的信息,例如简化 Java 应用程序迁移的应用程序迁移工具(Migration Toolkit for Applications),以及更新服务器配置的 JBoss 服务器迁移工具

成功部署并运行应用后,可以制定计划来升级各个组件以使用 JBoss EAP 7 的新功能和功能。

如果您计划将 JBoss EAP 5 应用直接迁移至 JBoss EAP 7,请参阅从旧版 JBoss EAP 迁移

1.1. 关于迁移和升级

主版本升级

当应用从一个主要版本移至另一个主要版本(例如从 JBoss EAP 6.4 移到 JBoss EAP 7.0)时,需要进行重大升级或迁移。如果应用遵循 Jakarta EE 规范,不访问已弃用的 API,并且不包含专有代码,则有可能在不更改应用代码的情况下在 JBoss EAP 7 中运行应用。但是,JBoss EAP 7 中的服务器配置已更改,需要迁移。本指南解决了此类迁移问题。

次版本更新

JBoss EAP 定期提供点版本,它们是包括漏洞修复、安全修复和新功能的次要更新。有关点版本更改的信息,请查看本指南和 7.3.0 发行注记

您可以使用 JBoss 服务器迁移工具自动从一个点版本升级到另一个点版本,例如从 JBoss EAP 7.0 升级到 JBoss EAP 7.1。有关如何配置和运行工具的详情,请参考使用 JBoss 服务器迁移工具

您也可以手动升级服务器配置。有关如何执行手动升级的说明,请参见 JBoss EAP 补丁和升级指南中的升级 JBoss EAP

累积补丁

JBoss EAP 定期提供包含漏洞和安全修复的累积修补程序。累积修补程序将发行版递增到最后一个数字,例如从 7.1.0 增加到 7.1.1。JBoss EAP 补丁和升级指南包括了与补丁安装相关的信息。

1.2. 关于本文档中 EAP_HOME 的使用

在本文档中,变量 EAP_HOME 用于表示 JBoss EAP 安装的路径。将此变量替换为 JBoss EAP 安装的实际路径。

  • 如果您使用 ZIP 安装方法安装 JBoss EAP,安装目录是您解压 ZIP 存档的 jboss-eap-7.4 目录。
  • 如果您使用 RPM 安装方法安装 JBoss EAP,安装目录为 /opt/rh/eap7/root/usr/share/wildfly/
  • 如果您使用安装程序安装 JBoss EAP,EAP_HOME 的默认路径为 ${user.home}/EAP-7.4.0

    • 对于 Red Hat Enterprise Linux 和 Solaris: /home/USER_NAME/EAP-7.4.0/
    • 对于 Microsoft Windows: C:\Users\USER_NAME\EAP-7.4.0\
  • 如果您使用 Red Hat CodeReady Studio 安装程序安装和配置 JBoss EAP 服务器,EAP_HOME 的默认路径为 ${user.home}/devstudio/runtimes/jboss-eap

    • 对于 Red Hat Enterprise Linux:/home/USER_NAME/devstudio/runtimes/jboss-eap/
    • 对于 Microsoft Windows:C:\Users\USER_NAME\devstudio\runtimes\jboss-eapC:\Documents and Settings\USER_NAME\devstudio\runtimes\jboss-eap\
注意

如果您在 Red Hat CodeReady Studio 中将 Target runtime 设为 7.4 或更新的运行时版本,则您的项目与 Jakarta EE 8 规范兼容。

注意

EAP_HOME 不是环境变量。JBOSS_HOME 是脚本中使用的环境变量。

第 2 章 迁移准备

注意

Oracle 向 Jakarta EE 8 贡献了 Java EE 8 TCK,后者由 Jakarta EE 8 实施(如 JBoss EAP)用于兼容 Jakarta EE 8。Jakarta EE 8 API 等同于 Java EE 8 API。Jakarta EE 8 规范(技术)等同于 Java EE 8 规范(技术)。

2.1. 准备概述

在 JBoss EAP 7 中,曾努力为 JBoss EAP 6 应用程序提供向后兼容性。但是,如果您的应用使用了已弃用的功能或从 JBoss EAP 7 中删除的功能,您可能需要更改您的应用代码。

此外,本发行版中发生了一些变化,可能会影响 JBoss EAP 7 应用的部署。建议您在尝试迁移应用之前进行一些研究和规划。

一旦您熟悉功能的变更、开发材料以及可帮助您迁移工作的工具,您可以开始评估您的应用和服务器配置,以确定在 JBoss EAP 7 中运行所需的更改。

2.2. 查看 Jakarta EE 8 功能

Jakarta EE 8 包括了许多改进功能,使得在私有云和公共云上开发和运行丰富的应用程序变得更容易。它整合了新的功能和最新的标准,如 HTML5、WebSocket、JSON、Batch 和 Concurrency Utilities。更新包括 Jakarta Persistence 2.2、Jakarta RESTful Web Services 2.1、Jakarta Servlet 4.0、Jakarta Expression Language 3.0、Jakarta Messaging 2.0.Jakarta Server Faces 2.3、Jakarta Enterprise Beans 3.2、上下文和依赖注入 2.0 以及 Jakarta Bean Validation 2.0.

您可以在 Jarkata EE Platform 8 上找到有关 Jakarta EE 8 的更多信息。

2.3. 查看 Java EE 7 功能

如果您要从 JBoss EAP 6.4 进行迁移,Java EE 7 包括了许多改进,以便更轻松地在私有云和公共云上开发和运行丰富的应用程序。它包含新的功能和最新的标准,如 HTML5、WebSocket、JSON、Batch 和 Concurrency Utilities。更新包括 JPA 2.1、JAX-RS 2.0、Servlet 3.1、表达式语言 3.0、JMS 2.0。JSF 2.2、EJB 3.2、CDI 1.2 和 Bean 验证 1.1.

您可以在 Oracle 网站上找到有关 Java EE 7 的更多信息,包括教程:Java™ EE 文档

2.4. 参阅 JBoss EAP 7 中的新功能

与之前版本相比,JBoss EAP 7 包括一些显著的升级和改进。本节重点介绍 JBoss EAP 7 点版本中引入的一些新功能和增强功能。

引入了 JBoss EAP 7.0 的新功能和增强功能

Jakarta EE 8
JBoss EAP 7 是经过认证的 Jakarta EE 8 实施,同时满足 Web 配置文件和完整的平台规格。它还支持 Jakarta 上下文和依赖注入 2.0 和 Jakarta WebSocket 1.1 的最新迭代。
Undertow
Undertow 是 JBoss EAP 7 中包含的全新轻量、灵活且高性能的 Web 服务器,取代了 JBoss Web。它以 Java 语言编写,旨在实现最大吞吐量和可扩展性。它支持最新的 Web 技术,如新的 HTTP/2 标准。
Apache ActiveMQ Artemis
Apache ActiveMQ Artemis 是全新的 JBoss EAP 7 内置消息传递提供商。根据 HornetQ 贡献的代码,此 Apache 子项目根据公认的非阻塞架构提供出色的性能。
IronJacamar 1.2
最新的 IronJacamar 为 Jakarta Connectors 和 DataSources 提供了稳定且丰富的支持。
JBossWS 5
第五个 JBossWS 是向前发展的重大飞跃,为 JBoss EAP 7 Web 服务带来了新功能和性能改进。
resteasy 3
JBoss EAP 7 包括最新一代的 RESTEasy。它提供很多有用的扩展,如 JSON Web 加密、Jackson、Jkarta JSON Processing 1.1 和 Jettison,它超越了标准的 Jakarta RESTful Web Services 2.1。
OpenJDK ORB
JBoss EAP 7 用 OpenJDK ORB 的下游分支取代了 JacORB IIOP 实施,从而提高了与 JVM ORB 的互操作性。
丰富集群功能
JBoss EAP 7 中大量重构了集群支持,包括多个供应用访问的公共 API。
端口缩减
利用 HTTP 升级,JBoss EAP 7 已经转移了其几乎所有协议,以仅通过两个 HTTP 端口进行多路复用:管理端口(9990)和应用端口(8080)。
增强的日志记录
管理 API 现在支持列出和查看服务器上的可用日志文件,甚至定义默认模式格式器以外的自定义格式器。部署的日志设置也大大增强。

有关 JBoss EAP 7.0 中引入的新功能的完整列表,请参阅 JBoss EAP 7.0.0 发行注记中的新功能和增强功能

JBoss EAP 7.1 中引入了新功能和增强功能

Elytron
Elytron 基于 WildFly Elytron 项目,是 JBoss EAP 7.1 中的新安全框架。它旨在统一整个应用服务器的安全性。
管理控制台
管理控制台得到了改进,可提供配置更多子系统的功能,提供增强的 transaction 子系统和交易资源指标,以及管理许多其他配置。
管理 CLI
管理 CLI 通过 echo-command 参数提供对响应和文件附加、模块配置和调试支持的增强支持。

有关 JBoss EAP 7.1 中引入的新功能的完整列表,请参阅红帽客户门户上的 7.1.0 发行注记中的新功能和增强功能

JBoss EAP 7.2 中引入了新功能和增强功能

Jakarta EE 8
JBoss EAP 7.2 是经过认证的 Jakarta EE 8 实施。它支持 Jakarta Servlet 4.0、Jakarta Persistence 2.2、上下文和依赖注入 2.0、Jkarta Server Faces 2.3、Jakarta JSON Binding 1.0、Jakarta JSON Binding 1.0、Jakarta JSON Processing 1.1 和 Jakarta RESTful Web Services 2.1 等。如需有关 Jakarta 企业版(Jakarta EE)8 平台所支持技术的更多信息,请参阅 Jakarta EE 平台 8

JBoss EAP 7.3 中引入了新功能和增强功能

集群
mod_cluster 子系统现在定义一个新属性 initial-loadinitial-load 属性有助于逐渐增加新加入节点的负载值,以避免在加入集群时出现过载。
Eclipse MicroProfile 指标
Eclipse MicroProfile 指标功能为 JBoss EAP 提供监控数据。此发行版本增强了 SmallRye Metrics 组件,以 Prometheus 格式提供 JBoss EAP 指标。
Jakarta Enterprise Beans
消息驱动型 Bean(MDB)现在可以属于多个交付组。
Elytron
本发行版本中的 elytron 子系统现在提供了来自用于容器的 Java Authentication SPI(JASPI)的 Servlet 配置集的实施。Elytron 现在包括增强的 JwtValidator 支持。对 Jakarta EE 安全 API(Security 1.0 API)支持也包含在 Jakarta 安全 1.0 规范中。
Jakarta EE 8
JBoss EAP 7.3 基于 Jakarta EE 8 平台。
Jakarta EE 8 对 BOMs 的更改

由于在 JBoss EAP 7.3 中迁移到 Jakarta EE 8 平台,组 ID org.jboss.bom 中的部分 JBoss EAP BOM 已被取代。如果您的应用使用被替换的 BOM,请更新项目 POM,使其包含新 BOM 的工件 ID,以将应用迁移到 JBoss EAP 7.3 版本。以下 BOM 被替换:

表 2.1. 对于 Jakarta EE,BOM 工件(Artifacts)在 Group ID org.jboss.bom 中被替换

旧工件 ID新工件 ID

jboss-eap-javaee8

jboss-eap-jakartaee8

jboss-eap-javaee8-with-tools

jboss-eap-jakartaee8-with-tools

有关配置项目依赖项的信息,请参阅开发指南中的管理项目依赖项

Jakarta EE 8 向后兼容性
JBoss EAP 7.3 保持与 Jakarta EE 8 的向后兼容性。Jakarta EE 8 仍然保持向后兼容其他 Jakarta EE 版本。所有以前的 JBoss EAP 7 应用都应部署在 JBoss EAP 7.3 上。
JBoss EAP Operator
JBoss EAPnow 提供特定于 JBoss EAP 的控制器 EAP 操作员,自动化常见与部署相关的任务。EAP 操作器确保应用集群中的安全交易恢复,并使用 StatefulSet 来适当处理 Jakarta 企业 Bean 复制和事务恢复处理。
管理控制台
现在可以从管理控制台配置外部 Jakarta 消息传递服务器资源。
消息传递
journal-file-open-timeout 属性现在配置打开消息日志文件的超时值。

除了现有的对静态 HTTP 负载平衡器的支持外,现在还支持使用 mod_cluster 的负载平衡器。

OpenShift 增强
OpenShift 现在将 JBoss EAP 管理 CLI 用于 S2I 构建。OpenShift 现在允许使用 Galleon 层自定义镜像占用空间。Jakarta Enterprise Beans 升级和交易恢复处理也得到了极大的改进。
安全性
此发行版本中的 server-ssl-sni-context 提供服务器端 SNI 匹配。它提供匹配规则,以将主机名与 SSL 上下文关联,并在未匹配任何提供的主机名时提供默认值。

有关 JBoss EAP 7.3 中引入的新功能的完整列表,请参阅红帽客户门户上的 7.3.0 发行注记中的新功能和增强功能

2.5. 查看已弃用和不支持的功能列表

在将应用迁移到 JBoss EAP 7.4 之前,请注意先前版本的 JBoss EAP 中提供的一些功能可能已被弃用或不再受支持。由于维护成本高、社区兴趣低和更好的替代解决方案,部分技术的支持已被移除。

以下是一些已弃用且不支持的功能的简短总结:

实体 Bean
实体 Bean 不再被支持。如果您的应用使用实体 bean,您应该迁移代码以使用 Jakarta Persistence,这提供了性能更高且更灵活的 API。
JAX-RPC
因为 Jakarta XML Web 服务提供了更加准确、更完整的解决方案,所以应该迁移为 Jakarta XML RPC 编写的代码,以使用 Jakarta XML Web 服务。
jakarta Deployment
Jakarta Deployment 定义了一个合同,使多个供应商的工具能够在任何 Jakarta EE 8 平台产品上配置和部署应用程序,但并未被广泛采用。您必须使用另一个 JBoss EAP 支持的选项来进行应用部署,如管理控制台、管理 CLI、部署扫描程序或 Maven。
通用 Jakarta 消息传递资源适配器
不再支持配置通用 Jakarta 消息传递资源适配器以连接到 Jakarta 消息传递供应商的功能。
IO 子系统
IO 缓冲池已弃用,但它们仍设置为当前版本中的默认设置。如果需要,您可以将 Undertow 字节缓冲区池设置为默认值。
缓存存储
remote 缓存存储已被弃用,而是使用 hotrod 缓存存储。
平台和功能
之前版本中可用的多个平台和数据库已在 JBoss EAP 7.4 中弃用。

有关 JBoss EAP 7.0 中已弃用和不支持的功能的完整列表,请参阅红帽客户门户上的 JBoss EAP 7.0.0 发行注记中的不受支持和已弃用的功能

有关 JBoss EAP 7.1 中已弃用和不支持的功能的完整列表,请参阅红帽客户门户上的 JBoss EAP 7.1.0 发行注记中的不受支持和已弃用的功能

有关 JBoss EAP 7.2 中已弃用和不支持的功能的完整列表,请参阅红帽客户门户上的 JBoss EAP 7.2.0 发行注记中的不受支持和已弃用的功能

有关 JBoss EAP 7.3 中已弃用和不支持的功能的完整列表,请参阅红帽客户门户上的 JBoss EAP 7.3.0 发行注记中的不受支持和已弃用的功能

2.6. 查看 JBoss EAP 入门资料

务必查阅 JBoss EAP 入门指南。它包含以下重要信息:

  • 如何下载和安装 JBoss EAP 7
  • 如何下载和安装 Red Hat CodeReady Studio
  • 为您的开发环境配置 Maven,管理项目依赖项,并将项目配置为使用 JBoss EAP Bill of Material(BOM)工件
  • 如何下载并运行随产品随附的快速入门示例应用程序

2.7. 迁移分析和规划

每个应用程序和服务器配置都是唯一的,在尝试迁移之前,您必须彻底了解现有应用程序和服务器平台的组件和架构。您的迁移计划应包括用于测试和部署到生产的详细路线图,其中应考虑以下信息:

确定负责迁移的人员
确定负责迁移的利益相关者、项目经理、开发人员、管理员和其他人员。
查看应用程序服务器平台配置和硬件

检查现有的应用服务器和平台配置,以确定它们受到 JBoss EAP 7 中的功能更改的影响。这应包括以下项目:

  • 操作系统和版本
  • 应用程序使用的数据库
  • Web 服务器
  • 安全架构
  • 处理器的数量和类型
  • 内存量
  • 物理磁盘存储量
  • 数据库或消息传递数据的迁移
  • 可能会受迁移影响的其他组件
查看当前生产环境

您应该计划尽可能密切地重新创建生产环境,以测试和暂存迁移过程。

  • 考虑任何集群配置。有关如何迁移集群的更多信息,请参阅 JBoss EAP 补丁和升级指南中的升级一个集群
  • 如果您目前正在运行大型受管域,请考虑逐步迁移方法。
  • 确定您是否需要迁移任何数据库或消息传递数据。
检查并了解现有应用

彻底检查现有的 JBoss EAP 6 应用。完全熟悉其架构、功能、特性和组件,包括:

  • JVM 版本
  • 与其他红帽应用服务器中间件组件集成
  • 与专有第三方软件集成
  • 使用需要替换的已弃用功能
  • 应用程序配置,包括部署描述符、Java 命名和目录接口、持久性、JDBC 配置和池、Jakarta 消息传递主题和队列,以及日志记录

识别在迁移到 JBoss EAP 7 期间需要修改的任何代码或配置不兼容。

创建详细的测试计划
  • 计划应包括回归测试和验收标准要求。
  • 它还应包括性能测试。
  • 设置一个与生产环境最接近的暂存环境,以便在推出到生产前测试迁移。
  • 确保创建备份和恢复计划!
查看为迁移过程可用的资源
  • 评估开发团队的技能,规划培训或其他咨询帮助。
  • 请注意,在迁移过程中暂存和测试需要额外的硬件和其他资源,直到工作完成为止。
  • 确定是否需要正式培训。如果是,将其添加到计划。
执行计划
收集所需资源并实施迁移计划。
重要

在对应用进行任何修改之前,请务必创建备份副本。

2.8. 备份重要数据和查看服务器状态

在迁移应用之前,您需要了解以下潜在问题:

  • 迁移可能会删除临时文件夹。在迁移之前,存储在 data/content/ 目录中的所有部署都必须备份,并在迁移完成后进行恢复。否则,由于缺少内容,服务器将无法启动。
  • 在迁移之前,请处理任何开放事务并删除 data/tx-object-store/ transaction 目录。
  • 必须检查 data/timer-service-data 中的持久定时器数据,以确定升级后是否仍然适用。在升级前,请查看该目录中的 deployment-* 文件以确定哪些计时器仍在使用。

务必在开始之前备份当前服务器配置和应用程序。

2.9. 迁移 RPM 安装

重要

不支持在单个 Red Hat Enterprise Linux 服务器上拥有多个 RPM 安装的 JBoss EAP 实例。因此,建议您在迁移到 JBoss EAP 7 时将您的 JBoss EAP 安装迁移到新机器。

将 JBoss EAP RPM 安装从 JBoss EAP 6 迁移到 JBoss EAP 7 时,请确保将 JBoss EAP 7 安装在没有现有 JBoss EAP RPM 安装的计算机上。

要使用 RPM 安装 JBoss EAP 7,请参阅 JBoss EAP 安装指南

本指南中的迁移建议也适用于迁移 JBoss EAP 的 RPM 安装,但您可能需要更改一些步骤(如如何启动 JBoss EAP)来适合与 ZIP 或安装程序安装相比 RPM 安装。

2.10. 迁移作为服务运行的 JBoss EAP

如果您将 JBoss EAP 6 作为服务运行,请查阅 JBoss EAP 安装指南中的配置 EAP 以作为服务运行,以获得 JBoss EAP 7 的更新配置说明。

第 3 章 迁移中的协助工具

3.1. 使用 Migration Toolkit for Application 分析应用程序进行迁移

应用迁移工具包(MTA)是一套可扩展且可自定义的基于规则的工具集,可帮助简化 Java 应用程序的迁移。它将分析您计划迁移的应用所使用的 API、技术和架构,并为每个应用提供详细的迁移报告。这些报告提供以下信息:

  • 所需迁移更改的详细解释
  • 报告的更改是强制的还是可选的
  • 报告的变化是复杂还是简单
  • 需要更改迁移代码的链接
  • 有关如何进行所需更改的信息提示和链接
  • 估算发现的每个迁移问题的工作量程度以及迁移应用的总预计工作量

在将 JBoss EAP 6 应用的代码和架构迁移到 JBoss EAP 7 之前,您可以使用 MTA 对它们进行分析。用于从 JBoss EAP 6 迁移到 JBoss EAP 7 的 MTA 规则集,报告了在迁移到 JBoss EAP 7 时需要被替代配置所取代的 XML 描述符和特定应用代码和参数。

有关如何使用应用程序的 Migration Toolkit 来分析您的 JBoss EAP 6 应用程序的更多信息,请参阅应用迁移工具包入门指南

3.2. 使用 JBoss 服务器迁移工具迁移服务器配置

JBoss 服务器迁移工具是更新您的服务器配置的首选方法,在 JBoss EAP 7 中包括新功能和设置,同时保持现有配置。JBoss 服务器迁移工具读取您现有的 JBoss EAP 服务器配置文件,并添加任何新子系统的配置,使用新功能更新现有的子系统配置,并删除任何过时的子系统配置。

您可以使用 JBoss 服务器迁移工具为以下配置迁移单机服务器和受管域:

迁移到 JBoss EAP 7.4

JBoss 服务器迁移工具随附 JBoss EAP 7.4,因此无需单独下载或安装。此工具支持从 JBoss EAP 6.4 以及所有 7.x 版本(直到 JBoss EAP 7.4)的迁移。您可以通过执行位于 EAP_HOME/bin 目录中的 jboss-server-migration 脚本来运行该工具。有关如何配置和运行工具的详情,请参考使用 JBoss 服务器迁移工具

建议您使用此版本的 JBoss 服务器迁移工具将您的服务器配置迁移到 JBoss EAP 7.4,因为支持此版本的工具。

从 WildFly 迁移到 JBoss EAP

如果要从 WildFly 服务器迁移到 JBoss EAP,您必须从 JBoss 服务器迁移工具 GitHub 存储库下载 JBoss 服务器迁移工具的最新二进制分发。这一开源、独立版本的工具支持从多个版本的 WildFly 服务器迁移到 JBoss EAP。有关如何安装和运行此版本的工具的详情,请参考 JBoss 服务器迁移工具用户指南

重要

不支持 JBoss 服务器迁移工具的二进制发行版。如果您要从之前的 JBoss EAP 版本迁移,建议您使用这个受支持的工具版本将您的服务器配置迁移到 JBoss EAP 7.4。

第 4 章 服务器配置更改

4.1. RPM 安装更改

在 JBoss EAP 6 中,RPM 安装的默认路径是 /usr/share/jbossas/ 目录。

JBoss EAP 7 构建为使用 Red Hat Software Collections 的形式。Software Collections 的根目录通常位于 /opt/ 目录中,以避免 Software Collections 和基本系统安装之间可能存在冲突。Filesystem Hierarchy Standard(FHS)建议使用 /opt/ 目录。因此,在 JBoss EAP 7 中,RPM 安装的默认路径已更改为 /opt/rh/eap7/root/usr/share/wildfly/

4.2. 服务器配置迁移选项

要将服务器配置从 JBoss EAP 6 迁移到 JBoss EAP 7,您可以使用 JBoss 服务器迁移工具,或者在 管理 CLI 迁移操作的帮助下执行手动 迁移

JBoss 服务器迁移工具

JBoss 服务器迁移工具是更新您的配置的首选方法,在 JBoss EAP 7 中包括新功能和设置,同时保持现有配置。有关如何配置和运行工具的详情,请参考使用 JBoss 服务器迁移工具

管理 CLI 迁移操作

您可以使用管理 CLI migrate 操作来更新 JBoss EAP 6 服务器配置文件中的 jacorbmessagingWeb 子系统,以允许它们在新版本上运行,但请注意其结果不是完整的 JBoss EAP 7 配置。例如:

  • 该操作不会将原始 remote 协议和端口设置更新为 JBoss EAP 7 中现在使用的新 http-remoting 和新的端口设置。
  • 配置中不包含新的 JBoss EAP 子系统或集群单例部署或安全关闭等功能。
  • 该配置不包括批处理等 Jakarta EE 8 功能。
  • migrate 操作不会迁移 ejb3 子系统配置。有关可能的 Jakarta Enterprise Beans 迁移问题的详情,请参阅 Jakarta Enterprise Beans 服务器配置更改。

有关使用 migrate 操作迁移服务器配置的更多信息,请参阅 管理 CLI 迁移操作

4.3. 管理 CLI 迁移操作

您可以使用管理 CLI 更新 JBoss EAP 6 服务器配置文件,使其在 JBoss EAP 7 上运行。管理 CLI 提供了 migrate 操作,可将上一发行版中的 jacorbmessagingWeb 子系统自动更新至新配置。您还可以对 jacorbmessagingweb 子系统执行 describe-migration 操作,以便在执行迁移前检查建议的迁移配置更改。cmpjaxrthreads 子系统没有替换,它们必须从服务器配置中移除。

重要

对于 migrate 操作的限制,请参阅 Server Configuration Migration Options。JBoss 服务器迁移工具是更新您的配置的首选方法,在 JBoss EAP 7 中包括新功能和设置,同时保持现有配置。有关如何配置和运行工具的详情,请参考使用 JBoss 服务器迁移工具

表 4.1. 子系统迁移和管理 CLI 操作

JBoss EAP 6 子系统JBoss EAP 7 子系统管理 CLI 操作

cmp

没有替换方案

remove

jacorb

iiop-openjdk

migrate

JAXR

没有替换方案

remove

messaging

messaging-activemq

migrate

threads

没有替换方案

remove

web

undertow

migrate

启动服务器和管理 CLI

按照以下步骤更新您的 JBoss EAP 6 服务器配置,使其在 JBoss EAP 7 上运行。

  1. 开始之前,请检查备份重要数据和查看服务器状态。它包含有关确保服务器处于良好状态并且已备份适当文件的重要信息。
  2. 使用 JBoss EAP 6 配置启动 JBoss EAP 7 服务器。

    1. 备份 JBoss EAP 7 服务器配置文件。
    2. 将上一版本的配置文件复制到 JBoss EAP 7 目录中。

      $ cp EAP6_HOME/standalone/configuration/standalone-full.xml EAP7_HOME/standalone/configuration
    3. 进入 JBoss EAP 7 安装目录,再使用 --start-mode=admin-only 参数启动服务器。

      $ bin/standalone.sh -c standalone-full.xml --start-mode=admin-only
      注意

      当您启动服务器时,您将在服务器日志中看到以下 org.jboss.as.controller.management-operation ERRORS:这些错误是正常的,并且表明必须删除传统的子系统配置或迁移到 JBoss EAP 7。

      • WFLYCTL0402:运行此版本的服务器上不支持由传统扩展名 'org.jboss.as.cmp' 提供的子系统 [cmp]。服务器必须先删除或迁移子系统和扩展。
      • WFLYCTL0402:运行此版本的服务器上不支持由传统扩展名 'org.jboss.as.jacorb' 提供的 Subsystems [jacorb]。服务器必须先删除或迁移子系统和扩展。
      • WFLYCTL0402:运行此版本的服务器上不支持由传统扩展名 'org.jboss.as.jaxr' 提供的子系统 [jaxr]。服务器必须先删除或迁移子系统和扩展。
      • WFLYCTL0402:运行此版本的服务器上不支持由传统扩展名 'org.jboss.as.messaging' 提供的子系统 [messaging]。服务器必须先删除或迁移子系统和扩展。
      • WFLYCTL0402:运行此版本的服务器上不支持由传统扩展名 'org.jboss.as.threads' 提供的子系统 [threads]。服务器必须先删除或迁移子系统和扩展。
      • WFLYCTL0402:运行此版本的服务器上不支持由传统扩展名 'org.jboss.as.web' 提供的子系统 [web]。服务器必须先删除或迁移子系统和扩展。
  3. 打开一个新终端,进入 JBoss EAP 7 安装目录,然后使用 --controller=remote://localhost:9990 参数启动管理 CLI。

    $ bin/jboss-cli.sh --connect --controller=remote://localhost:9990

迁移 JacORB、Messaging 和 Web 子系统

  1. 要在执行迁移前检查子系统将要进行的配置更改,请执行 describe-migration 操作。

    describe-migration 操作使用以下语法:

    /subsystem=SUBSYSTEM_NAME:describe-migration

    以下示例描述了在迁移到 JBoss EAP 7 时对 JBoss EAP 6.4 standalone-full.xml 配置文件进行的配置更改。条目已从输出中删除,以提高可读性和节省空间。

    示例: describe-migration Operation

    /subsystem=messaging:describe-migration
    {
        "outcome" => "success",
        "result" => {
            "migration-warnings" => [],
            "migration-operations" => [
                {
                    "operation" => "add",
                    "address" => [("extension" => "org.wildfly.extension.messaging-activemq")],
                    "module" => "org.wildfly.extension.messaging-activemq"
                },
                {
                    "operation" => "add",
                    "address" => [("subsystem" => "messaging-activemq")]
                },
                <!-- *** Entries removed for readability *** -->
                {
                    "operation" => "remove",
                    "address" => [("subsystem" => "messaging")]
                },
                {
                    "operation" => "remove",
                    "address" => [("extension" => "org.jboss.as.messaging")]
                }
            ]
        }
    }

  2. 执行 migrate 操作,将子系统配置迁移到 JBoss EAP 7 中的替换子系统。该操作使用以下语法:

    /subsystem=SUBSYSTEM_NAME:migrate
    注意

    messaging 子系统的 describe-migrationmigrate 操作允许您通过使用参数来配置老客户端的访问。有关命令语法的更多信息,请参阅 Messaging Subsystem Migration 和 Forward Compatibility

  3. 查看命令的结果。确保操作成功完成,并且没有"迁移警告"条目。这意味着子系统的迁移配置已经完成。

    示例:成功迁移操作时没有警告

    /subsystem=messaging:migrate
    {
        "outcome" => "success",
        "result" => {"migration-warnings" => []}
    }

    如果您在日志中看到"migration-warnings"条目,这表示服务器配置已成功迁移,但它无法迁移所有元素和属性。您必须遵循"migration-warnings"提供的建议,并运行额外的管理 CLI 命令来修改这些配置。以下是返回"migration-warnings"的 migrate 操作示例。

    示例:使用 Warning 迁移操作

    /subsystem=messaging:migrate
    {
        "outcome" => "success",
        "result" => {"migration-warnings" => [
            "WFLYMSG0080: Could not migrate attribute group-address from resource [
        (\"subsystem\" => \"messaging-activemq\"),
        (\"server\" => \"default\"),
        (\"broadcast-group\" => \"groupB\")
    ]. Use instead the socket-binding attribute to configure this broadcast-group.",
            "WFLYMSG0080: Could not migrate attribute group-port from resource [
        (\"subsystem\" => \"messaging-activemq\"),
        (\"server\" => \"default\"),
        (\"broadcast-group\" => \"groupB\")
    ]. Use instead the socket-binding attribute to configure this broadcast-group.",
            "WFLYMSG0080: Could not migrate attribute local-bind-address from resource [
        (\"subsystem\" => \"messaging-activemq\"),
        (\"server\" => \"default\"),
        (\"broadcast-group\" => \"groupA\")
    ]. Use instead the socket-binding attribute to configure this broadcast-group.",
            "WFLYMSG0080: Could not migrate attribute local-bind-port from resource [
        (\"subsystem\" => \"messaging-activemq\"),
        (\"server\" => \"default\"),
        (\"broadcast-group\" => \"groupA\")
    ]. Use instead the socket-binding attribute to configure this broadcast-group.",
            "WFLYMSG0080: Could not migrate attribute group-address from resource [
        (\"subsystem\" => \"messaging-activemq\"),
        (\"server\" => \"default\"),
        (\"broadcast-group\" => \"groupA\")
    ]. Use instead the socket-binding attribute to configure this broadcast-group.",
            "WFLYMSG0080: Could not migrate attribute group-port from resource [
        (\"subsystem\" => \"messaging-activemq\"),
        (\"server\" => \"default\"),
        (\"broadcast-group\" => \"groupA\")
    ]. Use instead the socket-binding attribute to configure this broadcast-group."
        ]}
    }

    注意

    对于每个子系统的 migratedescribe-migration 警告列表包括在本指南后面的 Reference Material 中。

  4. 检查服务器配置文件,以验证扩展、子系统和命名空间是否已更新,并且现有的子系统配置已迁移到 JBoss EAP 7。

    注意

    您必须使用以下命令为每个 jacorbmessagingweb 子系统重复此过程:

    /subsystem=jacorb:migrate
    /subsystem=messaging:migrate
    /subsystem=web:migrate
  5. 从服务器配置中删除 cmpjaxrthreads 子系统和扩展。

    当仍在管理 CLI 提示符中时,请执行以下命令来删除过时的 cmpjaxrthreads 子系统:

    /subsystem=cmp:remove
    /extension=org.jboss.as.cmp:remove
    /subsystem=jaxr:remove
    /extension=org.jboss.as.jaxr:remove
    /subsystem=threads:remove
    /extension=org.jboss.as.threads:remove
重要

您必须迁移 messagingjacorbWeb 子系统,并删除 cmpjaxrthreads 扩展和子系统,然后才能重新启动服务器以进行正常操作。如果您需要在完成此过程前重新启动服务器,请务必在服务器启动命令行中包含 --start-mode=admin-only 参数。这可让您继续进行配置更改。

4.4. 日志更改

4.4.1. 日志记录消息前缀更改

日志消息以报告消息的子系统的项目代码作为前缀。JBoss EAP 7 中更改了所有日志消息的前缀。

有关 JBoss EAP 7 中使用的新日志消息项目代码前缀的完整列表,请参阅 JBoss EAP 开发指南 中的 JBoss EAP 中使用的项目代码

4.4.2. 根日志记录器控制台处理程序更改

JBoss EAP 7.0 根日志记录器包含用于所有域服务器配置文件的控制台日志处理程序,以及 standalone-full-ha 配置文件之外的所有默认独立配置文件的控制台日志处理程序。自 JBoss EAP 7.1 起,根日志记录器不再包含受管域配置文件的控制台日志处理程序。默认情况下,主机控制器和流程控制器的日志信息在控制台中记录。若要获得 JBoss EAP 7.0 中提供的相同功能,请参阅 JBoss EAP 配置指南中的配置控制台日志处理程序

4.5. Web 服务器配置更改

4.5.1. 将 Web 子系统替换为 Undertow

Undertow 取代 JBoss Web 作为 JBoss EAP 7 中的 Web 服务器。这意味着旧版 Web 子系统配置必须迁移到新的 JBoss EAP 7 undertow 子系统配置。

  • 服务器配置文件中的 urn:jboss:domain:web:2.2 子系统配置命名空间已被 urn:jboss:domain:undertow:10.0 命名空间取代。
  • EAP_HOME/modules/system/layers/base/ 中的 org.jboss.as.web 扩展模块已被 org.wildfly.extension.undertow 扩展模块取代。

您可以使用管理 CLI migrate 操作,将 Web 子系统迁移到服务器配置文件中的 undertow。但是,请注意,此操作无法迁移所有 JBoss Web 子系统配置。如果您看到"migration-warning"条目,则必须运行其他管理 CLI 命令将这些配置迁移到 Undertow。如需有关管理 CLI migrate 操作的更多信息,请参阅管理 CLI 迁移操作

以下是 JBoss EAP 6.4 中默认 Web 子系统配置的示例:

<subsystem xmlns="urn:jboss:domain:web:2.2" default-virtual-server="default-host" native="false">
    <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
    <virtual-server name="default-host" enable-welcome-root="true">
        <alias name="localhost"/>
        <alias name="example.com"/>
    </virtual-server>
</subsystem>

以下是 JBoss EAP 7.4 中默认 undertow 子系统配置的示例:

<subsystem xmlns="urn:jboss:domain:undertow:10.0" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
        <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
        <host name="default-host" alias="localhost">
            <location name="/" handler="welcome-content"/>
            <http-invoker security-realm="ApplicationRealm"/>
        </host>
    </server>
    ...
</subsystem>

4.5.2. 迁移 JBoss Web 重写条件

管理 CLI migrate 操作无法自动迁移重写条件。它们报告为"迁移警告",您必须手动迁移。您可以使用 Undertow Predicates Attributes and Handlers 在 JBoss EAP 7 中创建等效的配置。

以下是包含 rewrite 配置的 JBoss EAP 6 中的 web 子系统配置示例:

<subsystem xmlns="urn:jboss:domain:web:2.2" default-virtual-server="default" native="false">
    <virtual-server name="default" enable-welcome-root="true">
        <alias name="localhost"/>
        <rewrite name="test" pattern="(.*)/toberewritten/(.*)" substitution="$1/rewritten/$2" flags="NC"/>
        <rewrite name="test2" pattern="(.*)" substitution="-" flags="F">
            <condition name="get" test="%{REQUEST_METHOD}" pattern="GET"/>
            <condition name="andCond" test="%{REQUEST_URI}" pattern=".*index.html" flags="NC"/>
        </rewrite>
    </virtual-server>
</subsystem>

按照 管理 CLI 迁移操作 说明启动您的服务器和管理 CLI,然后使用以下命令迁移 web 子系统配置文件:

/subsystem=web:migrate

当您在上述配置上运行 web 操作时,将报告以下"migration-warnings"。

/subsystem=web:migrate
{
    "outcome" => "success",
    "result" => {"migration-warnings" => [
        "WFLYWEB0002: Could not migrate resource {
    \"pattern\" => \"(.*)\",
    \"substitution\" => \"-\",
    \"flags\" => \"F\",
    \"operation\" => \"add\",
    \"address\" => [
        (\"subsystem\" => \"web\"),
        (\"virtual-server\" => \"default-host\"),
        (\"rewrite\" => \"test2\")
    ]
}",
        "WFLYWEB0002: Could not migrate resource {
    \"test\" => \"%{REQUEST_METHOD}\",
    \"pattern\" => \"GET\",
    \"flags\" => undefined,
    \"operation\" => \"add\",
    \"address\" => [
        (\"subsystem\" => \"web\"),
        (\"virtual-server\" => \"default-host\"),
        (\"rewrite\" => \"test2\"),
        (\"condition\" => \"get\")
    ]
}",
        "WFLYWEB0002: Could not migrate resource {
    \"test\" => \"%{REQUEST_URI}\",
    \"pattern\" => \".*index.html\",
    \"flags\" => \"NC\",
    \"operation\" => \"add\",
    \"address\" => [
        (\"subsystem\" => \"web\"),
        (\"virtual-server\" => \"default-host\"),
        (\"rewrite\" => \"test2\"),
        (\"condition\" => \"andCond\")
    ]
}"
    ]}
}

检查服务器配置文件,并且您看到 undertow 子系统的以下配置:

注意

重写配置已被丢弃。

<subsystem xmlns="urn:jboss:domain:undertow:10.0" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other">
     <buffer-cache name="default"/>
     <server name="default-server">
         <http-listener name="http" socket-binding="http"/>
         <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
         <host name="default-host" alias="localhost, example.com">
             <location name="/" handler="welcome-content"/>
         </host>
     </server>
     <servlet-container name="default">
         <jsp-config/>
     </servlet-container>
     <handlers>
         <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
     </handlers>
 </subsystem>

使用管理 CLI 创建过滤器,以取代 undertow 子系统中的重写配置。对于每个命令,您应该可以看到 "{"outcome" SAS "success"}"。

# Create the filters
/subsystem=undertow/configuration=filter/expression-filter="test1":add(expression="path('(.*)/toberewritten/(.*)') -> rewrite('$1/rewritten/$2')")
/subsystem=undertow/configuration=filter/expression-filter="test2":add(expression="method('GET') and path('.*index.html') -> response-code(403)")

# Add the filters to the default server
/subsystem=undertow/server=default-server/host=default-host/filter-ref="test1":add
/subsystem=undertow/server=default-server/host=default-host/filter-ref="test2":add

检查更新的服务器配置文件。JBoss Web 子系统现已完全在 undertow 子系统中进行迁移和配置。

<subsystem xmlns="urn:jboss:domain:undertow:10.0" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="http" socket-binding="http"/>
        <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
        <host name="default-host" alias="localhost, example.com">
            <location name="/" handler="welcome-content"/>
            <filter-ref name="test1"/>
            <filter-ref name="test2"/>
        </host>
    </server>
    <servlet-container name="default">
        <jsp-config/>
    </servlet-container>
    <handlers>
        <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
    </handlers>
    <filters>
        <expression-filter name="test1" expression="path('(.*)/toberewritten/(.*)') -> rewrite('$1/rewritten/$2')"/>
        <expression-filter name="test2" expression="method('GET') and path('.*index.html') -> response-code(403)"/>
    </filters>
</subsystem>

有关如何使用管理 CLI 配置过滤器和处理程序的更多信息,请参阅 JBoss EAP 7 配置指南中的配置 Web 服务器

4.5.3. 迁移 JBoss Web 系统属性

在之前的 JBoss EAP 版本中,系统属性可用于修改默认的 JBoss Web 行为。有关如何在 Undertow 中配置相同行为的详情,请查看 JBoss Web 系统属性迁移参考

4.5.4. 更新 Access Log Header Pattern

从 JBoss EAP 6.4 迁移到 JBoss EAP 7 时,您可能会发现访问日志不再编写预期的"Referer"和"User-agent"值。这是因为 JBoss EAP 6.4 中包含的 JBoss Web 使用 access-log 中的 %{headername}i 模式来记录传入的标头。

示例:访问 JBoss EAP 6.4 中的日志格式

<access-log pattern="%h %l %u %t &quot;%T sec&quot; &quot;%r&quot; %s %b &quot;%{Referer}i&quot; &quot;%{User-agent}i&quot;"/>

随着在 JBoss EAP 7 中使用 Undertow 的更改,传入标头的模式已更改为 %{i,headername}

示例:JBoss EAP 7 中的访问格式标头

<access-log pattern="%h %l %u %t &quot;%T sec&quot; &quot;%r&quot; %s %b &quot;%{i,Referer}&quot; &quot;%{i,User-Agent}&quot;"/>

4.5.5. 迁移 Global Valves

以前 JBoss EAP 版本支持的 valves。valves 是插入到应用的请求处理管道中的自定义类,在 servlet 过滤器之前插入,以更改请求或执行其他处理。

  • 全局 valves 会被插入到所有部署的应用的请求处理管道中,并在服务器配置文件中配置。
  • 身份验证器 valves 验证请求的凭据。
  • 通过扩展 org.apache.catalina.valves.ValveBase 类并配置在 jboss-web.xml 描述符文件的 <valve> 元素中创建自定义应用程序 valves。这些 valve 必须手动迁移。

本节论述了如何迁移全局 valves。本指南的迁移自定义应用程序 Valves 一节介绍了自定义和验证器的迁移。

Undertow(在 JBoss EAP 7 中取代 JBoss Web)不支持全局 valves;但是,您应该能够通过使用 Undertow 处理程序来实现类似的功能。Undertow 包含多个提供常见功能的内置处理程序:它还提供创建自定义处理程序的功能,可用于取代自定义 valve 功能。

如果您的应用使用 valves,则必须将它们替换为适当的 Undertow 处理程序代码,以便在迁移到 JBoss EAP 7 时获得相同的功能。

如需有关如何配置处理程序的更多信息,请参阅 JBoss EAP 7 配置指南中的配置处理程序

如需有关如何配置过滤器的更多信息,请参阅 JBoss EAP 7 配置指南中的配置过滤器

迁移 JBoss Web Valves

下表列出了 JBoss EAP 之前版本中 JBoss Web 提供的 valves,以及对应的 Undertow 内置处理程序:JBoss Web valves 位于 org.apache.catalina.valves 包中。

表 4.2. 将 Valves 映射到处理程序

Valve处理程序

AccessLogValve

io.undertow.server.handlers.accesslog.AccessLogHandler

CrawlerSessionManagerValve

io.undertow.servlet.handlers.CrawlerSessionManagerHandler

ExtendedAccessLogValve

io.undertow.server.handlers.accesslog.AccessLogHandler

JDBCAccessLogValve

相关说明请查看下面的 JDBCAccessLogValve 手动迁移过程

RemoteAddrValve

io.undertow.server.handlers.IPAddressAccessControlHandler

RemoteHostValve

io.undertow.server.handlers.AccessControlListHandler

RemoteIpValve

io.undertow.server.handlers.ProxyPeerAddressHandler

RequestDumperValve

io.undertow.server.handlers.RequestDumpingHandler

RewriteValve

有关手动迁移这些 valve 的说明,请参阅迁移 JBoss Web 重写条件

StuckThreadDetectionValve

io.undertow.server.handlers.StuckThreadDetectionHandler

您可以使用管理 CLI migrate 操作自动迁移满足以下条件的全局 valves:

  • 它们仅限于上表中列出的 valve,不需要手动处理。
  • 它们必须在服务器配置文件的 Web 子系统中定义。

如需有关管理 CLI migrate 操作的更多信息,请参阅管理 CLI 迁移操作

JDBCAccessLogValve 手工迁移过程

org.apache.catalina.valves.JDBCAccessLogValve valve 是规则的例外,无法自动迁移到 io.undertow.server.handlers.JDBCLogHandler。按照以下步骤迁移以下示例 valve。

<valve name="jdbc" module="org.jboss.as.web" class-name="org.apache.catalina.valves.JDBCAccessLogValve">
    <param param-name="driverName" param-value="com.mysql.jdbc.Driver" />
    <param param-name="connectionName" param-value="root" />
    <param param-name="connectionPassword" param-value="password" />
    <param param-name="connectionURL" param-value="jdbc:mysql://localhost:3306/wildfly?zeroDateTimeBehavior=convertToNull" />
    <param param-name="format" param-value="combined" />
</valve>
  1. 为数据库创建一个驱动程序模块,它将存储日志条目。
  2. 配置数据库的数据源,并将驱动程序添加到 datasources 子系统中可用驱动程序的列表中。

    <datasources>
        <datasource jndi-name="java:jboss/datasources/accessLogDS" pool-name="accessLogDS" enabled="true" use-java-context="true">
            <connection-url>jdbc:mysql://localhost:3306/wildfly?zeroDateTimeBehavior=convertToNull</connection-url>
            <driver>mysql</driver>
            <security>
               <user-name>root</user-name>
               <password>Password1!</password>
            </security>
        </datasource>
        ...
        <drivers>
            <driver name="mysql" module="com.mysql">
                <driver-class>com.mysql.jdbc.Driver</driver-class>
            </driver>
        ...
        </drivers>
    </datasources>
  3. undertow 子系统中,使用以下表达式配置 expression-filterjdbc-access-log(datasource=DATASOURCE_JNDI_NAME)

    <filters>
        <expression-filter name="jdbc-access" expression="jdbc-access-log(datasource='java:jboss/datasources/accessLogDS')" />
        ...
    </filters>

4.5.7. 更改 HTTP 方法调用行为

JBoss EAP 6.4(包括 JBoss Web 作为 Web 服务器)默认允许 HTTP TRACE 方法调用。

Undertow(替换 JBoss Web 作为 JBoss EAP 7 中的 Web 服务器)默认不允许 HTTP TRACE 方法调用。此设置使用 undertow 子系统中 http-listener 元素的 disallowed-methods 属性进行配置。可以通过查看以下 read-resource 命令的输出来确认这一点。注意 disallowed-methods 属性的值为 ["TRACE"]

/subsystem=undertow/server=default-server/http-listener=default:read-resource
{
    "outcome" => "success",
    "result" => {
        "allow-encoded-slash" => false,
        "allow-equals-in-cookie-value" => false,
        "allow-unescaped-characters-in-url" => false,
        "always-set-keep-alive" => true,
        "buffer-pipelined-data" => false,
        "buffer-pool" => "default",
        "certificate-forwarding" => false,
        "decode-url" => true,
        "disallowed-methods" => ["TRACE"],
         ...
    }
}

若要在 JBoss EAP 7 及更高版本中启用 HTTP TRACE 方法调用,您必须运行以下命令,从 disallowed-methods 属性列表中删除"TRACE"条目:

/subsystem=undertow/server=default-server/http-listener=default:list-remove(name=disallowed-methods,value="TRACE")

当再次运行 read-resource 命令时,您会注意到 TRACE 方法调用不再在禁止的方法列表中。

/subsystem=undertow/server=default-server/http-listener=default:read-resource
{
    "outcome" => "success",
    "result" => {
        "allow-encoded-slash" => false,
        "allow-equals-in-cookie-value" => false,
        "allow-unescaped-characters-in-url" => false,
        "always-set-keep-alive" => true,
        "buffer-pipelined-data" => false,
        "buffer-pool" => "default",
        "certificate-forwarding" => false,
        "decode-url" => true,
        "disallowed-methods" => [],
         ...
    }
}

如需有关 HTTP 方法默认行为的更多信息,请参阅 JBoss EAP 配置指南中的 HTTP 方法默认行为

4.5.8. 默认 Web 模块行为的更改

在 JBoss EAP 7.0 中,mod_cluster 中默认禁用了 Web 应用的根上下文。

自 JBoss EAP 7.1 起,情况已不再如此。如果您希望禁用根上下文,这可能会造成意外的后果。例如,可以将请求错误路由到不合要求的节点,或者不应公开的私有应用可以通过公共代理意外访问。Undertow 位置现在会自动注册到 mod_cluster 负载平衡器,除非被明确排除。

使用以下管理 CLI 命令,将 ROOT 从 modcluster 子系统配置中排除:

/subsystem=modcluster/mod-cluster-config=configuration:write-attribute(name=excluded-contexts,value=ROOT)

使用以下管理 CLI 命令,禁用默认的欢迎 Web 应用:

/subsystem=undertow/server=default-server/host=default-host/location=\/:remove
/subsystem=undertow/configuration=handler/file=welcome-content:remove
reload

有关如何配置默认欢迎 Web 应用程序的更多信息,请参阅 JBoss EAP 开发指南中的配置默认欢迎 Web 应用

4.5.9. Undertow 子系统默认配置的更改

在 JBoss EAP 7.2 之前,默认的 undertow 子系统配置包含两个响应标头过滤器,它们附加至 default-host 各个 HTTP 响应中。

  • Server,设置为 JBoss-EAP/7
  • X-Powered-By,设置为 Undertow/1

这些响应标头过滤器已从默认的 JBoss EAP 7.2 配置中删除,以防止意外泄漏有关正在使用的服务器的信息。

以下是 JBoss EAP 7.1 中默认 undertow 子系统配置的示例。

<subsystem xmlns="urn:jboss:domain:undertow:4.0">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="default" socket-binding="http" redirect-socket="https"/>
        <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
        <host name="default-host" alias="localhost">
            <location name="/" handler="welcome-content"/>
            <filter-ref name="server-header"/>
            <filter-ref name="x-powered-by-header"/>
            <http-invoker security-realm="ApplicationRealm"/>
        </host>
    </server>
    <servlet-container name="default">
        <jsp-config/>
        <websockets/>
    </servlet-container>
    <handlers>
        <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
    </handlers>
    <filters>
        <response-header name="server-header" header-name="Server" header-value="JBoss-EAP/7"/>
        <response-header name="x-powered-by-header" header-name="X-Powered-By" header-value="Undertow/1"/>
    </filters>
</subsystem>

以下是 JBoss EAP 7.4 中新默认 undertow 子系统配置的示例:

<subsystem xmlns="urn:jboss:domain:undertow:10.0" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
        <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
        <host name="default-host" alias="localhost">
            <location name="/" handler="welcome-content"/>
            <http-invoker security-realm="ApplicationRealm"/>
        </host>
    </server>
    <servlet-container name="default">
        <jsp-config/>
        <websockets/>
    </servlet-container>
    <handlers>
        <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
    </handlers>
</subsystem>

4.6. JGroups 服务器配置更改

4.6.1. JGroups 默认到私有网络接口

在 JBoss EAP 6 默认配置中,JGroups 使用服务器配置文件的 <interfaces> 部分中定义的 public 接口。

由于建议的做法是使用专用网络接口,所以 JGroups 现在默认使用 JBoss EAP 7 中服务器配置文件 <interfaces> 部分中定义的新 private 接口。

4.6.2. JGroups Channels 的变化

JGroups 以 JGroups 通道的形式为 HA 服务提供组通信支持。JBoss EAP 7 向服务器配置文件中的 jgroups 子系统引入了 <channel> 元素。您可以使用管理 CLI 添加、删除或更改 JGroups 频道的配置。

有关如何配置 JGroups 的更多信息,请参阅 JBoss EAP 配置指南中的通过 JGroups 进行集群通信

4.7. Infinispan Server 配置更改

4.7.1. Infinispan 默认缓存配置更改

在 JBoss EAP 6 中,用于 Web 会话复制和 EJB 复制的默认集群缓存是复制的 ASYNC 缓存。这在 JBoss EAP 7 中有所改变。默认集群缓存现在是分布式 ASYNC 缓存。默认情况下,复制的缓存不再配置。如需有关如何添加复制缓存并使其成为默认设置的信息,请参阅 JBoss EAP 配置指南中的配置缓存模式

这仅在使用新的 JBoss EAP 7 默认配置时影响您。如果您从 JBoss EAP 6 迁移配置,则将保留 infinispan 子系统的配置。

4.7.2. Infinispan Cache 策略变化

JBoss EAP 7 中更改了 ASYNC 缓存策略的行为。

在 JBoss EAP 6 中,ASYNC 缓存读取为空闲锁定。虽然它们永远不会被阻止,但这容易产生对陈旧数据的脏读取,例如在故障转移中。这是因为,它将允许对同一用户的后续请求在上一个请求完成之前启动。使用分布式模式时,这种行为是无法接受的,因为集群拓扑更改可能会影响会话关联,并容易产生过时的数据。

在 JBoss EAP 7 中,ASYNC 缓存读取需要锁定。由于它们现在阻止来自同一用户的新请求,直到之前的复制完成前,脏读取会被阻止。

4.7.3. 配置自定义有状态会话 Bean Cache 进行 Passivation

在配置自定义有状态会话 Bean(SFSB)缓存以进行 JBoss EAP 7.1 及更高版本中传递时,请注意以下限制:

  • idle-timeout 属性(在 ejb3 子系统的 infinispan passivation-store 中配置)已在 JBoss EAP 7.1 及更高版本中弃用。JBoss EAP 6.4 支持 eager 钝化,并根据 idle-timeout 值进行钝化。JBoss EAP 7.1 及更高版本支持 lazy 钝化,当达到 max-size 阈值时进行钝化。
  • 在 JBoss EAP 7.1 及更高版本中,由 Jakarta Enterprise Beans 客户端使用的集群名称由通道的实际集群名称决定,如 jgroups 子系统中所配置。
  • JBoss EAP 7.1 及更高版本仍允许您设置 max-size 属性来控制传递阈值。
  • 您不应该在 Jakarta Enterprise Beans 缓存配置中配置驱除或过期。

    • 您应该通过在 ejb3 子系统中使用 passivation-storemax-size 属性来配置驱除。
    • 您应该使用 SFSB Java 源代码中的 @StatefulTimeout 注释或通过在 ejb-jar.xml 文件中指定 stateful-timeout 值来配置到期。

4.7.4. Infinispan Cache 容器传输更改

JBoss EAP 7.0 和更新版本之间的行为更改要求对缓存容器传输协议的任何更新都必须以批处理模式或使用特殊标头来完成。这种行为变化也会影响任何用于管理 JBoss EAP 服务器的工具。

以下是用于在 JBoss EAP 7.0 中配置缓存容器传输协议的管理 CLI 命令示例。

/subsystem=infinispan/cache-container=my:add()
/subsystem=infinispan/cache-container=my/transport=jgroups:add()
/subsystem=infinispan/cache-container=my/invalidation-cache=mycache:add(mode=SYNC)

以下是在 JBoss EAP 7.1 中执行相同配置所需的管理 CLI 命令示例。请注意,命令是以批处理模式执行的。

batch
/subsystem=infinispan/cache-container=my:add()
/subsystem=infinispan/cache-container=my/transport=jgroups:add()
/subsystem=infinispan/cache-container=my/invalidation-cache=mycache:add(mode=SYNC)
run-batch

如果您不希望使用批处理模式,您可以在定义传输时指定操作标头 allow-resource-service-restart=true。请注意,这将重新启动服务,以便操作可以生效,一些服务可能会停止工作,直到服务重启为止。

如果您使用脚本更新缓存容器传输协议,请务必检查它们并添加批处理模式。

4.8. Jakarta Enterprise Beans 服务器配置变化

ejb3 子系统没有 migrate 操作;因此,如果您使用管理 CLI migrate 操作升级其他现有的 JBoss EAP 6.4 配置,请注意 ejb3 子系统配置没有迁移。由于 ejb3 子系统的配置在 JBoss EAP 7 中与 JBoss EAP 6.4 中的配置略有不同,您可能会在部署企业 bean 应用时看到服务器日志中的异常。

重要

如果您使用 JBoss 服务器迁移工具更新服务器配置,ejb3 子系统应配置正确,在部署 Jakarta 企业 Beans 应用程序时,您不应看到任何问题。有关如何配置和运行工具的详情,请参考使用 JBoss 服务器迁移工具

4.8.1. DuplicateServiceException

以下 DuplicateServiceException 是由 JBoss EAP 7 中的缓存更改导致的。

服务器日志中的 DuplicateServiceException

ERROR [org.jboss.msc.service.fail] (MSC service thread 1-3) MSC000001: Failed to start service jboss.deployment.unit."mdb-1.0-SNAPSHOT.jar".cache-dependencies-installer: org.jboss.msc.service.StartException in service jboss.deployment.unit."mdb-1.0-SNAPSHOT.jar".cache-dependencies-installer: Failed to start service
...
Caused by: org.jboss.msc.service.DuplicateServiceException: Service jboss.infinispan.ejb."mdb-1.0-SNAPSHOT.jar".config is already registered

您必须重新配置缓存来解决这个错误。

  1. 按照说明启动服务器和管理 CLI
  2. 发出下列命令,以在 ejb3 子系统中重新配置缓存:

    /subsystem=ejb3/file-passivation-store=file:remove
    /subsystem=ejb3/cluster-passivation-store=infinispan:remove
    /subsystem=ejb3/passivation-store=infinispan:add(cache-container=ejb, max-size=10000)
    
    /subsystem=ejb3/cache=passivating:remove
    /subsystem=ejb3/cache=clustered:remove
    /subsystem=ejb3/cache=distributable:add(passivation-store=infinispan, aliases=[passivating, clustered])

4.8.2. Jakarta Enterprise Beans 子系统服务器配置变化

在 JBoss EAP 7.4 之前,ejb3 子系统中 remote 元素的 connector-ref 属性用于指定单一补救连接器。然后,外部 Jakarta Enterprise Beans 客户端将使用指定的 remoting 连接器连接到服务器。

JBoss EAP 7.4 将 connector-ref 属性替换为 connector 属性。connector 属性从 remoting 子系统获取连接器列表,以便外部 Jakarta Enterprise Beans 客户端可以使用它们连接到服务器。

4.9. 消息传递服务器配置变化

在 JBoss EAP 7 中,ActiveMQ Artemis 取代了 HornetQ 作为 Jakarta 消息传递支持提供商。这部分论述了如何迁移配置和相关消息传递数据。

4.9.1. 消息传递子系统服务器配置变化

org.jboss.as.messaging 模块扩展(位于 EAP_HOME/modules/system/layers/base/)已被 org.wildfly.extension.messaging-activemq 扩展模块替代。

urn:jboss:domain:messaging:3.0 子系统配置命名空间已被 urn:jboss:domain:messaging-activemq:4.0 命名空间替代。

管理模型

大多数情况下,尽量使元素和属性名称与之前发行版中使用的名称相似。下表列出了其中一些更改:

表 4.3. 映射消息传递属性

HornetQ 名称ActiveMQ 名称

hornetq-server

server

hornetq-serverType

serverType

connectors

connector

discovery-group-name

discovery-group

messaging-activemq 子系统调用的管理操作已从 /subsystem=messaging/hornetq-server= 更改为 /subsystem=messaging-activemq/server=

您可以通过调用 migrate 操作,将现有的 JBoss EAP 6 messaging 子系统配置迁移到 JBoss EAP 7 服务器上的 messaging-activemq 子系统。

/subsystem=messaging:migrate

在执行 migrate 操作之前,您可以调用 describe-migration 操作,以检查要执行的管理操作列表,以便从现有 JBoss EAP 6 messaging 子系统配置迁移到 JBoss EAP 7 服务器上的 messaging-activemq 子系统。

/subsystem=messaging:describe-migration

migratedescribe-migration 操作还会显示无法自动迁移的资源或属性的 migration-warnings 列表。

消息传递子系统迁移和提升兼容性

describe-migrationmigration 操作为 messaging 子系统提供了额外的配置参数。如果您要将消息传递配置为允许旧版 JBoss EAP 6 客户端连接 JBoss EAP 7 服务器,您可以按照如下所示将布尔值 add-legacy-entries 参数添加到 describe-migrationmigrate 操作:

/subsystem=messaging:describe-migration(add-legacy-entries=true)
/subsystem=messaging:migrate(add-legacy-entries=true)

如果布尔值参数 add-legacy-entries 设为 truemessaging-activemq 子系统将创建 legacy-connection-factory 资源,并将 legacy-entries 添加到 jms-queuejms-topic 资源。

如果布尔值参数 add-legacy-entries 设为 false,则 messaging-activemq 子系统中不会创建传统资源,并且传统的消息传递客户端将无法与 JBoss EAP 7 服务器通信。这是默认值。

有关正向和向后兼容性的更多信息,请参阅为 JBoss EAP 配置 Messaging 中的向后和提升兼容性

如需有关管理 CLI migratedescribe-migration 的更多信息,请参阅管理 CLI 迁移操作

forward-when-no-sumers 属性的行为变化

JBoss EAP 7 中的 forward-when-no-consumers 属性的行为已经改变。

在 JBoss EAP 6 中,当 forward-when-no- Consumers 设置为 false 时,当集群中没有消费者时,消息会被重新分发到群集中的所有节点。

JBoss EAP 7 中已更改此行为。如果 forward-when-no-consumers 设为 false,且集群中没有使用者,则信息不会被重新分发。相反,它们会被保留在发送到的原始节点上。

默认集群负载均衡策略更改

JBoss EAP 7 中的默认群集负载平衡策略已更改。

在 JBoss EAP 6 中,默认的群集负载平衡策略类似于 STRICT,后者类似于将旧的 forward-when-no-consumers 参数设置为 true。在 JBoss EAP 7 中,默认值现在是 ON_DEMAND,它类似于将旧的 forward-when-no-consumers 参数设置为 false。有关这些设置的更多信息,请参阅为 JBoss EAP 配置 Messaging 中的集群连接属性

消息传递子系统 XML 配置

XML 配置已根据新的 messaging-activemq 子系统进行了显著更改,现在提供的 XML 架构与其他 JBoss EAP 子系统更加一致。

强烈建议您不要尝试修改 JBoss EAP messaging 子系统 XML 配置,以符合新的 messaging-activemq 子系统。相反,可调用传统的子系统 migrate 操作。此操作将编写新的 messaging-activemq 子系统的 XML 配置,作为其执行的一部分。

4.9.2. 迁移消息传递数据

您可以使用以下方法之一将消息传递数据从上一版本迁移到 JBoss EAP 的当前版本:

  • 对于基于文件的消息传递系统,您可以使用导出和导入方法将消息传递数据从 JBoss EAP 6.4 和之前的 JBoss EAP 7.x 版本迁移到 JBoss EAP 7.4。使用此方法,您可以导出来自上一发行版本的消息传递数据,并使用管理 CLI import-journal 操作导入数据。请注意,您只能在基于文件的消息传递系统中使用此方法。
  • 您可以通过配置 Jakarta 消息传递网桥,将消息传递数据从 JBoss EAP 6.4 迁移到 JBoss EAP 7.4。您可以将这种方法用于基于文件和 JDBC 消息传递系统。

由于作为 Jakarta 消息传递支持提供商从 HornetQ 更改为 ActiveMQ Artemis,消息传递数据的格式和位置在 JBoss EAP 7.0 及更高版本中发生变化。如需了解有关消息传递数据文件夹名称和 6.4 和 7.x 版本之间的位置的更改的详细信息,请参阅映射消息传递文件夹名称

4.9.2.1. 使用导出和导入来迁移消息传递数据

使用此方法,您可以将之前版本的消息传递数据导出到 XML 文件,然后使用 import-journal 操作导入该文件。

重要

您不能使用导出和导入方法在使用基于 JDBC 的日志进行存储的系统之间移动消息传递数据。

从 JBoss EAP 6.4 导出消息传递数据

由于消息传递支持提供商从 HornetQ 更改为 ActiveMQ Artemis,消息传递数据的格式和位置在 JBoss EAP 7.0 及更高版本中有所变化。

要从 JBoss EAP 6.4 导出消息传递数据,您必须使用 HornetQ exporter 实用程序。HornetQ exporter 实用程序生成消息传递数据并将其导出从 JBoss EAP 6.4 到 XML 文件。此命令要求您指定 JBoss EAP 6.4 随附的所需 HornetQ JAR 的路径,将路径传递到 messagingbindings/messagejournal/messagepaging/messaginglargemessages/ 文件夹作为参数,并指定输出文件,在其中编写导出的 XML 数据。

以下是 HornetQ exporter 程序所需的语法。

$ java -jar -mp MODULE_PATH org.hornetq.exporter MESSAGING_BINDINGS_DIRECTORY MESSAGING_JOURNAL_DIRECTORY MESSAGING_PAGING_DIRECTORY MESSAGING_LARGE_MESSAGES_DIRECTORY > OUTPUT_DATA.xml

创建自定义模块,以确保正确版本的 HornetQ JAR(包括安装有补丁或升级的任何 JAR)已加载并提供给 exporter 实用程序。使用您首选的编辑器,在 EAP6_HOME/modules/org/hornetq/exporter/main/ 目录中创建一个新的 module.xml 文件并复制以下内容:

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.1" name="org.hornetq.exporter">
    <main-class name="org.hornetq.jms.persistence.impl.journal.XmlDataExporter"/>
    <properties>
        <property name="jboss.api" value="deprecated"/>
    </properties>
    <dependencies>
        <module name="org.hornetq"/>
    </dependencies>
</module>
注意

自定义模块是在 modules/ 目录中创建的,而不是 module/system/layers/base/ 目录。

按照以下步骤导出数据。

  1. 停止 JBoss EAP 6.4 服务器。
  2. 如上所述,创建自定义模块。
  3. 运行以下命令以导出数据:

    $ java -jar jboss-modules.jar -mp modules/ org.hornetq.exporter standalone/data/messagingbindings/ standalone/data/messagingjournal/ standalone/data/messagingpaging standalone/data/messaginglargemessages/ > OUTPUT_DIRECTORY/OldMessagingData.xml
  4. 确保完成 命令时,日志中没有任何错误或警告消息。
  5. 使用您的操作系统可用的工具来验证所生成输出文件中的 XML。
从 JBoss EAP 7.x 导出消息传递数据

按照以下步骤导出来自 JBoss EAP 7.x 的消息传递数据。

  1. 打开一个终端,前往 JBoss EAP 7.x 安装目录,再以 admin-only 模式启动服务器。

    $ EAP_HOME/bin/standalone.sh -c standalone-full.xml --start-mode=admin-only
  2. 打开一个新终端,前往 JBoss EAP 7.x 安装目录,再连接管理 CLI。

    $ EAP_HOME/bin/jboss-cli.sh --connect
  3. 使用以下管理 CLI 命令导出消息传递日志数据:

    /subsystem=messaging-activemq/server=default:export-journal()
  4. 确保完成 命令时,日志中没有任何错误或警告消息。
  5. 使用您的操作系统可用的工具来验证所生成输出文件中的 XML。
导入 XML 格式的消息传递数据

然后,您将 XML 文件导入到 JBoss EAP 7.0 或更高版本,按照如下所示使用 import-journal 操作:

重要

如果您的目标服务器已执行一些消息传递任务,请务必在开始 import-journal 操作前备份您的消息传递文件夹,以防止导入失败时出现数据丢失。如需更多信息,请参阅备份消息传递文件夹数据

  1. 如果要将 JBoss EAP 6.4 服务器迁移至 JBoss EAP 7.4,请确保已完成服务器配置迁移,然后再使用管理 CLI 迁移操作或运行 JBoss 服务器迁移工具。有关如何配置和运行工具的详情,请参考使用 JBoss 服务器迁移工具
  2. 以正常模式启动 JBoss EAP 7.x 服务器,但没有连接 Jakarta 消息传递客户端。

    重要

    您在没有连接 Jakarta 消息传递客户端的情况下启动服务器非常重要。这是因为,import-journal 操作的行为类似于 Jakarta 消息传递制作者。操作过程中,消息会立即可用。如果此操作在导入期间失败,并且连接了 Jakarta 消息传递客户端,则无法恢复,因为 Jakarta 消息传递客户端可能已经消耗了一些消息。

  3. 打开一个新终端,前往 JBoss EAP 7.x 安装目录,再连接管理 CLI。

    $ EAP_HOME/bin/jboss-cli.sh --connect
  4. 使用以下管理 CLI 命令导入消息传递数据:

    /subsystem=messaging-activemq/server=default:import-journal(file=OUTPUT_DIRECTORY/OldMessagingData.xml)
    重要

    不要多次运行此命令,因为这样做会导致重复的消息!

    警告

    如果您使用 JBoss EAP 7.0,您必须对 JBoss EAP 安装应用 Red Hat JBoss Enterprise Application Platform 7.0 Update 05 或较新的累积修补程序,以避免读取大量消息时已知问题。如需更多信息,请参阅 JBEAP-4407 - Consumer crashes with IndexOutOfBoundsException when reading large messages from imported journal

    此问题不会影响 JBoss EAP 7.1 及更高版本。

从导入的消息传递数据失败中恢复

如果 import-journal 操作失败,您可以按照以下步骤尝试恢复。

  1. 关闭 JBoss EAP 7.x 服务器。
  2. 删除所有消息传递日志文件夹。请参阅管理 CLI 命令备份消息传递文件夹数据,以确定消息传递日志文件夹的正确目录位置。
  3. 如果您在导入前备份了目标服务器消息传递数据,请将消息传递文件夹从备份位置复制到在上一步中确定的消息传递日志目录。
  4. 重复上述步骤,以导入 XML 格式的消息传递数据

4.9.2.2. 使用消息传递网桥迁移消息传递数据

使用此方法,您可以配置消息传递网桥并部署到 JBoss EAP 7.x 服务器。此网桥将消息从 JBoss EAP 6.4 HornetQ 队列移动到 JBoss EAP 7.x ActiveMQ Artemis 队列。

Jakarta 消息传递网桥使用来自源 Jakarta Messaging 队列或主题的消息,将它们发送到目标 Jakarta 消息传递队列或主题,后者通常位于不同的服务器上。它可用于在任何消息传递服务器之间桥接消息,只要它们兼容 JMS 1.1。使用 Java 命名和目录接口查找来源和目的地 Jakarta 消息传递资源,并且 Java 命名和目录接口查找的客户端类必须捆绑到模块中。然后,在 Jakarta 消息传递网桥配置中声明模块名称。

本节介绍如何配置服务器和部署消息传递网桥,将消息传递数据从 JBoss EAP 6.4 移到 JBoss EAP 7.x。

配置源 JBoss EAP 6.4 服务器
  1. 停止 JBoss EAP 6.4 服务器。
  2. 备份 HornetQ 日志和配置文件。

    • 默认情况下,HornetQ 日志位于 EAP6_HOME/standalone/data/ 目录中。
    • 请参阅每个发行版本的默认消息传递文件夹位置映射消息传递文件夹名称
  3. 确保 JBoss EAP 6.4 服务器上定义了包含 JMS 消息的 InQueue JMS 队列。
  4. 确保 messaging 子系统配置包含 RemoteConnectionFactory 的条目,如下所示:

    <connection-factory name="RemoteConnectionFactory">
        <entries>
            <entry name="java:jboss/exported/jms/RemoteConnectionFactory"/>
        </entries>
        ...
    </connection-factory>

    如果没有包含该条目,请使用以下管理 CLI 命令创建一个:

    /subsystem=messaging/hornetq-server=default/connection-factory=RemoteConnectionFactory:add(factory-type=XA_GENERIC, connector=[netty], entries=[java:jboss/exported/jms/RemoteConnectionFactory],ha=true,block-on-acknowledge=true,retry-interval=1000,retry-interval-multiplier=1.0,reconnect-attempts=-1)
配置目标 JBoss EAP 7.x 服务器
  1. Jakarta 消息传递网桥配置需要 org.hornetq 模块连接到上一发行版中的 HornetQ 服务器。JBoss EAP 7.x 中不存在此模块及其直接依赖项,因此您必须从上一发行版中复制以下模块:

    • org.hornetq 模块复制到 JBoss EAP 7.x EAP_HOME/modules/org/ 目录中。

      • 如果您没有在此模块应用补丁,请从 JBoss EAP 6.4 服务器复制此文件夹:EAP6_HOME/modules/system/layers/base/org/hornetq/
      • 如果您已将补丁应用到此模块,请从 JBoss EAP 6.4 服务器复制此文件夹:EAP6_HOME/modules/system/layers/base/.overlays/layer-base-jboss-eap-6.4.x.CP/org/hornetq/
    • 从 JBoss EAP 7.x EAP_HOME/modules/org/hornetq/main/module.xml 文件中为 HornetQ lib 路径删除 <resource-root>

      • 如果您没有将补丁应用到 JBoss EAP 6.4 org.hornetq 模块,从文件中删除以下行:

        <resource-root path="lib"/>
      • 如果您将补丁应用到 JBoss EAP 6.4 org.hornetq 模块,从文件中删除以下行:

        <resource-root path="lib"/>
        <resource-root path="../../../../../org/hornetq/main/lib"/>
        警告

        如果不删除 HornetQ lib path resource-root 将导致网桥失败,在日志文件中出现以下错误:

        2016-07-15 09:32:25,660 ERROR [org.jboss.as.controller.management-operation] (management-handler-thread - 2) WFLYCTL0013: Operation ("add") failed - address: ([
            ("subsystem" => "messaging-activemq"),
            ("jms-bridge" => "myBridge")
        ]) - failure description: "WFLYMSGAMQ0086: Unable to load module org.hornetq"
    • org.jboss.netty 模块复制到 JBoss EAP 7.x EAP_HOME/modules/org/jboss/ 目录中。

      • 如果您没有将补丁应用到此模块,请从 JBoss EAP 6.4 服务器复制此文件夹: EAP6_HOME/modules/system/layers/base/org/jboss/netty/
      • 如果您已将补丁应用到此模块,请从 JBoss EAP 6.4 服务器复制此文件夹:EAP6_HOME/modules/system/layers/base/.overlays/layer-base-jboss-eap-6.4.x.CP/org/jboss/netty
  2. 创建 Jakarta Messaging 队列,以包含 JBoss EAP 6.4 服务器接收的消息。以下是一个管理 CLI 命令的示例,它可创建 MigratedMessagesQueue Jakarta Messaging 队列来接收消息。

    jms-queue add --queue-address=MigratedMessagesQueue --entries=[jms/queue/MigratedMessagesQueue java:jboss/exported/jms/queue/MigratedMessagesQueue]

    这会在 JBoss EAP 7.x 服务器的 messaging-activemq 子系统中为默认服务器创建以下 jms-queue 配置。

    <jms-queue name="MigratedMessagesQueue" entries="jms/queue/MigratedMessagesQueue java:jboss/exported/jms/queue/MigratedMessagesQueue"/>
  3. 确保 messaging-activemq 子系统 默认 服务器包含 InVmConnectionFactory connection-factory 的配置,类似于以下内容:

    <connection-factory name="InVmConnectionFactory" factory-type="XA_GENERIC" entries="java:/ConnectionFactory" connectors="in-vm"/>

    如果没有包含该条目,请使用以下管理 CLI 命令创建一个:

    /subsystem=messaging-activemq/server=default/connection-factory=InVmConnectionFactory:add(factory-type=XA_GENERIC, connectors=[in-vm], entries=[java:/ConnectionFactory])
  4. 创建并部署 Jakarta Messaging 网桥,从 JBoss EAP 6.4 服务器上配置的 InQueue JMS 队列读取消息,并将它们传送到 JBoss EAP 7.x 服务器上配置的 MigratedMessagesQueue

    /subsystem=messaging-activemq/jms-bridge=myBridge:add(add-messageID-in-header=true,max-batch-time=100,max-batch-size=10,max-retries=-1,failure-retry-interval=1000,quality-of-service=AT_MOST_ONCE,module=org.hornetq,source-destination=jms/queue/InQueue,source-connection-factory=jms/RemoteConnectionFactory,source-context=[("java.naming.factory.initial"=>"org.wildfly.naming.client.WildFlyInitialContextFactory"),("java.naming.provider.url"=>"remote://127.0.0.1:4447")],target-destination=jms/queue/MigratedMessagesQueue,target-connection-factory=java:/ConnectionFactory)

    这会在 JBoss EAP 7.x 服务器的 messaging-activemq 子系统中创建以下 jms-bridge 配置。

    <jms-bridge name="myBridge" add-messageID-in-header="true" max-batch-time="100" max-batch-size="10" max-retries="-1" failure-retry-interval="1000" quality-of-service="AT_MOST_ONCE" module="org.hornetq">
        <source destination="jms/queue/InQueue" connection-factory="jms/RemoteConnectionFactory">
            <source-context>
                <property name="java.naming.factory.initial" value="org.wildfly.naming.client.WildFlyInitialContextFactory"/>
                <property name="java.naming.provider.url" value="remote://127.0.0.1:4447"/>
            </source-context>
        </source>
        <target destination="jms/queue/MigratedMessagesQueue" connection-factory="java:/ConnectionFactory"/>
    </jms-bridge>
  5. 如果为 JBoss EAP 6.4 配置了安全性,还必须将消息传递网桥配置 <source> 元素配置为包含一个 source-context,用于指定在创建连接时用于 Java Naming 和 Directory Interface 查找的正确用户名和密码。
迁移消息传递数据
  1. 验证您为以下配置提供的信息正确。

    • 任何队列和主题名称。
    • java.naming.provider.url 用于 Java 命名和目录接口查找。
  2. 确保您已将目标 Jakarta Messaging 目的地部署到 JBoss EAP 7.x 服务器。
  3. 启动 JBoss EAP 6.4 和 JBoss EAP 7.x 服务器。

4.9.2.3. 映射消息文件夹名称

下表显示了上一版本中使用的消息传递目录名以及 JBoss EAP 当前发行版本中使用的对应名称。目录相对于 jboss.server.data.dir 目录,如果未指定,则默认为 EAP_HOME/standalone/data/

JBoss EAP 6.4 目录名称JBoss EAP 7.x 目录名称

messagingbindings/

activemq/bindings/

messagingjournal/

activemq/journal/

messaginglargemessages/

activemq/largemessages/

messagingpaging/

activemq/paging/

注意

如果没有大型消息或者页面被禁用,则 messaginglargemessages/messagingpaging/ 目录可能不存在。

4.9.2.4. 备份消息文件夹数据

如果您的目标服务器已经处理了消息,最好在开始前将目标消息文件夹备份到备份位置。消息传递文件夹的默认位置是 EAP_HOME/standalone/data/activemq/,但它是可配置的。如果您不确定消息传递数据的位置,您可以使用以下管理 CLI 命令查找消息传递文件夹的位置。

/subsystem=messaging-activemq/server=default/path=journal-directory:resolve-path
/subsystem=messaging-activemq/server=default/path=paging-directory:resolve-path
/subsystem=messaging-activemq/server=default/path=bindings-directory:resolve-path
/subsystem=messaging-activemq/server=default/path=large-messages-directory:resolve-path

知道文件夹的位置后,将每个文件夹复制到安全备份位置。

4.9.3. 迁移消息目的地

在 JBoss EAP 6 中,消息传递目的地队列在 messaging 子系统的 <hornetq-server> 元素下的 <jms-destinations> 元素中配置。

<hornetq-server>
  ...
  <jms-destinations>
     <jms-queue name="testQueue">
        <entry name="queue/test"/>
         <entry name="java:jboss/exported/jms/queue/test"/>
      </jms-queue>
  </jms-destinations>
  ...
</hornetq-server>

在 JBoss EAP 7 中,Jakarta Messaging 目的地队列在 messaging-activemq 子系统的默认 <server> 元素中配置。

<server name="default">
  ...
  <jms-queue name="testQueue" entries="queue/test java:jboss/exported/jms/queue/test"/>
  ...
</server>

4.9.4. 迁移消息拦截器

在 JBoss EAP 7 中,消息拦截器已显著改变,它替代了 ActiveMQ为 Jakarta Messaging 提供者。

JBoss EAP 前面发行版本中的 HornetQ messaging 子系统要求您通过将 HornetQ 拦截器添加到 JAR,然后修改 HornetQ module.xml 文件。

JBoss EAP 7 中包含的 messaging-activemq 子系统不需要修改 module.xml 文件。用户拦截器类现在可以从任何服务器模块加载 Apache ActiveMQ ActiveMQ Interceptor 接口。您可以指定拦截器应加载在服务器配置文件的 messaging-activemq 子系统中的模块。

示例: Interceptor 配置

<subsystem xmlns="urn:jboss:domain:messaging-activemq:4.0">
  <server name="default">
    ...
    <incoming-interceptors>
      <class name="com.mycompany.incoming.myInterceptor" module="com.mycompany" />
      <class name="com.othercompany.incoming.myOtherInterceptor" module="com.othercompany" />
    </incoming-interceptors>
    <outgoing-interceptors>
      <class name="com.mycompany.outgoing.myInterceptor" module="com.mycompany" />
      <class name="com.othercompany.outgoing.myOtherInterceptor" module="com.othercompany" />
    </outgoing-interceptors>
  </server>
</subsystem>

4.9.5. 替换 Netty Servlet 配置

在 JBoss EAP 6 中,您可以配置 servlet 引擎以用于 Netty Servlet 传输。由于 ActiveMQ6.3 取代了 JBoss EAP 7 中的内置消息传递提供程序,因此该配置不再可用。您必须替换 servlet 配置,以使用新的内置消息传递 HTTP 连接器和 HTTP 接受器。

4.9.6. 配置通用 Jakarta 消息传递资源适配器

您在 JBoss EAP 7 中配置了通用 Jakarta Messaging 资源适配器的方式,在 JBoss EAP 7 中更改了用于第三方 Jakarta 消息传递供应商。如需更多信息,请参阅为 JBoss EAP 配置 消息传递资源适配器部署通用 Jakarta 消息传递 资源适配器。

4.9.7. 消息传递配置更改

在 JBoss EAP 7.0 中,如果您配置了 复制策略 而不指定 check-for-live-server 属性,则默认值为 false。JBoss EAP 7.1 及更高版本中发生了这一变化。check-for-live-server 属性的默认值现在是 true

以下是一个管理 CLI 命令的示例,它可在不指定 check-for-live-server 属性的情况下配置 replication-master 策略。

/subsystem=messaging-activemq/server=default/ha-policy=replication-master:add(cluster-name=my-cluster,group-name=group1)

当您使用管理 CLI 读取资源时,请注意 check-for-live-server 属性值被设置为 true

/subsystem=messaging-activemq/server=default/ha-policy=replication-master:read-resource(recursive=true)
{
    "outcome" => "success",
    "result" => {
        "check-for-live-server" => true,
        "cluster-name" => "my-cluster",
        "group-name" => "group1",
        "initial-replication-sync-timeout" => 30000L
    },
    "response-headers" => {"process-state" => "reload-required"}
}

4.9.8. JMS 和 Jakarta Messaging Serialization Behavior 在发行版本间的更改

javax.jms.JMSExceptionserialVersionUID 在 JMS 1.1 和 JMS 2.0.0 之间更改。这意味着,如果 JMSException 实例或其任何子类的实例使用 JMS 1.1 进行序列化,则无法使用 JMS 2.0.0 进行反序列化。反向也是 true。如果 JMSException 实例使用 JMS 2.0.0 序列化,则无法使用 JMS 1.1 来反序列化。在这两个情形中,它会抛出类似如下的异常:

javax.jms.JMSException: javax.jms.JMSException; local class incompatible: stream classdesc serialVersionUID = 8951994251593378324, local class serialVersionUID = 2368476267211489441

这个问题已在 Jakarta Messaging 2.0.1 维护发行版本中解决。

注意

JMS 2.0.1 规范与 Jakarta Messaging 2.0.3 规范兼容。

以下列出了每个 JBoss EAP 版本的实施:

表 4.4. 每个 JBoss EAP 版本实施

JBoss EAP 版本实施版本

6.4

HornetQ

JMS 1.1

7.0

Apache ActiveMQ Artemis

JMS 2.0.0

7.1 及更新的版本

Apache ActiveMQ Artemis

jakarta Messaging 2.0.3 或更高版本

请注意,serialVersionUID 不兼容性可能会导致在以下情况下出现迁移问题:

  • 如果您使用 JBoss EAP 6.4 客户端发送包含 JMSException 的消息,请将您的消息传递数据迁移到 JBoss EAP 7.0,然后尝试使用 JBoss EAP 7.0 客户端反序列化该消息,反序列化将会失败,并且会引发异常。这是因为 JMS 1.1 中的 serialVersionUID 与 JMS 2.0.0 中的 serialVersionUID 不兼容
  • 如果您使用 JBoss EAP 7.0 客户端发送包含 JMSException 的消息,请将您的消息传递数据迁移到 JBoss EAP 7.1 或更高版本,然后尝试使用 JBoss EAP 7.1 或更高版本的客户端来反序列化该消息,并且会引发异常。这是因为 JMS 2.0.0 中的 serialVersionUID 与 Jakarta Messaging 2.0.3 或更高版本中的版本 不兼容

请注意,如果您使用 JBoss EAP 6.4 客户端发送包含 JMSException 的消息,请将您的消息传递数据迁移到 JBoss EAP 7.1 或更高版本,然后尝试使用 JBoss EAP 7.1 或更高版本的客户端对消息进行反序列化化,因为 JMS 1.1 中的 serialVersionUID 与 Jakarta Messaging 2.0.3 中的 serialVersionUID 兼容。

重要

红帽建议您在迁移消息传递数据前执行以下操作:

  • 在将消息从 JBoss EAP 6.4 迁移到 JBoss EAP 7.0 之前,请务必使用包含 JMSException 的所有 JMS 1.1 消息。
  • 在将 JBoss EAP 7.0 的消息传递数据从 JBoss EAP 7.0 迁移到 JBoss EAP 7.1 或更高版本之前,请务必使用包含 Jakarta Messaging Exception 的所有 Jakarta Messaging 2.0.3 消息。

4.10. JMX 管理与 Jakarta 管理的变化

JBoss EAP 6 中的 HornetQ 组件提供自己的 JMX 管理,但不推荐使用它。它现已被弃用,并不再被支持。如果您依赖于 JBoss EAP 6 中的此功能,您必须迁移管理工具以使用 JBoss EAP 管理 CLI 或 JBoss EAP 7 提供的 Jakarta 管理管理。

您还需要升级客户端库,以使用 JBoss EAP 7 附带的 jboss-client.jar

以下是 JBoss EAP 6 中使用的 HornetQ JMX 管理代码的示例。

JMXConnector connector = null;
try {
    HashMap environment = new HashMap();
    String[] credentials = new String[]{"admin", "Password123!"};
    environment.put(JMXConnector.CREDENTIALS, credentials);

    // HornetQ used the protocol "remoting-jmx" and port "9999"
    JMXServiceURL beanServerUrl = new JMXServiceURL("service:jmx:remoting-jmx://127.0.0.1:9990");

    connector = JMXConnectorFactory.connect(beanServerUrl, environment);
    MBeanServerConnection mbeanServer = connector.getMBeanServerConnection();

    // The JMX object name pointed to the HornetQ JMX management
    ObjectName objectName = new ObjectName("org.hornetq:type=Server,module=JMS");

    // The invoked method name was "listConnectionIDs"
    String[] connections = (String[]) mbeanServer.invoke(objectName, "listConnectionIDs", new Object[]{}, new String[]{});
    for (String connection : connections) {
        System.out.println(connection);
    }
} finally {
    if (connector != null) {
      connector.close();
   }
}

以下示例是 JBoss EAP 7 中 ActiveMQ EFK 所需的等效代码。

JMXConnector connector = null;
try {
    HashMap environment = new HashMap();
    String[] credentials = new String[]{"admin", "Password123!"};
    environment.put(JMXConnector.CREDENTIALS, credentials);

    // ActiveMQ Artemis uses the protocol "remote+http" and port "9990"
    JMXServiceURL beanServerUrl = new JMXServiceURL("service:jmx:remote+http://127.0.0.1:9990");

    connector = JMXConnectorFactory.connect(beanServerUrl, environment);
    MBeanServerConnection mbeanServer = connector.getMBeanServerConnection();

    // The Jakarta Management object name points to the new Jakarta Management in the `messaging-activemq` subsystem
    ObjectName objectName = new ObjectName("jboss.as:subsystem=messaging-activemq,server=default");

    // The invoked method name is now "listConnectionIds"
    String[] connections = (String[]) mbeanServer.invoke(objectName, "listConnectionIds", new Object[]{}, new String[]{});
    for (String connection : connections) {
        System.out.println(connection);
    }
} finally {
    if (connector != null) {
      connector.close();
   }
}

请注意,在新实现中更改了方法名称和参数。您可以按照以下步骤在 JConsole 中找到新方法名称。

  1. 使用以下命令连接到 JConsole。

    $ EAP_HOME/bin/jconsole.sh
  2. 连接到 JBoss EAP 本地进程。请注意,它应当以 "jboss-modules.jar" 开头。
  3. MBeans 选项卡中,选择 jboss.asmessaging-activemqdefaultOperations 以显示方法名称和属性列表。

4.11. ORB 服务器配置更改

JacORB 实施已被 JBoss EAP 7 中的 OpenJDK ORB 的下游分支替代。

EAP_HOME/modules/system/layers/base/ 中的 org.jboss.as.jacorb 扩展模块已被 org.wildfly.iiop-openjdk 扩展模块替代。

服务器配置文件中的 urn:jboss:domain:jacorb:1.4 子系统配置命名空间已被 urn:jboss:domain:iiop-openjdk:2.1 命名空间替代。

以下是 JBoss EAP 6 中默认 jacorb 系统配置的示例。

<subsystem xmlns="urn:jboss:domain:jacorb:1.4">
    <orb socket-binding="jacorb" ssl-socket-binding="jacorb-ssl">
        <initializers security="identity" transactions="spec"/>
    </orb>
</subsystem>

以下是 JBoss EAP 7 中默认 iiop-openjdk 子系统配置的示例。

<subsystem xmlns="urn:jboss:domain:iiop-openjdk:2.1">
    <orb socket-binding="jacorb" ssl-socket-binding="jacorb-ssl" />
    <initializers security="identity" transactions="spec" />
</subsystem>

新的 iiop-openjdk 子系统配置仅接受传统元素和属性的子集。以下是 JBoss EAP 上一发行版本中的 jacorb 子系统配置示例,其中包含所有有效的元素和属性:

<subsystem xmlns="urn:jboss:domain:jacorb:1.4">
   <orb name="JBoss" print-version="off" use-imr="off" use-bom="off"  cache-typecodes="off"
       cache-poa-names="off" giop-minor-version="2" socket-binding="jacorb" ssl-socket-binding="jacorb-ssl">
       <connection retries="5" retry-interval="500" client-timeout="0" server-timeout="0"
           max-server-connections="500" max-managed-buf-size="24" outbuf-size="2048"
           outbuf-cache-timeout="-1"/>
       <initializers security="off" transactions="spec"/>
   </orb>
   <poa monitoring="off" queue-wait="on" queue-min="10" queue-max="100">
       <request-processors pool-size="10" max-threads="32"/>
   </poa>
   <naming root-context="JBoss/Naming/root" export-corbaloc="on"/>
   <interop sun="on" comet="off" iona="off" chunk-custom-rmi-valuetypes="on"
       lax-boolean-encoding="off" indirection-encoding-disable="off" strict-check-on-tc-creation="off"/>
   <security support-ssl="off" add-component-via-interceptor="on" client-supports="MutualAuth"
       client-requires="None" server-supports="MutualAuth" server-requires="None"/>
   <properties>
       <property name="some_property" value="some_value"/>
   </properties>
</subsystem>

以下元素属性不再被支持且必须被删除。

表 4.5. 要删除的属性

元素不支持的属性

<orb>

  • client-timeout
  • max-managed-buf-size
  • max-server-connections
  • outbuf-cache-timeout
  • outbuf-size
  • 连接重试
  • retry-interval
  • name
  • server-timeout

<poa>

  • queue-min
  • queue-max
  • pool-size
  • max-threads

以下 on/off 属性不再被支持,在运行管理 CLI 迁移操作时不会迁移。如果设置为 on,您将会收到迁移警告。此表中未提及 的其他/关闭 属性(如 < security support-ssl="on|off"&gt;)仍被支持,并会被成功迁移。唯一的区别是,其值将从 on/off 更改为 true/false

表 4.6. 被关闭或删除的属性

元素设置为 Off 的属性

<orb>

  • cache-poa-names
  • cache-typecodes
  • print-version
  • use-bom
  • use-imr

<interop>

(除 sun外的所有内容)

  • comet
  • iona
  • chunk-custom-rmi-valuetypes
  • indirection-encoding-disable
  • lax-boolean-encoding
  • strict-check-on-tc-creation

<poa>

  • 监控
  • queue-wait

4.12. 迁移线程子系统配置

JBoss EAP 6 服务器配置包含一个 threads 子系统,用于管理服务器中各种子系统中的线程池。

JBoss EAP 7 中不再提供 threads 子系统。相反,每个子系统负责管理自己的线程池。

有关如何为 infinispan 子系统配置线程池的详情,请参考 JBoss EAP 配置指南中的配置 Infinispan Thread Pools

有关如何为 jgroups 子系统配置线程池的信息,请参阅 JBoss EAP 配置指南中的 Configure JGroups Thread Pools

在 JBoss EAP 6 中,您可以通过引用在 threads 子系统中定义的 executor,为 web 子系统配置连接器和监听程序。在 JBoss EAP 7 中,您现在通过引用 io 子系统中定义的 workerundertow 子系统配置线程池。有关更多信息,请参阅 JBoss EAP 配置指南中的配置 IO 子系统

有关在 remoting 子系统中更改线程池配置的详情,请参考本指南中的 Addmoting subsystem Configuration,以及配置 JBoss EAP 配置 指南中的 Endpoint

4.13. 迁移删除子系统配置

在 JBoss EAP 6 中,您可以通过设置各种 worker-* 属性来配置 remoting 子系统的线程池。JBoss EAP 7 中的 remoting subsystem 中不再配置 worker 线程池,如果尝试修改现有配置,您会看到以下消息:

WFLYRMT0022: Worker configuration is no longer used, please use endpoint worker configuration

在 JBoss EAP 7 中,worker 线程池被替换为引用 io 子系统中定义的 worker 的端点配置。

有关如何配置端点的详情,请参考 JBoss EAP 配置指南中的配置端点

4.14. Websocket 服务器配置的变化

要在 JBoss EAP 6 中使用 WebSockets,您必须使用类似如下的命令在 JBoss EAP 服务器配置文件的 web 子系统中为 http 连接器启用非阻塞 NIO2 连接器协议。

/subsystem=web/connector=http/:write-attribute(name=protocol,value=org.apache.coyote.http11.Http11NioProtocol)

要在应用程序中使用 WebSockets,还必须在应用程序 WEB-INF/jboss -web.xml 文件中创建一个 <enable-websockets > 元素,并将其设置为 true

在 JBoss EAP 7 中,您不再需要为默认 WebSocket 支持配置服务器,或者将应用程序配置为使用它。websocket 是 Jakarta EE 8 规格的要求,并且默认配置了必要的协议。更复杂的 WebSocket 配置在 JBoss EAP 服务器配置文件的 undertow 子系统的 servlet-container 中完成。您可以使用以下命令查看可用的设置。

/subsystem=undertow/servlet-container=default/setting=websockets:read-resource(recursive=true)
{
   "outcome" => "success",
   "result" => {
       "buffer-pool" => "default",
       "dispatch-to-worker" => true,
       "worker" => "default"
   }
}

有关 WebSocket 开发的更多信息,请参阅 JBoss EAP 开发指南中的创建 WebSocket 应用程序

websocket 代码示例也可以在 JBoss EAP 附带的快速入门中找到。

4.15. 单点登录服务器更改

infinispan 子系统仍然以 JBoss EAP 7 中的 Infinispan 缓存的形式为 HA 服务提供分布式缓存支持,但身份验证信息的缓存和分布与以前的版本不同。

在 JBoss EAP 6 中,如果单点登录(SSO)没有提供 Infinispan 缓存,缓存不会被发布。

在 JBoss EAP 7 中,选择 HA 配置集时会自动分发 SSO。在运行 HA 配置集时,每个主机都有自己的 Infinispan 缓存,该缓存基于 Web 缓存容器的默认缓存。此缓存存储了主机的相关会话和 SSO Cookie 信息。JBoss EAP 处理对所有主机的单个缓存信息传播。在 JBoss EAP 7 中,无法特别将 Infinispan 缓存分配给 SSO。

在 JBoss EAP 7 中,SSO 在服务器配置文件的 undertow 子系统中配置。

在迁移到 JBoss EAP 7 时,SSO 不需要更改应用程序代码。

4.16. 数据源配置更改

4.16.1. JDBC Datasource Driver Name

当您在 JBoss EAP 的早期版本中配置数据源时,为驱动程序名称指定的值取决于 META-INF/services/java.sql.Driver 文件中列出的类数量。

驱动程序包含单一类

如果只指定了 META-INF/services/java.sql.Driver 文件,则驱动程序名称的值是 JDBC 驱动程序 JAR 的名称。JBoss EAP 7 中的这一变化。

包含多个类的驱动

在 JBoss EAP 6 中,如果 META-INF/services/java.sql.Driver 文件列出了多个类,您可以指定哪个类是驱动程序类,方法是将其名称附加到 JAR 名称,以及主版本及次版本。

JAR_NAME + DRIVER_CLASS_NAME + "_" + MAJOR_VERSION + "_" + MINOR_VERSION

在 JBoss EAP 7 中,这一更改已经改变。现在,您可以使用以下格式指定驱动程序名称。

JAR_NAME + "_" + DRIVER_CLASS_NAME + "_" + MAJOR_VERSION + "_" + MINOR_VERSION
注意

JAR_NAMEDRIVER_CLASS_NAME 之间添加了下划线。

MySQL 5.1.31 JDBC 驱动程序是一个包含两个类的驱动程序示例。驱动程序类名称是 com.mysql.jdbc.Driver。以下示例演示了您在上一和 JBoss EAP 当前版本中指定驱动程序名称之间的差异。

示例:JBoss EAP 6 驱动器名称

mysql-connector-java-5.1.31-bin.jarcom.mysql.jdbc.Driver_5_1

示例:JBoss EAP 7 驱动程序名称

mysql-connector-java-5.1.31-bin.jar_com.mysql.jdbc.Driver_5_1

4.17. 安全服务器配置更改

如果您迁移到 JBoss EAP 7 并计划在启用了 Java Security Manager 的情况下运行,则应该注意,在定义策略的方式中进行更改,并且可能需要进行额外的配置更改。另请注意,JBoss EAP 7 不支持自定义安全管理器。

有关 Java 安全管理器服务器配置更改的信息,请参阅 如何为 JBoss EAP 配置服务器安全性中的从以前的版本迁移

4.17.1. JBoss EAP 7.0 和 JBoss EAP 7.1 之间的传统安全行为改变

4.17.1.1. 不可访问的 LDAP Realm 的 HTTP 状态更改

如果 JBoss EAP 7.0 中的服务器无法访问 LDAP 域,则 security 子系统会返回 HTTP 状态代码"401 Unauthorized"。

JBoss EAP 7.1 及之后的版本中的旧 security 子系统现在会返回 HTTP 状态代码 "500 Internal Error",以更准确地描述导致服务器成功处理请求的意外状况。

4.17.1.2. 启用 LDAP Security Realm 来从 DN 解析角色

在 JBoss EAP 7.0 中,org.jboss.as.domain.management.security.parseGroupNameFromLdapDN 系统属性用于启用 LDAP 安全域从 DN 解析角色。当此属性设置为 true 时,会从 DN 解析角色。否则,会使用普通的 LDAP 搜索来搜索角色。

在 JBoss EAP 7.1 及更新的版本中,这个系统属性已弃用。反之,您可以使用以下管理 CLI 命令在核心服务路径中将新引入的 parse-group-name-from-dn 属性设置为 true 来配置这个选项:

/core-service=management/security-realm=REALM_NAME/authorization=ldap/group-search=principal-to-group:add(parse-group-name-from-dn=true)

4.17.1.3. 将 JBoss EAP SSL 证书发送到 LDAP 服务器的更改

在 JBoss EAP 7.0 中,当管理界面配置为使用 ldapSSL 安全域时,服务器和 LDAP 之间的相互身份验证会失败,从而导致管理界面中的身份验证失败。这是因为,会进行两个不同的 LDAP 连接,每个连接各自有不同的线程,它们不共享 SSL 会话。

JBoss EAP 7.1 在 LDAP outbound-connection 中添加了一个新的 always-send-client-cert 管理属性(布尔值)。这个选项允许配置出站 LDAP 连接以支持配置为始终需要客户端证书的 LDAP 服务器。

LDAP 身份验证分为两个步骤:

  1. 它搜索帐户。
  2. 它将验证凭据。

默认情况下,always-send-client-cert 属性设为 false,即客户端 SSL 证书仅通过第一个搜索帐户请求发送。当此属性设置为 true 时,JBoss EAP LDAP 客户端使用搜索和验证请求将客户端证书发送到 LDAP 服务器。

您可以使用以下管理 CLI 命令将此属性设置为 true

/core-service=management/ldap-connection=my-ldap-connection:write-attribute(name=always-send-client-cert,value=true)

这会在服务器配置文件中生成以下 LDAP 出站连接。

<management>
  ....
  <outbound-connections>
    <ldap name="my-ldap-connection" url="ldap://127.0.0.1:389" search-dn="cn=search,dc=myCompany,dc=com" search-credential="myPass" always-send-client-cert="true"/>
  </outbound-connections>
  ....
</management>

4.17.2. FIPS 模式更改

如果您以 FIPS 模式运行,请注意在 JBoss EAP 7.0 和 JBoss EAP 7.1 之间修改了默认行为。

在使用传统安全域时,JBoss EAP 7.1 和更高版本为开发提供了自动生成的自签名证书。默认情况下启用此功能(在 JBoss EAP 7.0 中不可用)。这意味着,如果您在 FIPS 模式下运行,您必须将服务器配置为禁用自动自签名证书创建。否则,您在启动服务器时可能会看到以下错误。

ERROR [org.xnio.listener] (default I/O-6) XNIO001007: A channel event listener threw an exception: java.lang.RuntimeException: WFLYDM0114: Failed to lazily initialize SSL context
...
Caused by: java.lang.RuntimeException: WFLYDM0112: Failed to generate self signed certificate
...
Caused by: java.security.KeyStoreException: Cannot get key bytes, not PKCS#8 encoded

有关自动创建自签名证书的信息,请参阅如何为 JBoss EAP 配置服务器安全性中的自动签署应用证书创建

4.18. 事务子系统更改

JBoss EAP 6 中的 transaction 子系统中提供的一些交易管理器配置属性在 JBoss EAP 7 中有所变化。

删除了 Transactions 子系统属性

下表列出了 JBoss EAP 6 属性,这些属性已从 JBoss EAP 7 中的 transactions 子系统以及等效的替代属性中删除。

JBoss EAP 6 中的属性替换 JBoss EAP 7

path

object-store-path

relative-to

object-store-relative-to

弃用的事务子系统属性

JBoss EAP 6 的 transactions 子系统中提供的以下属性已在 JBoss EAP 7 中弃用。弃用的属性可能会在以后的版本中删除。下表列出了对等的替换属性。

JBoss EAP 6 中的属性替换 JBoss EAP 7

use-hornetq-store

use-journal-store

hornetq-store-enable-async-io

journal-store-enable-async-io

enable-statistics

statistics-enabled

4.19. 对 mod_cluster 配置的更改

在 JBoss EAP 7 中,mod_cluster 中静态代理列表的配置已改变。

在 JBoss EAP 6 中,您配置了 proxy-list 属性,它是以 hostname:port 的格式指定的 httpd 代理地址的逗号分隔列表。

proxy-list 属性在 JBoss EAP 7 中已弃用。它已被 proxies 属性替代,这个属性是出站套接字绑定名称的列表。

此更改会影响如何定义静态代理列表,例如在禁用 mod_cluster 的广告时。有关如何为 mod_cluster 禁用广告的信息,请参阅 JBoss EAP 配置指南中的 为 mod_cluster 禁用广告

有关 mod_cluster 属性的更多信息,请参阅 JBoss EAP 配置指南中ModCluster 子系统属性

4.20. 查看配置更改

JBoss EAP 7 提供了跟踪对正在运行的服务器的配置更改的功能。这样,管理员可以查看授权用户可以进行配置更改的历史记录。

在 JBoss EAP 7.0 中,您必须使用 core-service 管理 CLI 命令配置选项并列出最新的配置更改。

示例:列出 JBoss EAP 7.0 中的配置更改

/core-service=management/service=configuration-changes:add(max-history=10)
/core-service=management/service=configuration-changes:list-changes

JBoss EAP 7.1 引入了新的 core-management 子系统,可以配置该子系统来跟踪对正在运行的服务器的配置更改。这是在 JBoss EAP 7.1 及更高版本中配置和查看配置更改的首选方法。

示例:列出 JBoss EAP 7.1 及之后的版本中的配置更改

/subsystem=core-management/service=configuration-changes:add(max-history=20)
/subsystem=core-management/service=configuration-changes:list-changes

有关使用 JBoss EAP 7.1 中引入的新 核心管理 子系统的更多信息,请参阅 JBoss EAP 配置指南中的 查看配置更改

第 5 章 应用程序迁移更改

5.1. Web 服务应用程序更改

JBossWS 5 对 JBoss EAP 7 web 服务提供了新的特性和性能改进,主要是通过升级 Apache CXFApache WSS4JApache Santuario 组件。

5.1.1. JAX-RPC 支持更改

基于 XML 的 RPC(JAX-RPC)的 Java API 在 Java EE 6 中弃用,在 Java EE 7 中是可选的。JBoss EAP 7 中不再提供或支持它。使用 JAX-RPC 的应用必须迁移到使用 Jakarta XML Web 服务,该服务为当前的 Jakarta EE 标准 Web 服务框架。

可以使用以下任一方式识别 JAX-RPC Web 服务:

  • 存在 JAX-RPC 映射文件,它是包含 root 元素 < java-wsdl-mapping > 的 XML 文件。
  • 存在 webservices.xml XML 描述符文件,其中包含 <webservice-description> 元素,其中包含一个 <jaxrpc-mapping-file> 子元素。以下是定义 JAX-RPC Web 服务的 webservices.xml 描述符文件示例。

    <webservices xmlns="http://java.sun.com/xml/ns/j2ee"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://www.ibm.com/webservices/xsd/j2ee_web_services_1_1.xsd" version="1.1">
      <webservice-description>
        <webservice-description-name>HelloService</webservice-description-name>
        <wsdl-file>WEB-INF/wsdl/HelloService.wsdl</wsdl-file>
        <jaxrpc-mapping-file>WEB-INF/mapping.xml</jaxrpc-mapping-file>
        <port-component>
          <port-component-name>Hello</port-component-name>
          <wsdl-port>HelloPort</wsdl-port>
          <service-endpoint-interface>org.jboss.chap12.hello.Hello</service-endpoint-interface>
          <service-impl-bean>
            <servlet-link>HelloWorldServlet</servlet-link>
          </service-impl-bean>
        </port-component>
      </webservice-description>
    </webservices>
  • 存在 ejb-jar.xml 文件,该文件中包含引用一个 JAX-RPC 映射文件的 <service-ref>

5.1.2. Apache CXF Spring web 服务更改

在以前的 JBoss EAP 版本中,您可以通过包含带有端点部署存档的 jbossws-cxf.xml 配置文件来自定义 JBossWS 和 Apache CXF 集成。一个用例是,为 Apache CXF 总线上的 Web 服务客户端和服务器端点配置拦截器链。此集成需要在 JBoss EAP 服务器中部署 Spring。

JBoss EAP 7 不再支持 Spring 集成。包含 jbossws-cxf.xml 描述符配置文件的任何应用程序都必须修改,以替换该文件中定义的自定义配置。虽然仍然可以直接访问 Apache CXF API,但请注意,应用程序将无法可移植。

建议的方法将 Spring 自定义配置替换为新的 JBossWS 描述符配置选项。基于 JBossWS 描述符的方法提供类似功能,无需修改客户端端点代码。在某些情况下,您可以将 Spring 替换为上下文依赖注入(CDI)。

Apache CXF 拦截器

JBossWS 描述符提供了新的配置选项,允许您在不修改客户端端点代码的情况下声明拦截器。反之,您可以通过为 cxf.interceptors.incxf.interceptors.out 属性指定拦截器名称列表,在预定义的客户端和端点配置中声明拦截器。

以下是使用这些属性声明拦截器的 jaxws-endpoint-config.xml 文件的示例。

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd">
  <endpoint-config>
    <config-name>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointImpl</config-name>
    <property>
      <property-name>cxf.interceptors.in</property-name>
      <property-value>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointInterceptor,org.jboss.test.ws.jaxws.cxf.interceptors.FooInterceptor</property-value>
    </property>
    <property>
      <property-name>cxf.interceptors.out</property-name>
      <property-value>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointCounterInterceptor</property-value>
    </property>
  </endpoint-config>
</jaxws-config>
Apache CXF 功能

JBossWS 描述符允许您通过为 cxf.features 属性指定功能列表,在预定义的客户端和端点配置中声明功能。

以下是使用此属性声明功能的 jaxws-endpoint-config.xml 文件的示例。

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd">
  <endpoint-config>
    <config-name>Custom FI Config</config-name>
    <property>
      <property-name>cxf.features</property-name>
      <property-value>org.apache.cxf.feature.FastInfosetFeature</property-value>
    </property>
  </endpoint-config>
</jaxws-config>
Apache CXF HTTP 传输

在 Apache CXF 中,通过指定 org.apache.cxf.transport.http.HTTPConduit 选项来实现 HTTP 传输配置。JBossWS 集成允许以编程方式使用 Apache CXF API 修改,如下所示:

import org.apache.cxf.frontend.ClientProxy;
import org.apache.cxf.transport.http.HTTPConduit;
import org.apache.cxf.transports.http.configuration.HTTPClientPolicy;

// Set chunking threshold before using a JAX-WS port client
...
HTTPConduit conduit = (HTTPConduit)ClientProxy.getClient(port).getConduit();
HTTPClientPolicy client = conduit.getClient();

client.setChunkingThreshold(8192);
...

您还可以通过设置系统属性来控制并覆盖 Apache CXF HTTPConduit 默认值。

属性类型描述

cxf.client.allowChunking

布尔值

指定是否使用块发送请求。

cxf.client.chunkingThreshold

整数

设置从非克隆到块模式的阈值。

cxf.client.connectionTimeout

Long

设置连接超时的毫秒数。

cxf.client.receiveTimeout

Long

设置接收超时的毫秒数。

cxf.client.connection

字符串

指定是否使用 Keep-Aliveclose 连接类型。

cxf.tls-client.disableCNCheck

布尔值

指定是否禁用 CN 主机名检查。

5.1.3. WS-Security 更改

  • 如果您的应用程序包含访问 org.apache.ws.security.WSPasswordCallback 类的自定义回调处理器,请注意,此类已移到 org.apache.wss4j.common.ext 软件包。
  • org.apache.ws.saml.ext 软件包中的大多数 SAML Bean 对象已移到 org.apache.wss4j.common.saml 软件包
  • 默认情况下,不允许使用 RSA v1.5 密钥传输和所有相关算法。
  • 以前,安全令牌服务(STS)仅在 BehalfOf 令牌上进行验证。现在,它还会验证 ActAs 令牌。因此,必须在为 ActAs 令牌提供的 UsernameToken 中指定有效的用户名和密码。
  • SAML 持有者令牌现在需要具有内部签名。org.apache.wss4j.dom.SamlAsertionValidator 类现在有一个 setRequireBearerSignature() 方法,用于启用或禁用签名验证。

5.1.4. JBoss 模块结构更改

cxf-apicxf-rt-core JARs 已合并到一个 cxf-core JAR 中。因此,JBoss EAP 中的 org.apache.cxf 模块现在包含 cxf-core JAR,并公开比上一版本更多的类。

5.1.5. Bouncy Castle 要求和更改

如果要将 AES 加密与 Galois/Counter Mode(GCM)用于 XML/WS-Security 中的对称加密,则需要 BouncyCastle Security Provider。

JBoss EAP 7 附带 org.bouncastle 模块,而 JBossWS 现在能够依靠其课程加载程序来获取和使用 BouncyCastle 安全提供商。因此,在当前 JVM 中静态安装 BouncyCastle 不再需要。对于在容器外运行的应用程序,可通过在类路径中添加 BouncyCastle 库来为 JBossWS 提供安全供应商。

您可以禁用此行为:把 jaxws-endpoint-config.xml 部署描述符文件(对于服务器)或 jaxws-client-config.xml 部署描述符文件(对于客户端)中的 org.jboss.ws.cxf.noLocalBC 属性值设置为true

如果要使用与 JBoss EAP 附带的版本不同的版本,您仍可将 BouncyCastle 安装到 JVM。在这种情况下,按照类路径中的提供者选择静态安装的 BouncyCastle Security Provider。要避免任何问题,您必须使用 BouncyCastle 1.49、1.51 或更高。

5.1.6. Apache CXF 总线选择策略

在容器中运行的客户端的默认总线选择策略已从 THREAD_BUS 改为 TCCL_BUS。对于运行内存不足的客户端,默认的策略仍然是 THREAD_BUS。您可以使用以下方法之一将行为恢复到之前的版本。

  • 使用系统属性 org.jboss.ws.cxf.jaxws-client.bus.strategy 值设置为 THREAD_BUS 来启动 JBoss EAP 服务器。
  • 在客户端代码中明确设置选择策略。

5.1.7. WebServiceRef 的 Jakarta XML Web Services 2.2 要求

容器必须使用 Jakarta XML Web 服务 2.2 风格构造器,它将 WebServiceFeature 类包含在构造器中,以构建注入 Web 服务引用的客户端。JBoss EAP 6.4 包括了 JBossWS 4,隐藏了这一要求。JBoss EAP 7 包括了 JBossWS 5,不再隐藏了这一要求。这意味着,容器注入的用户提供的服务类必须通过更新现有代码来实现 Jakarta XML Web Services 2.2 或更高版本,以使用包含一个或多个 WebServiceFeature 参数的 javax.xml.ws.Service 结构器。

protected Service(URL wsdlDocumentLocation,
       QName serviceName,
       WebServiceFeature... features)

5.1.8. IgnoreHttpsHost CN 检查更改

在以前的版本中,您可以通过将系统属性 org.jboss.security.ignoreHttpsHost 设置为 true 来禁用对证书中提供的服务通用名称(CN)的 HTTPS URL 主机名检查。这个系统属性名称已被 cxf.tls-client.disableCNCheck 替代。

5.1.9. 服务器端配置和类加载

由于启用注入服务端点和服务客户端处理程序,便无法再自动加载来自 org.jboss.as.webservices.server.integration JBoss 模块的处理程序类。如果您的应用程序依赖于给定的预定义的配置,您可能需要为部署显式定义新的模块依赖项。如需更多信息,请参阅迁移模块依赖项

5.1.10. 弃用 Java 签名的标准覆盖机制

JDK 1.8_40 中弃用了 Java 背书的标准覆盖机制,旨在将其从 JDK 9 中删除。这种机制使开发人员能够通过将 JARs 放入 JRE 中的最终目录,使库可供所有部署的应用程序使用。

如果您的应用程序使用 Apache CXF 的 JBossWS 实施,JBoss EAP 7 可确保以正确顺序添加所需的依赖项,您不应受到此更改的影响。如果您的应用程序直接访问 Apache CXF,则现在必须在 JBossWS 依赖项作为应用程序部署的一部分后提供 Apache CXF 依赖项。

5.1.11. EAR 归档中的描述符规格

在以前的 JBoss EAP 版本中,您可以为 Jakarta Enterprise Beans Web 服务部署描述符文件配置 jboss-webservices.xml 部署描述符文件,在 JAR 存档的 META-INF/ 目录中配置 JAR 存档或 WEB-INF/ 目录中用于 POJO Web 服务部署以及 Jakarta Enterprise Beans Web 服务端点的 Jakarta Enterprise Beans Web 服务端点。

在 JBoss EAP 7 中,您现在可以在 EAR 归档的 META-INF/ 目录中配置 jboss-webservices.xml 部署描述符文件。如果 EAR 归档和 JAR 或 WAR 存档中都找到了 jboss-webservices.xml 文件,则 JAR 或 WAR 中的 jboss-webservices.xml 文件中的配置数据会覆盖 EAR 描述符文件中对应的数据。

5.2. 更新远程 URL Connector 和端口

在 JBoss EAP 7 中,默认的连接器已从 remote 改为 http-remoting,默认的远程连接端口已从 4447 改为 8080。默认配置的 JNDI 提供程序 URL 已从 remote://localhost:4447 更改为 http-remoting://localhost:8080

如果您使用 JBoss EAP 7 迁移操作来更新配置,则不需要修改远程连接器、远程端口或 JNDI 提供程序 URL,因为迁移操作会保留 JBoss EAP 6 重新移动连接器和 4447 端口配置设置。有关迁移操作的更多信息,请参阅管理 CLI 迁移操作

如果不使用 migrate 操作,而使用新的 JBoss EAP 7 默认配置,您必须更改远程连接器、远程端口和 JNDI 提供程序 URL,以使用上述新设置。

5.3. 消息传递应用程序更改

5.3.1. 替换或更新 Jakarta Messaging 部署描述符

命名模式 -jms.xml 标识的专有 HornetQ 消息资源部署描述符文件在 JBoss EAP 7 中不再起作用。以下是 JBoss EAP 6 中 Jakarta Messaging 资源部署描述符文件的示例:

<?xml version="1.0" encoding="UTF-8"?>
<messaging-deployment xmlns="urn:jboss:messaging-deployment:1.0">
  <hornetq-server>
    <jms-destinations>
      <jms-queue name="testQueue">
        <entry name="queue/test"/>
        <entry name="java:jboss/exported/jms/queue/test"/>
      </jms-queue>
      <jms-topic name="testTopic">
        <entry name="topic/test"/>
        <entry name="java:jboss/exported/jms/topic/test"/>
      </jms-topic>
    </jms-destinations>
  </hornetq-server>
</messaging-deployment>

如果您在上一版本中使用 -jms.xml Jakarta Messaging 部署描述符,您可以转换应用程序以使用 Jakarta EE 平台第 EE.5.18 部分中指定的标准部署描述符,或者您可以更新部署描述符以使用 messaging-activemq-deployment 模式。如果您选择更新描述符,则需要进行以下修改:

  • 将命名空间从 "urn:jboss: messaging-deployment:1.0" 更改为 "urn:jboss: messaging-activemq-deployment:1.0"。
  • <hornetq-server> 元素的名称改为 <server>

修改后的文件应当类似于下例所示。

<?xml version="1.0" encoding="UTF-8"?>
<messaging-deployment xmlns="urn:jboss:messaging-activemq-deployment:1.0">
  <server>
    <jms-destinations>
      <jms-queue name="testQueue">
        <entry name="queue/test"/>
        <entry name="java:jboss/exported/jms/queue/test"/>
      </jms-queue>
      <jms-topic name="testTopic">
        <entry name="topic/test"/>
        <entry name="java:jboss/exported/jms/topic/test"/>
      </jms-topic>
    </jms-destinations>
  </server>
</messaging-deployment>

有关与消息传递相关的服务器配置更改的详情,请参考消息传递服务器配置变化

5.3.2. 更新外部 Jakarta Messaging 客户端

JBoss EAP 7 仍然支持 Jakarta Messaging 1.1 API,因此您无需修改代码。

JBoss EAP 7 中更改了默认远程连接器和端口。有关此更改的详情,请参阅更新远程 URL Connector 和端口

如果您使用 migrate 操作迁移服务器配置,则会保留旧的设置,您不需要更新您的 ImagePrepare _URL。但是,如果使用新的 JBoss EAP 7 默认配置运行,您必须更改客户端代码中的 BK_URL,以使用新的 http-remoting://localhost:8080 设置。如需更多信息,请参阅 迁移远程命名客户端代码

如果您计划迁移代码以使用 Jakarta Messaging 2.0 API,请参见 helloworld-jms quickstart 了解工作示例。

5.3.3. 替换 HornetQ API

JBoss EAP 6 包含 org.hornetq 模块,可用于在应用程序源代码中使用 HornetQ API

Apache ActiveMQ Artemis 取代了 JBoss EAP 7 中的 HornetQ,因此您必须迁移任何使用 HornetQ API 的代码,以使用 Apache ActiveMQ Artemis API。此 API 的库包含在 org.apache.activemq.artemis 模块中。

ActiveMQ Artemis 是 HornetQ 的演进,因此许多概念仍然适用。

5.3.4. 替换已弃用的地址设置属性

使用 auto-create-jms-queues、auto-delete- jms-queues、auto-create -jms-queues、auto-create-jms-topicsauto-delete-jms-topics 属性自动创建和自动删除主题的功能只在 JBoss EAP 7 中实施且不完全配置。这些属性已弃用,仅作为技术预览提供,且不被支持。

您必须将这些已弃用的属性的任何用法替换为以下替代属性。

注意

弃用的属性不再在 JBoss EAP 7.4 中配置此功能,且不会起作用。不支持替换属性。它们只能作为按最佳努力迁移的方式。

弃用的属性替换属性

auto-create-jms-queues

auto-create-queues

auto-delete-jms-queues

auto-delete-queues

auto-create-jms-topics

auto-create-addresses

auto-delete-jms-topics

auto-delete-addresses

在 JBoss EAP 6 中,默认的地址设置属性设为 false。JBoss EAP 7 中的替换属性默认为 true

如果您希望保留 JBoss EAP 6 行为,您必须将替换属性设置为 false

有关这些替换属性的更多信息,请参阅配置消息传递中的地址设置属性

5.3.5. JBoss EAP 7 所需的消息传递应用程序变化

从 JBoss EAP 7.2 开始,如果客户端应用直接依赖于 INVENTORY 客户端 JAR,例如: artemis-jms-clientartemis-commonsartemis-core-client,或 artemis-selector,那么您必须在 pom.xml 文件中为 wildfly-client-properties 添加以下依赖关系。

<dependency>
  <groupId>org.jboss.eap</groupId>
  <artifactId>wildfly-client-properties</artifactId>
</dependency>

在从旧的 JBoss EAP 7 客户端中调用 message.getJMSReplyTo() 时,避免 JMSRuntimeException,如 JBEAP-15889 所述。

5.4. JAX-RS 和 RESTEasy 应用更改

JBoss EAP 6 捆绑了 RESTEasy 2,它是 JAX-RS 1.x 的实施。

JBoss EAP 7.0 和 JBoss EAP 7.1 包括 RESTEasy 3.0.x,这是 JSR 339: JAX-RS 2.0 定义的 JAX-RS 2.0 实施:RESTful Web 服务规范的 Java API。有关 RESTful Web 服务的 Java API 的更多信息,请参阅 JAX-RS 2.0 API 规格

JBoss EAP 7.4 包含 RESTEasy 3.9.0,这是 Jakarta RESTful Web 服务 2.1 的实施。此发行版本还添加了对 JDK 11 的支持。虽然提供一些 RESTEasy 4 主要功能,但此版本基于 RESTEasy 3.0,确保完全向后兼容。因此,您应该在从 RESTEasy 3.0.x 迁移到 3.9.0 时遇到一些问题。有关 RESTEasy 3.9.0 的 Java API 的更多信息,请参阅 RESTEasy JAX-RS 3.9.0.Final API

如果您要从 JBoss EAP 6.4 迁移,请注意 JBoss EAP 中包含的 Jackson 版本发生了变化。JBoss EAP 6.4 包括 Jackson 1.9.9。JBoss EAP 7 及更高版本现在包含 Jackson 2.6.3 或更高版本。

本节介绍这些更改如何影响使用 RESTEasy 或 JAX-RS 的应用。

5.4.1. resteasy 已弃用类

拦截器和 MessageBody 类

JSR 311:JAX-RS:RESTful Web 服务的 Java™ API 没有包含拦截器框架,因此 RESTEasy 2 提供一个。JSR 339:JAX-RS 2.0:RESTful Web 服务的 Java API 引入了官方拦截器和过滤框架,因此 RESTEasy 2 中包含的拦截器框架现已弃用,并且被 RESTEasy 3.x 中的 JAX-RS 兼容拦截器功能所取代。相关的接口在 jaxrs-api 模块的 javax.ws.rs.ext 软件包中定义。

注意

来自以前版本的 RESTEasy 的所有拦截器都可以与新的 JAX-RS 过滤器和拦截器接口并行运行。

如需有关拦截器的更多信息,请参阅用于 JBoss EAP 开发 Web Services 应用中的 RESTEasy 拦截器

如需有关新的替换 API 的更多信息,请参阅 RESTEasy JAX-RS 3.9.0.Final API

客户端 API

resteasy-jaxrs 中的 RESTEasy 客户端框架被 JBoss EAP 7.0 中的遵循 JAX-RS 2.0 的 resteasy-client 模块替代。因此,一些 RESTEasy 客户端 API 类和方法已弃用。

注意

有关 org.jboss.resteasy.client.jaxrs API 类的更多信息,请参见 RESTEasy JAX-RS JavaDoc

StringConverter

org.jboss.resteasy.spi.StringConverter 类在 RESTEasy 3.x 中被弃用。可以使用 JAX-RS jax.ws.rs.ext.ParamConverterProvider 类来替换此功能。

5.4.2. 删除或保护的 RESTEasy 类

ResteasyProviderFactory 添加方法

大多数 org.jboss.resteasy.spi.ResteasyProviderFactory add() 方法已被删除或在 RESTEasy 3.0 中受到保护。例如,addBuiltInMessageBodyReader()addBuiltInMessageBodyWriter() 方法已被删除,并且 addMessageBodyReader()addMessageBodyWriter() 方法受保护。

您现在应使用 registerProvider()registerProviderInstance() 方法。

从 RESTEasy 3 中删除额外的类

@org.jboss.resteasy.annotations.cache.ServerCached 注释指定对 JAX-RS 方法的响应应缓存在服务器上,并且必须从 RESTEasy 3 中删除。

5.4.3. 其他 RESTEasy 更改

SignedInput 和 SignedOuput
  • resteasy-cryptoSignedInputSignedOutput 必须在 RequestResponse 对象中将 Content-Type 设置为multipart/signed,或使用 @Consumes@Produces 注解。
  • SignedOutputSignedInput 可用于通过设置 @Produces@Consumes 注释中的 type 以二进制格式返回 应用程序/pkcs7-signature MIME 类型格式。
  • 如果 @Produces@Consumestext/plain MIME 类型,则 SignedOutput 将采用 base64 编码并作为 String 发送。
安全过滤器

@RolesAllowed@PermitAll@DenyAll 的安全过滤器现在返回 "403 Forbidden" 而不是 "401 Unauthorized"。

客户端过滤器

从 RESTEasy 3.0 之前,从版本使用 RESTEasy 客户端 API 时,在 JAX-RS 2.0 中引入的客户端侧过滤器不会绑定并运行。

异步 HTTP 支持

由于 JAX-RS 2.0 规范添加了利用 @Suspended 注释和 AsynResponse 接口的异步 HTTP 支持,因此用于异步 HTTP 的 RESTEasy 专有 API 已被弃用,并可能在以后的 RESTEasy 发行版中移除。异步 Tomcat 和异步 JBoss Web 模块也已从服务器安装中删除。如果您不使用 Servlet 3.0 容器或更高,则异步 HTTP 服务器端处理将模拟,并在同一个请求线程中异步运行。

服务器端缓存

服务器端缓存设置已更改。如需更多信息,请参阅 RESTEasy 文档

YAML 供应商设置更改

在以前的 JBoss EAP 版本中,RESTEasy YAML 供应商设置被默认启用。这在 JBoss EAP 7 中有所改变。现在默认禁用 YAML 供应商。由于 RESTEasy 用于 unmarshalling 的 SnakeYAML 库中的安全问题,它不被支持,因此必须在应用中明确启用。有关如何在应用程序中启用 YAML 供应商并添加 Maven 依赖项的信息,请参阅 为 JBoss EAP 开发 Web Services Applications 中的 YAML 供应商

Content-Type Header 中的默认 Charset UTF-8

自 JBoss EAP 7.1 起,resteasy.add.charset 参数默认设置为 true。当资源方法返回一个 text/*application/xml* 媒介类型且没有明确的字符集时,如果您不希望 RESTEasy 将 charset=UTF-8 添加到返回的 content-type 头时,可以将 resteasy.add.charset 参数设置为 false

如需有关文本媒体类型和字符集的更多信息,请参阅为 JBoss EAP 开发 Web 服务应用中的文本介质类型和字符集

SerializableProvider

从不受信任的源中反序列化 Java 对象是不安全的。因此,在 JBoss EAP 7 中,默认禁用 org.jboss.resteasy.plugins.providers.SerializableProvider 类,因此不建议使用这个提供程序。

将请求与资源方法匹配

在 RESTEasy 3 中,对匹配的规则实施进行了改进和修正,如 JAX-RS 规范中所定义。特别是,如何对子资源方法上的模糊的 URI 以及处理子资源松cator 时进行一个更改。

在 RESTEasy 2 中,即使存在具有相同 URI 的另一个子资源,也会让子资源 locator 成功执行。这个行为根据规格不正确。

在 RESTEasy 3 中,当子资源和子资源松cator 存在模糊的 URI 时,调用子资源将成功;但是,调用子资源 locator 将导致 HTTP 状态 405 Method Not Allowed 错误。

以下示例包含子资源方法和子资源 locator 上的模糊 @Path 注释。注意 URI 到端点( anotherResourceanotherResourceLocator )是相同的。两个端点的区别在于 anotherResource 方法与 REST 动词 POST 关联。anotherResourceLocator 方法不与任何 REST 动词关联。根据规范,将始终选择具有 REST 动词的端点(本例中为 anotherResource 方法)。

@Path("myResource")
public class ExampleSubResources {
    @POST
    @Path("items")
    @Produces("text/plain")
    public Response anotherResource(String text) {
        return Response.ok("ok").build();
    }

    @Path("items")
    @Produces("text/plain")
    public SubResource anotherResourceLocator() {
        return new SubResource();
    }
}
资源方法算法切换

在 3.0.25 之前的 RESTEasy 3.0.x 版本中使用的资源方法匹配算法中发现了一个错误,即 RESTEasy 在响应请求时返回太多的资源类型。

匹配算法有三个阶段:

  1. 使用请求路径来选择可能的资源类。
  2. 使用请求路径来选择可能的资源方法。
  3. 使用 HTTP 动词和介质类型 coming 和 going,选择最终的资源方法。

根据 JAX-RS 2.0 规范,在对潜在资源方法集合进行排序后,仅将最大元素传递给第 3 步。但是,在 RESTEasy 3.0.25 之前的 RESTEasy 3.0.x 实施将所有方法传递给第 3 步。JBoss EAP 7.1.0 中包含的 RESTEasy 3.0.24 表现出了这种行为不正确。

RESTEasy 3.0.25 (包含在 JBoss EAP 7.1.1 中)提供了相应的修复,以限制传递到第 3 步要符合 JAX-RS 2.0 规范的方法。由于 looser 的行为可能更倾向于,因此 RESTEasy 3.0.25 还引入了 context-param 配置选项 resteasy.loose.step2.request.match(默认为 false ),它可以配置为启用旧行为。

如果您将 JBoss EAP 服务器从 7.1.0 升级到 7.1.1,并且您希望保留旧行为,并将所有潜在的资源方法传递给第 3 步,将 resteasy.loose.step2.request.matching 选项设置为 true

在 JAX-RS 2.1 规范中更改了匹配的算法,将所有匹配的资源方法传递给第 3 步。RESTEasy 3.9.0 包含在 JBoss EAP 7.4 中,提供 jaxrs.2.0.request.matching 选项,以保留 JAX-RS 2.0 规范中定义的更严格的行为。

如果您将应用程序从 JBoss EAP 从 7.1.0 迁移到 7.2.x,则不应在资源方法匹配算法的行为中看到更改。如果您将应用程序从 JBoss EAP 从 7.1.1 迁移到 7.2.x 或更高版本,并希望保留 JAX-RS 2.0 规范中定义的更严格的行为,将 jaxrs.2.0.request.matching 选项设置为 true

5.4.4. resteasy SPI 更改

SPI Exceptions

所有 SPI 失败异常已被弃用,且不再在内部使用。它们已被对应的 JAX-RS 例外替代。

弃用的例外jaxrs-api 模块中的替换 Exception

org.jboss.resteasy.spi.ForbiddenException

javax.ws.rs.ForbiddenException

org.jboss.resteasy.spi.MethodNotAllowedException

javax.ws.rs.NotAllowedException

org.jboss.resteasy.spi.NotAcceptableException

javax.ws.rs.NotAcceptableException

org.jboss.resteasy.spi.NotFoundException

javax.ws.rs.NotFoundException

org.jboss.resteasy.spi.UnauthorizedException

javax.ws.rs.NotAuthorizedException

org.jboss.resteasy.spi.UnsupportedMediaTypeException

javax.ws.rs.NotSupportedException

InjectoronnectionFactoryy 和 Registry

InjectorFactoryRegistry SPI 已更改。如果使用 RESTEasy 作为文档和支持,这不应有问题。

5.4.5. Jackson Provider Changes

JBoss EAP 中包含的 Jackson 版本发生了变化。先前版本的 JBoss EAP 包括 Jackson 1.9.9。JBoss EAP 7 现在包含 Jackson 2.6.3 或更高版本。因此,Jackson 供应商已从 resteasy-jackson-provider 改为 resteasy-jackson2-provider

升级到 resteasy-jackson2-provider 需要一些软件包更改。例如,Jackson 注解软件包已从 org.codehaus.jackson.annotate 改为 com.fasterxml.jackson.annotation

要切换应用程序以使用 JBoss EAP 之前版本中包含的默认供应商,请参阅在为 JBoss EAP 开发 Web Services Applications切换 Default Jackson Provider

5.4.6. Spring RESTEasy 集成更改

Spring 4.0 框架引入了对 Java 8 的支持。如果您计划使用 RESTEasy 3.x 与 Spring 集成,请确保将 4.2.x 指定为部署中最低 Spring 版本,因为这是 JBoss EAP 7 支持的最早的稳定版本。

5.4.7. resteasy Jettison JSON Provider Changes

RESTEasy Jettison JSON 提供程序在 JBoss EAP 7 中已弃用,且不再默认添加到部署中。建议您切换到推荐的 RESTEasy Jackson 供应商。如果您希望继续使用 Jettison 提供程序,您必须在 jboss-deployment-descriptor.xml 文件中定义一个明确的依赖关系,如下例所示。

<?xml version="1.0" encoding="UTF-8"?>
<jboss-deployment-structure>
  <deployment>
    <exclusions>
      <module name="org.jboss.resteasy.resteasy-jackson2-provider"/>
      <module name="org.jboss.resteasy.resteasy-jackson-provider"/>
    </exclusions>
    <dependencies>
      <module name="org.jboss.resteasy.resteasy-jettison-provider" services="import"/>
    </dependencies>
  </deployment>
</jboss-deployment-structure>

有关如何定义显式依赖项的更多信息,请参阅 JBoss EAP 开发指南为部署添加解释模块依赖项

5.4.8. MicroProfile Rest Client Code 所需的更改

JBoss EAP 7.3 支持 MicroProfile REST 客户端的版本 1.3.x。如果您使用旧版 MicroProfile REST 客户端,则需要在代码中进行一些更新。

重要

MicroProfile REST 客户端仅作为技术预览提供。技术预览功能不包括在红帽生产服务级别协议(SLA)中,且其功能可能并不完善。因此,红帽不建议在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能,并有机会在开发阶段提供反馈意见。

如需有关 技术预览功能支持范围 的信息,请参阅红帽客户门户网站中的技术预览功能支持范围。

org.jboss.resteasy.client.microprofile.MicroprofileClientBuilderResolver 类被 org.eclipse.microprofile.rest.client.RestClientBuilder 替代。例如:

@Path("resource")
public interface TestResourceIntf {

   @Path("test")
   @GET
   public String test();
}

TestResourceIntf service = RestClientBuilder.newBuilder()
                              .baseUrl("http://localhost:8081/")
                              .build(TestResourceIntf.class);
String s = service.test();

有关 MicroProfile REST 客户端的更多信息,请参阅 JBoss EAP 开发 Web 服务应用 指南中的 MicroProfile REST 客户端

5.4.9. JBoss EAP 的 MicroProfile 配置

MicroProfile 配置是开发人员用来将应用和微服务配置为在多个环境中运行的规范名称,而无需修改或重新打包这些应用。在以前的版本中,MicroProfile Config 作为技术预览提供 JBoss EAP,但自此后已被删除。MicroProfile 配置现在仅适用于 JBoss EAP XP。

其他资源

5.5. CDI 应用更改

JBoss EAP 7.4 包含对 CDI 2.0 的支持。因此,使用 CDI 1.0 或 CDI 1.2 编写的应用程序可能会在迁移到 JBoss EAP 7.4 时看到一些行为更改。本节总结了 CDI 1.2 和 CDI 2.0 中所做的一些更改。

您可以在以下引用中找到有关 Weld 和 CDI 2.0 的更多信息:

Bean 归档

bean enabled Bean 类必须部署到 bean 存档中,以确保它们由 CDI 扫描并处理 bean 类。

在 CDI 1.0 中,一个归档在一个 explicit bean 归档中定义,如果它在 META-INF/ 目录中包括一个 beans.xml 文件用于应用程序客户、EJB 或库 JAR,或它在 WEB-INF/ 目录中包括一个 beans.xml 文件用于 WAR。

CDI 1.1 引入了 隐式 bean 归档,存档包含一个或多个带有定义注解的 bean 类,或者一个或多个 session Bean。隐式 bean 存档由 CDI 扫描,在类型发现过程中,只会发现带有 bean 定义注解的类。如需更多信息,请参阅 JSR 365、上下文和依赖注入中的 Type 和 Bean Discovery for Java 2.0。Jakarta 为 bean 定义注解的等效项在 Jakarta 上下文依赖注入 2.0 规格中定义

bean 归档具有 all, annotatednone 的 bean 发现模式。包含一个 bean 归档,其中包含没有版本且无 version 的 bean 发现模式,all 均有默认的 bean 发现模式。包含带有版本 1.1 或更新的 Bean.xml 文件的 bean 归档必须指定 bean-discovery-mode 属性。属性的默认值被 annotated

在以下情况下,存档不是 bean 归档:

  • 它包含一个 Bean.xml 文件,bean-discovery-modenone
  • 它包含一个 CDI 扩展,没有 Bean.xml 文件。

在以下情况下,存档是一个 明确的 归档:

  • 归档包含 Bean.xml 文件,其版本号为 1.1 或以上,并且是 bean-discovery-modeall
  • 归档包含一个 beans.xml 文件,且无版本号。
  • 归档包含空的 beans.xml 文件。

归档是在以下情况下的一个 隐式 存档:

  • 存档包含一个或多个 bean 类,它们带有 bean 定义注解或一个或多个会话 Bean,即使它不包含 Bean.xml 文件。
  • 归档包含一个 beans.xml 文件,bean-discovery-modeannotated

CDI 1.2 限于定义以下注解

  • @ApplicationScoped@SessionScoped@ConversationScoped@RequestScoped annotations
  • 所有其他常规范围类型
  • @Interceptor@Decorator 注解
  • 所有 stereotype 注解,注解为 @Stereotype
  • @Dependent scope 注释

有关 bean 归档的更多信息,请参阅 JSR 365:上下文和依赖注入 Java 2.0 中的 Bean 存档。Jakarta 等同于 Bean 归档,在 Jakarta 上下文依赖注入 2.0 规格中定义

解析解析

CDI 1.2 中更改了对话上下文生命周期,以防止与 Servlet 规范冲突,如 CDI 规范问题 CDI-411 所述。对话范围在所有 servlet 请求期间处于活跃状态,不应阻止其他 servlet 或 servlet 过滤器设置请求正文或字符编码。如需更多信息,请参阅 Jakarta EE 中的整合上下文生命周期

观察器解析

在 CDI 1.2 中,事件解析部分被重写。在 CDI 1.0 中,如果观察器方法具有所有事件限定符,则会向观察器发送事件。在 CDI 1.2 中,如果观察器方法没有事件限定符或者具有事件限定符的子集,则会向观察者发送事件。如需更多信息,请参阅 Observer 解析

5.6. HTTP 会话 ID 更改

request.getSession().getId() 调用返回的字符串,以获取分配给 HTTP 会话的唯一标识符,已在 JBoss EAP 6.4 和 JBoss EAP 7 之间有所变化。

JBoss EAP 6.4 以 session-id.instance-id 格式返回会话 ID 和实例 ID。

JBoss EAP 7 仅返回会话 ID。

对于从 JBoss EAP 6 到 JBoss EAP 7 的一些升级,这种更改可能会造成无路由 Cookie 的问题。如果您的应用程序根据这个方法调用的返回值重新创建 JSESSIONID cookies,您可能需要更新应用代码来提供所需的行为。

5.7. 迁移 Explicit Module Dependencies

JBoss EAP 之前的发行版本中对模块类载入系统和 JBoss 模块的引入,允许对应用程序可用的类进行精细控制。此功能允许您使用应用程序的 MANIFEST.MF 文件或 jboss-deployment-structure.xml 部署描述符文件来配置显式模块依赖项。

如果在应用中定义明确的模块依赖项,您应该了解 JBoss EAP 7 中的以下更改。

查看依赖项以实现高可用性

JBoss EAP 中包含的模块已更改。将应用程序迁移到 JBoss EAP 7 时,请查看 MANIFEST.MFjboss-deployment-structure.xml 文件条目,以确保它们没有引用从该产品中删除的任何模块。

需要扫描的依赖关系

在之前的 JBoss EAP 版本中,如果您的依赖项包含在注解扫描期间被处理所需的注释,如声明 EJB 拦截器时,您需要在新 JAR 文件中生成并包括 Jandex 索引,然后在 MANIFEST.MFjboss-deployment-structure.xml 部署描述符文件中设置标记。

JBoss EAP 7 现在为静态模块提供自动运行时的注解索引,因此您无需手动生成它们。但是,您仍然需要在应用程序的 MANIFEST.MF 文件或 jboss-deployment-structure.xml 部署描述符文件中添加 annotations 标记。

示例:在 MANIFEST.MF 文件中注解标记

Dependencies: com.company.my-ejb annotations, com.company.other

示例:说明 jboss-deployment-structure.xml 文件中的 Flag

<jboss-deployment-structure>
  <deployment>
    <dependencies>
      <module name="com.company.my-ejb" annotations="true"/>
      <module name="com.company.other"/>
    </dependencies>
  </deployment>
</jboss-deployment-structure>

5.8. Hibernate 和 Jakarta Persistence 迁移更改

5.8.1. Hibernate ORM 3.0

在 JBoss EAP 6.4 中使用 Hibernate ORM 3 的整合类已经从 JBoss EAP 7 中移除。如果您的应用程序仍然使用 Hibernate ORM 3 库,则强烈建议您迁移应用程序以使用 Hibernate ORM 5 作为 Hibernate ORM 5 作为 Hibernate ORM 3,无需大量工作。如果您无法迁移到 Hibernate ORM 5,您必须为 Hibernate ORM 3 JARs 定义自定义 JBoss 模块,并不包括应用程序中的 Hibernate ORM 5 类。

5.8.2. Hibernate ORM 4.0 - 4.3

如果您的应用程序需要启用第二级别的缓存,请注意 Infinispan 8.x 与 Hibernate ORM 5.0 集成。支持将 Infinispan 用作 Hibernate 2nd 级缓存提供商,然后被移到 Hibernate ORM 5.3 中的 Infinispan 项目,因此,Ehiber n-infinispan 模块已从该版本丢弃。

使用 Hibernate ORM 4.x 编写的应用程序仍然可以使用 Hibernate ORM 4.x。您必须为 Hibernate ORM 4.x JARs 定义自定义 JBoss 模块,并从应用程序中排除 Hibernate ORM 5 类。但是,强烈建议您重写应用程序代码以使用 Hibernate ORM 5。有关迁移到 Hibernate ORM 5 的详情,请参考 Migrating to Hibernate ORM 5

5.8.3. 迁移到 Hibernate ORM 5

JBoss EAP 7.0 包含 Hibernate ORM 5.0。本节重点介绍从 Hibernate ORM 版本 4.3 迁移到版本 5 时所需的更改。有关在 Hibernate ORM 4 和 Hibernate ORM 5 之间实现的更改的更多信息,请参阅 Hibernate ORM 5.0 迁移指南

删除和弃用的类

以下已弃用的类已从 Hibernate ORM 5 中删除:

对类和软件包的其他更改
类型处理
事务管理
其他 Hibernate ORM 5 更改

5.8.4. 从 Hibernate ORM 5.0 迁移到 Hibernate ORM 5.1

JBoss EAP 7.1 包含 Hibernate ORM 5.1。本节重点介绍从 Hibernate ORM 版本 5.0 迁移到版本 5.1 所需的区别和所需更改。

Hibernate ORM 5.1 功能

Hibernate 的这个发行版本包括了很多性能改进和程序错误修复,它们包括在 JBoss EAP 7.1.0 发行注记中的 Hibernate ORM 5.1 功能 中。有关在 Hibernate ORM 5.0 和 Hibernate ORM 5.1 之间实施的更改的更多信息,请参阅 Hibernate ORM 5.1 迁移指南

模式管理工具更改
JBoss EAP 7 中的模式管理工具更改

Hibernate ORM 5.1 中的模式管理工具更改主要关注以下区域:

  • 统一处理 hbm2ddl.auto 和 Hibernate 的 Jakarta Persistence schema-generation 支持。
  • 从 SPI 中删除 JDBC 顾虑,以促进 Hibernate OGM(一种为 NoSQL 数据存储提供 Jakarta Persistence 支持)的持久性引擎。

模式管理工具更改应该只针对直接使用任何类的应用程序进行迁移:

  • org.hibernate.tool.hbm2ddl.SchemaExport
  • org.hibernate.tool.hbm2ddl.SchemaUpdate
  • org.hibernate.tool.hbm2ddl.SchemaValidator
  • org.hibernate.tool.schema.spi.SchemaManagementTool 或其任何委托
JBoss EAP 7.1 中的模式管理工具更改

Hibernate ORM 5.1.10(包含在 JBoss EAP 7.1 中)引入了一种用于检索数据库表的新策略,用于提高 SchemaMigratorSchemaValidator 性能。此策略执行单个 java.sql.DatabaseMetaData#getTables(String, String, String[]) 调用来确定每个 javax.persistence.Entity 都有映射的数据库表。这是默认的策略,它使用 hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=grouped 属性设置。此策略可能要求提供 hibernate.default_schema 和/或 hibernate.default_catalog

要使用旧的策略,它会执行 java.sql.DatabaseMetaData#getTables(String, String, String, String[]) 调用每个 javax.persistence.Entity,使用 hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=individly 属性设置。

5.8.5. 从 Hibernate ORM 5.1 迁移到 Hibernate ORM 5.3

JBoss EAP 7.4 包括 Hibernate ORM 5.3.本节重点介绍从 Hibernate ORM 5.1 迁移到 Hibernate ORM 5.3 时所需的一些更改。

Hibernate ORM 5.2 功能

Hibernate ORM 5.2 使用 Java 8 JDK 构建,需要在运行时使用 Java 8 JRE。以下是本发行版本中进行的一些更改列表:

  • hibernate-java8 模块已合并到 hibernate-core 中,Java 8 日期/时间数据类型现已原生支持。
  • hibernate-entitymanager 模块合并到 hibernate-core 中。HibernateEntityManagerHibernateEntityManagerFactory 已被弃用。
  • SessionStatelessSessionSessionFactory 类层次结构被重构为移除已弃用的类,并与 Jakarta Persistence Metamodel API 更好地保持一致。
  • org.hibernate.persisterorg.hibernate.tuple 软件包中的 SPIs 已更改。任何使用这些 SPI 的自定义类别都需要检查和更新。
  • LimitHandler 更改引入了一个新的 hibernate.legacy_limit_handler 设置,默认设置为 false,它旨在允许您启用旧的 Hibernate 4.3 限制处理器行为。这会影响有限问题列表。
  • 引入了一个新的检索数据库表的策略,改进了 SchemaMigratorSchemaValidator 性能。
  • 此发行版本更改了在使用 PostgreSQL81Dialect 及其子类时处理带有 @LobStringcharacter[]Character[] 属性的 CLOB 值的方式。
  • @TableGenerator@SequenceGenerator 名称的范围已从 global 改为 local。

有关 Hibernate 5.2 中实施的更改的完整列表,请参阅 Hibernate ORM 5.2 迁移指南

Hibernate ORM 5.3 功能

Hibernate ORM 5.3 添加了对 Jakarta Persistence 2.2 规范的支持。此发行版本包含有关此规格的更改,以及其他改进。以下是这些更改的列表:

  • 对位置查询参数处理的更改会导致以下更改:

    • 移除在 HQL/Jakarta Persistence 查询语言查询中对 JDBC 样式参数声明的支持。
    • Jakarta Persistence 位置位置参数的行为与命名参数更为相似。
    • 原生查询中的 JDBC 样式参数声明使用单向参数声明,而不是基于零的参数绑定,与 Jakarta Persistence 保持一致。您可以通过将 hibernate.query.sql.jdbc_style_params_base 属性设置为 true 来恢复基于零的绑定。
  • 为遵守 Jakarta Persistence 规格,由 @TableGener 存储的值存储的序列值是最后生成的值。在以前的版本中,Hibernate 存储下一个序列值。您可以使用 hibernate.id.generator.stored_last_used 属性来启用旧的 Hibernate 行为。使用 @TableGenerator 和迁移到 Hibernate 5.3 的现有应用程序必须将 hibernate.id.generator.stored_last_used 配置 属性设置为 false
  • org.hibernate.query.QueryParameter 类中的 getType() 方法被重命名为 getHibernateType()
  • Hibernate 的第二个缓存 SPI 被重新设计,以更好地满足各种缓存供应商的要求。可在 HHH-11356 中找到详情。
  • HHH-11356 的更改还需要更改消费者,这会影响 Hibernate Statistics 系统。
  • 有些方法临时添加到 org.hibernate.Query 类中,以便更轻松地将原生应用程序从 Hibernate ORM 5.1 迁移到 5.3,并维护 Hibernate 5.1 pagination 行为。这些方法已弃用,并在以后使用 Hibernate 版本进行可移植,应用程序应使用 Jakarta Persistence 方法。
  • 支持将 Infinispan 用作 Hibernate 2nd-level 缓存提供商,已移至 Infinispan 项目。因此,hibernate-infinispan 模块已被丢弃。
  • org.hibernate.tool.enhance.EnhancementTask Ant 任务的 API 已更改。addFileset() 方法已被丢弃,而是使用 setBase()setDir() 方法。详情可在 HHH-11795 中找到。
  • Hibernate 4.3 中引入了一个错误,导致嵌入的集合元素和复合 ID 中的多到一关联,即使在显式映射为 lazy 时也是如此。在 Hibernate 5.3.2 中,这个程序错误已被解决。因此,这些关联会根据其映射指定的。详情可在 HHH-12687 中找到。
  • 本发行版本中,Jakarta Persistence 和 Hibernate 事件监听器的原生实现。因此,JpaIntegrator 类已过时。扩展 org.hibernate.jpa.event.spi.JpaIntegrator 的类必须修改,才能将这些类更改为实施 org.hibernate.integrator.spi.spi.Integrator 接口。可在 HHH-11264 中找到详细信息。
  • org.hibernate.persister 软件包中的 SPI 已更改。任何使用这些 SPI 的自定义类别都需要检查和更新。

有关 Hibernate 5.3 中所实施的其他更改的完整列表,请参阅 Hibernate ORM 5.3 迁移指南

5.8.5.1. Hibernate 5.1 和 Hibernate 5.3 之间的异常处理变化

在 Hibernate 5.2 和 5.3 中,使用 Hibernate 的原生 Bootstrap 构建的 SessionFactory 异常处理,按照 Jakarta Persistence 规格嵌套或转换 HibernateException。唯一例外于操作是特定于 Hibernate 时,如 Session.save()Session.saveOrUpdate()

在 Hibernate 5.3.3 中,添加了 hibernate.native_exception_handling_51_compliance 属性。此属性指示,使用 Hibernate 的原生 bootstrap 构建的 Session factory 异常处理是否应该和 Hibernate ORM 5.1 中的原生异常处理相同。当设置为 true 时,会根据 Jakarta Persistence 规范,不会嵌套或转换HibernateException。对于使用 Jakarta Persistence bootstrapping 构建的 SessionFactory,会忽略此设置。

5.8.5.2. 兼容性转换器

JBoss EAP 7.4 包括一个兼容性转换程序,它解决了与 Hibernate ORM 5.1 兼容的 Hibernate ORM 5.3 API 方法。转换程序是一种临时措施,允许使用 Hibernate ORM 5.1 构建的应用程序在 JBoss EAP 7.4 中表现出与 Hibernate 5.3 相同的行为。这是一个临时解决方案,您应该将这些方法调用替换为推荐的 Jakarta Persistence 方法调用。

您可以使用以下方法之一启用转换器:

  • 您可以通过将 Hibernate51CompatibilityTransformer 系统属性设置为 true 为所有应用程序启用转换器。
  • 您可以使用 jboss-deployment-structure.xml 文件在应用程序级别启用转换程序。

    <jboss-deployment-structure>
      <deployment>
        <transformers>
          <transformer class="org.jboss.as.hibernate.Hibernate51CompatibilityTransformer"/>
        </transformers>
      </deployment>
      <sub-deployment name="main.war">
        <transformers>
          <transformer class="org.jboss.as.hibernate.Hibernate51CompatibilityTransformer"/>
        </transformers>
      </sub-deployment>
    </jboss-deployment-structure>

下表列出了正在转换的 Hibernate 5.1 方法,并将其转换为 Hibernate 5.3 方法:

5.9. Hibernate 搜索更改

JBoss EAP 7 附带的 Hibernate Search 版本已更改。之前的 JBoss EAP 版本随 Hibernate Search 4.6.x 一同发布。JBoss EAP 7 附带 Hibernate Search 5.5.x。

Hibernate Search 5.5 基于 Apache Lucene 5.3.1 构建。如果您使用任何原生 Lucene API,请确保与此版本一致。Hibernate Search 5.5 API 换行并隐藏了版本 3 和版本 5 之间进行的许多 Lucene API 更改的复杂性,但一些类现已弃用、重命名或重新打包。本节介绍了这些更改如何影响应用程序代码。

Hibernate 搜索映射更改

为嵌入式关系的 ID 字段索引

当使用 @IndexedE mbedededed 注解包含相关实体中的字段时,不再包含相关实体的 id。您可以使用 @IndexedEmbeded 注解的 includeEmbeded ObjectId 属性启用包括 id

示例 :@IndexedEmbeded 注解

@IndexedEmbedded(includeEmbeddedObjectId=true)

数量和日期索引格式更改

现在,默认情况下,数字和日期被索引为数字字段。intlongfloatdouble 及其对应打包程序类的属性不再被索引为字符串。现在,它们会根据 Lucene 的适当数字编码进行索引。id 字段是此规则的一个例外。即使它们由数字类型表示,也会默认将它们索引为 string 关键字。使用 @NumericField 现已过时,除非您想为数字编码指定自定义精度。您可以通过显式指定字符串 encoding 字段桥接来保留旧的基于字符串的索引格式。如果是整数,这是 org.hibernate.search.bridge.builtin.IntegerBridge。检查 org.hibernate.search.bridge.builtin 软件包,用于其他公开可用的字段网桥。

DateCalendar 不再被索引为字符串。相反,实例会用长值编码,代表自 1970 年 1 月 1 日 00:00:00 GMT 后的毫秒数。您可以使用新的 EncodingType enum 切换索引格式。例如:

示例:@DateBridge@CalendarBridge 注释

@DateBridge(encoding=EncodingType.STRING)
@CalendarBridge(encoding=EncodingType.STRING)

数字和日期的编码更改非常重要,对应用程序的行为有重大影响。如果您有一个以字符串编码的字段为目标的查询,但现在采用数字编码,则必须更新查询。必须使用 NumericRangeQuery 搜索数字字段。您还必须确保通过面对面目标的所有字段都是字符串编码。如果您使用 Search 查询 DSL,则会自动为您创建正确的查询。

其它 Hibernate 搜索更改

  • 对选项进行排序已被改进,字段编码在排序选项中现在会导致运行时异常。如果排序中使用的字段已知,Lucene 还提供更多执行性排序。Hibernate Search 5.5 提供新的 @SortableField 注释,及其多值 companion @SortableFields。如需更多信息,请参阅从 Hibernate Search 5.4 迁移到 5.5
  • Lucene SortField API 需要以下应用程序代码更改:

    在之前的 JBoss EAP 版本中,您可以设置查询中的 sort 字段类型,如下所示:

    fulltextQuery.setSort(new Sort(new SortField("title", SortField.STRING)));

    以下是如何在 JBoss EAP 7 中设置它的示例:

    fulltextQuery.setSort(new Sort(new SortField("title", SortField.Type.STRING)));
  • 由于 SearchFactory 只能供 ORM 集成使用,因此它从 hibernate-search-engine 模块移动到 hibernate-search-orm 模块。其他集成商应完全依赖 SearchIntegrator,它取代了过时的 SearchFactoryIntegrator
  • enum 值 SpatialMode.GRID 被重命名为 SpatialMode.HASH
  • FullTextIndexEventListener 现在是一个最终类。如果您目前扩展了这个课程,您必须找到一个替代的解决方案才能获得相同的功能。
  • hibernate-search-analyzers 模块已被删除。推荐的方法是直接使用适当的 Lucene 工件,如 org.apache.lucene:lucene-analyzers-common
  • Jakarta Messaging 控制器 API 已更改。对 Hibernate ORM 的 Jakarta 消息传递后端依赖性已经被删除,因此可以在其他非ORM 环境中使用它。其结果是,org.hibernate.search.backend.impl.jms.AbstractJMSHibernateSearchController 的实现器必须根据新的签名进行调整。此类是一个内部类,建议将它用作示例,而不是扩展它。
  • org.hibernate.search.spi.ServiceProvider SPI 被重构。如果您与旧服务合同集成,请参阅 Hibernate Search 5.5 Javadoc Service、 Service 、startableStoppable 了解新合同的详细信息。
  • 如果您保留了 Lucene 3.x 生成的索引,且已使用 Hibernate Search 5.0 或更高版本进行重建,您将得到 IndexFormatTooOldException。建议您使用大量索引器重建索引。如果您无法做到这一点,请尝试使用 Lucene 的 IndexUpgrader。在更改默认行为时,您必须仔细更新 Hibernate Search 映射。如需更多信息,请参阅 Apache Lucene Migration Guide
  • 在 JBoss EAP 7 中,Apache Lucene 从 3.6 升级到 5.3。如果您的代码直接导入 Lucene 代码,请参阅 Apache Lucene Migration Guide 了解详情。还可在 Lucene Change Log 中找到其他信息。
  • 使用 @Field(indexNullAs=) 在索引中编码 null 标记值时,标记的类型必须与同字段中索引的所有其他值兼容。例如,之前可以对类型为数字的字段中的 null 值使用字符串"null"。这不再被允许。现在,您需要选择一个代表 null 的值,例如 -1
  • 对面对引擎进行了显著改进。大多数更改不会影响 API。一个值得注意的例外是,您必须注解任何您要用于与 @Facet@Facets 注解相关的字段。

Hibernate 搜索重命名和重新打包类

以下是已重新打包或重命名的 Hibernate 搜索类列表:

以前的软件包和类新的软件包和类

org.hibernate.search.Environment

org.hibernate.search.cfg.Environment

org.hibernate.search.FullTextFilter

org.hibernate.search.filter.FullTextFilter

org.hibernate.search.ProjectionConstants

org.hibernate.search.engine.ProjectionConstants

org.hibernate.search.SearchException

org.hibernate.search.exception.SearchException

org.hibernate.search.Version

org.hibernate.search.engine.Version

Lucene: Renamed 和 repackaged 类

查询解析器已移至新模块,结果是软件包从 org.apache.lucene.queryParser.QueryParser 变为 org.apache.lucene.queryparser.classic.QueryParser

许多 Lucene 分析器都已重构,结果是软件包的变化。请参阅 Apache Lucene 文档 来查找替换软件包。

一些 Apache Solr 实用程序类(如 TokenizerFactoryTokenFilterFactory )被移到 Apache Lucene 中。如果您的应用程序使用这些实用程序或自定义分析器,则必须在 Apache Lucene 中找到新的软件包名称。

如需更多信息,请参阅 Apache Lucene 迁移指南

Hibernate 搜索已弃用的 API

有关 Hibernate 搜索已弃用接口、类、枚举、注解类型、方法、构造器和枚举 API 文档的完整列表,请参阅 Hibernate Search Decated API 文档。

Hibernate 搜索已弃用的接口
Interface描述

org.hibernate.search.store.IndexShardingStrategy

从 Hibernate Search 4.4 开始已弃用。可能会在搜索 5 中删除。改为使用 ShardIdentifierProvider

org.hibernate.search.store.Workspace

此接口将移动,并且应该被视为非公共 API。如需更多信息,请参阅 HSEARCH-1915

Hibernate 搜索已弃用的类
描述

org.hibernate.search.filter.FilterKey

自定义过滤器键已弃用,并计划在 Hibernate Search 6 中删除。从 Hibernate Search 5.1 开始,根据给定的过滤器参数自动计算缓存 Lucene 过滤器的密钥。

org.hibernate.search.filter.StandardFilterKey

自定义过滤器键已弃用,并计划在 Hibernate Search 6 中删除。从 Hibernate Search 5.1 开始,根据给定的过滤器参数自动计算缓存 Lucene 过滤器的密钥。

Hibernate 搜索已弃用的 enums
Enum描述

org.hibernate.search.annotations.FieldCacheType

删除 CacheFromIndex 注解,因为它已弃用。请参阅 Hibernate 搜索已弃用的注释

Hibernate 搜索已弃用的注解
注解描述

org.hibernate.search.annotations.CacheFromIndex

移除注解。不需要替代方案。

org.hibernate.search.annotations.Key

自定义过滤器缓存键是已弃用的功能,在 Hibernate Search 6 中删除。从 Hibernate Search 5.1 开始,根据过滤器参数自动决定过滤缓存密钥,因此不再需要提供密钥对象。

Hibernate 搜索已弃用的方法
方法描述

org.hibernate.search.FullTextSharedSessionBuilder.autoClose()

没有替换

org.hibernate.search.FullTextSharedSessionBuilder.autoClose(boolean)

没有替换

org.hibernate.search.cfg.IndexedMapping.cacheFromIndex(FieldCacheType…​)

这将在没有替换的情况下删除。

org.hibernate.search.cfg.EntityDescriptor.getCacheInMemory()

这将在没有替换的情况下删除。

org.hibernate.search.cfg.ContainedInMapping.numericField()

改为调用 field().numericField()

org.hibernate.search.cfg.EntityDescriptor.setCacheInMemory(Map<String, Object>)

这将在没有替换的情况下删除。

org.hibernate.search.MassIndexer.threadsForSubsequentFetching(int)

此方法将被删除。

org.hibernate.search.query.dsl.FuzzyContext.withThreshold(float)

使用 FuzzyContext.withEditDistanceUpTo(int)

Hibernate 搜索已弃用的构造器
Constructor描述

org.hibernate.search.cfg.NumericFieldMapping(PropertyDescriptor, EntityDescriptor, SearchMapping)

使用 NumericFieldMapping.NumericFieldMapping(String, PropertyDescriptor, EntityDescriptor, SearchMapping)

影响高级集成商的变化

本节介绍不是公共 API 的一部分的更改。它们不应该影响平均开发人员,因为工件只能被扩展 Hibernate Search 框架的集成访问。

5.10. 将实体 Bean 迁移到 Jakarta Persistence

对 EJB 实体 Bean 的支持在 Jakarta EE 8 中是可选的,在 JBoss EAP 7 中不支持它们。

在以前的 JBoss EAP 版本中,实体 Bean 通过扩展 javax.ejb.EntityBean 类和实施必要的方法,在应用源代码中创建。然后,在 ejb-jar.xml 文件中配置它们。CMP entity bean 由一个 <entity> 元素来指定,该元素包含值为 Container<persistence-type> 子元素。BMP entity bean 由一个 <entity> 元素来指定,其中包含一个 <persistence-type> 子元素,值为 Bean

在 JBoss EAP 7 中,您必须将您的代码中的任何 CMP 和 BMP 实体 Bean 替换为 Jakarta Persistence 实体。Jakarta Persistence 实体使用 javax.persistence.* 类创建,并在 persistence.xml 文件中定义。

以下是 Jakarta Persistence 实体类的示例:

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;
import javax.persistence.Table;

@Entity
// User is a keyword in some SQL dialects!
@Table(name = "MyUsers")
public class MyUser {
    @Id
    @GeneratedValue
    private Long id;

    @Column(unique = true)
    private String username;
    private String firstName;
    private String lastName;

    public Long getId() {
        return id;
    }
    public String getUsername() {
        return username;
    }
    public void setUsername(String username) {
        this.username = username;
    }
    public String getFirstName() {
        return firstName;
    }
    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }
    public String getLastName() {
        return lastName;
    }
    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

以下是 persistence.xml 文件的示例。

<persistence version="2.1"
      xmlns="http://xmlns.jcp.org/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="
        http://xmlns.jcp.org/xml/ns/persistence
        http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd">
  <persistence-unit name="my-unique-persistence-unit-name">
    <properties>
      // properties...
    </properties>
  </persistence-unit>
</persistence>

有关 Jakarta Persistence 实体的工作示例,请查看 JBoss EAP 7 附带的 bmtcmthibernate5 快速入门。

5.11. jakarta Persistence 属性更改

JBoss EAP 7.0 中引入的 Jakarta Persistence 属性更改

添加了一个新的持久性属性 jboss.as.jpa.deferdetach,以便与之前的 JBoss EAP 版本中的持久性行为兼容。

jboss.as.jpa.deferdetach 属性控制在每个实体 EntityManager 调用后,在非Jakarta 事务性环境中使用的事务范围持久性上下文以及是否等待持久性上下文关闭时(例如,会话 bean 调用结束时)。属性值默认为 false,即实体在各个 EntityManager 调用后被分离或清除。这是 Jakarta Persistence 规范中定义的正确默认行为。如果属性值设置为 true,则在持久化上下文关闭之前,实体不会被分离。

在 JBoss EAP 5 中,持久性的行为如同 jboss.as.jpa.deferdetach 属性设为 true。要在将应用从 JBoss EAP 5 迁移到 JBoss EAP 7 时获得同样的行为,您必须在 persistence.xml 中将 jboss.as.jpa.deferdetach 属性值设置为 true,如下例所示。

<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
    <persistence-unit name="EAP5_COMPAT_PU">
    <jta-data-source>java:jboss/datasources/ExampleDS</jta-data-source>
    <properties>
         <property name="jboss.as.jpa.deferdetach" value="true" />
    </properties>
  </persistence-unit>
</persistence>

在 JBoss EAP 6 中,持久性的行为如同 jboss.as.jpa.deferdetach 属性设为 false。这与 JBoss EAP 7 中看到的行为相同,因此迁移应用程序时不需要任何更改。

JBoss EAP 7.1 中引入的 Jakarta Persistence 属性更改

在 JBoss EAP 7.0 中,未同步持久性上下文错误检查不严格,因为它应该在以下区域:

  • 同步容器管理的持久性上下文允许使用与 Jakarta 事务关联的未同步扩展持久性上下文。相反,应该已经抛出一个 IllegalStateException,以防止使用未同步持久性上下文。
  • 部署描述符中指定的未同步持久性上下文被视为同步。

另外,JBoss EAP 7.0 中错误地忽略 @PersistenceContext 中的 PersistenceProperty 提示。

JBoss EAP 7.1 及之后的版本中解决了这些问题。由于这些更新可能会导致应用程序行为意外改变,在 JBoss EAP 7.1 中引入了两个新的持久性单元属性,以提供向后兼容性并保留之前的行为。

属性描述

wildfly.jpa.skipmixedsynctypechecking

此属性禁用错误检查。如果应用程序在 JBoss EAP 7.0 中工作,且在 JBoss EAP 7.1 及之后的版本中发生故障时,它才会用作临时性措施。因为此属性可能会在以后的版本中被弃用,因此建议您在可以这样做时立即更正应用程序代码。

wildfly.jpa.allowjoinedunsync

此属性是 wildfly.jpa.skipmixedsynctypechecking 的替代选择。它允许应用程序对待与 Jakarta 事务相关联的未同步持久性上下文,就像它们是同步持久性上下文一样。

5.12. 迁移 Jakarta Enterprise Beans 客户端代码

注意

JBoss EAP 7 不支持企业实体 Bean。有关如何将实体 Bean 迁移到 Jakarta Persistence 的信息,请参阅将 实体 Beans 迁移到 Jakarta Persistence

5.12.1. Jakarta Enterprise Beans 在 JBoss EAP 7 中的客户端变化

JBoss EAP 7 中更改了默认远程连接器和端口。有关此更改的详情,请参阅更新远程 URL Connector 和端口

如果您使用 migrate 操作来迁移服务器配置,则会保留旧的设置,您不需要在此处进行更改。但是,如果您使用新的 JBoss EAP 7 默认配置,您必须进行以下更改:

5.12.1.1. 更新默认远程连接端口

jboss-ejb-client.properties 文件中,将远程连接端口值从 4447 更改为 8080。以下是前面和当前版本的 jboss-ejb-client.properties 文件示例:

示例:JBoss EAP 6 jboss-ejb-client.properties 文件

remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
remote.connections=default
remote.connection.default.host=localhost
remote.connection.default.port=4447
remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONYMOUS=false

示例:JBoss EAP 7 jboss-ejb-client.properties 文件

remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
remote.connections=default
remote.connection.default.host=localhost
remote.connection.default.port=8080
remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONYMOUS=false

5.12.1.2. 更新默认连接器

如果您使用新的 JBoss EAP 7 配置,默认的连接器已从 远程 改为 http-remoting。这个变化会影响使用 JBoss EAP 的一个发行版本的库连接到不同版本中的服务器。

  • 如果客户端应用使用 JBoss EAP 6 中的 Jakarta Enterprise Beans 客户端库,并且想连接到 JBoss EAP 7 服务器,则必须将服务器配置为在端口 8080 之外的端口上公开 远程 连接器。然后,客户端必须使用那个新配置的连接器进行连接。
  • 使用 JBoss EAP 7 的 Jakarta Enterprise Beans 客户端库的客户端应用程序,希望连接到 JBoss EAP 6 服务器,必须清楚服务器实例不使用 http-remoting 连接器,而是使用 远程 连接器。这可以通过定义新的客户端连接属性来实现。

    示例: 远程连接 属性

    remote.connection.default.protocol=remote

5.12.2. 迁移远程命名客户端代码

如果您使用新的默认 JBoss EAP 7 配置运行,您必须修改客户端代码,以使用新的默认远程端口和连接器。

以下是如何在 JBoss EAP 6 中客户端代码指定远程命名属性的示例。

java.naming.factory.initial=org.jboss.naming.remote.client.InitialContextFactory
java.naming.provider.url=remote://localhost:4447

以下示例说明了如何在 JBoss EAP 7 中指定客户端代码中的远程命名属性。

java.naming.factory.initial=org.wildfly.naming.client.WildFlyInitialContextFactory
java.naming.provider.url=http-remoting://localhost:8080

5.12.3. JBoss EAP 7.1 中引入的其他 JBoss EJB 客户端更改

虽然 JBoss EAP 7.0 由 JBoss EJB 客户端 2.1.4 提供,但 JBoss EAP 7.1 及更新版本随 JBoss EJB 客户端 4.0.x 一起提供,但包括了对 API 的一些更改。

注意

JBoss EAP 7 不支持企业实体 Bean。有关如何将实体 Bean 迁移到 Jakarta Persistence 的信息,请参阅将 实体 Beans 迁移到 Jakarta Persistence

  • org.ejb.client.ejbClientInvocationContext 类已添加以下新方法:

    方法类型描述

    isBlockingCaller()

    布尔值

    确定此调用当前是否阻止调用线程。

    isClientAsync()

    布尔值

    确定方法是否标记为客户端,这意味着无论服务器端的方法是否是异步的,调用也应该是异步的。

    isIdempotent()

    布尔值

    确定该方法是否标记为 idempotent,这意味着可以多次调用方法而不产生额外的效果。

    setBlockingCaller(boolean)

    void

    建立此调用当前是否阻止调用线程。

    setLocator(EJBLocator<T>)

    <T> void

    为调用目标设置 locator。

  • org.ejb.client.ejbLocator 类添加了以下新方法:

    方法类型描述

    asStateful()

    StatefulEJBLocator<T>

    将此 locator 返回为有状态的 locator(如果是)。

    asStateless()

    StatelessEJBLocator<T>

    将此 locator 返回为无状态的 locator(如果是)。

    isEntity()

    布尔值

    确定这是否是实体 locator。

    isHome()

    布尔值

    确定这是否是家 locator。

    isStateful()

    布尔值

    确定这是否是状态 locator。

    isStateless()

    布尔值

    确定这是否是无状态 locator。

    withNewAffinity(Affinity)

    abstract EJBLocator<T>

    创建这个 locator 的一个副本,但具有新的给定关联性。

  • 引入了一个新的 org.ejb.client.ejbClientPermission 类,它是 java.security.Permission 的子类,用于控制对特权 EJB 操作的访问。它提供以下构造器:

    • EJBClientPermission(String name)
    • EJBClientPermission(字符串名称,字符串操作)
  • 它提供以下方法:

    方法类型描述

    equals(EJBClientPermission obj)

    布尔值

    检查两个 EJBClientPermission 对象是否相等。

    equals(Object obj)

    布尔值

    检查两个 Permission 对象是否相等。

    等于(权限 obj)

    布尔值

    检查两个 Permission 对象是否相等。

    getActions()

    字符串

    以字符串形式返回操作。

    hashcode()

    int

    返回此 Permission 对象的散列代码值。

    表示(EJBClientPermission)

    布尔值

    检查指定权限的行为是否由 EJBClientPermission 对象的行为决定

    表示(权限)

    布尔值

    Permission 对象的操作是否 暗示 了指定权限的操作。

  • 引进了一个新的 org.ejb.client.ejbMethodLocator 类,以查找特定的 EJB 方法。它提供以下构造器:

    • EJBMethodLocator(String methodName, String…​ parameterTypeNames)
  • 它提供以下方法:

    方法类型描述

    等于(EJBMethodLocator 其他)

    布尔值

    确定此对象是否等于另一个对象。

    等于(其他对象)

    布尔值

    确定此对象是否等于另一个对象。

    forMethod(Method 方法)

    静态 EJBMethodLocator

    获取给定反射方法的方法定位器。

    getMethodName()

    字符串

    获取方法名称。

    getParameterCount()

    int

    获取参数数。

    getParameterTypeName(int index)

    字符串

    获取给定索引中的参数名称。

    hashCode()

    int

    获取哈希代码。

  • 在故障情况下,引入了一个新的 org.jboss.ejb.client.ejbReceiverInvocationContext.ResultProducer.Failed 类。它提供以下构造器:

    • failed(Exception 原因)
  • 它提供以下方法:

    方法类型描述

    discardResult()

    void

    丢弃结果,表示将不会使用。

    getResult()

    对象

    获取结果。

  • 引进了一个新的 org.jboss.ejb.client.ejbReceiverInvocationContext.ResultProducer.Immediate 类来获取即时结果。它提供以下构造器:

    • failed(Exception 原因)
  • 它提供以下方法:

    方法类型描述

    discardResult()

    void

    丢弃结果,表示将不会使用。

    getResult()

    对象

    获取结果。

  • 针对 URI 关联性规格引入了一个新的 org.jboss.ejb.client.URIAffinity 类,它是 org.jboss.ejb.client.Affinity 的子类。它使用 Affinity.forUri(URI) 创建。
  • 它提供以下方法:

    方法类型描述

    等于(关联性其他)

    布尔值

    指明另一个对象是否等于这个对象。

    等于(其他对象)

    布尔值

    指明另一个对象是否等于这个对象。

    等于(URIAffinity 其他)

    布尔值

    指明另一个对象是否等于这个对象。

    getURI()

    URI

    获取关联的 URI。

    hashCode()

    int

    获取哈希代码。

    toString()

    字符串

    返回对象的字符串表示。

  • org.jboss.ejb.client.ejbMetaDataImpl 类已弃用:

    • toAbstractEJBMetaData()
    • EJBMetaDataImpl(AbstractEJBMetaData<?,?>)

5.12.4. JBoss EAP 7 所需的 EJB 客户端更改

在 JBoss EAP 7.2 中,将 org.apache.santuario.xmlsec 模块从 2.0.8 升级到 2.1.1 会导致对 PicketLinkSTS 中的 remoting 进行回归。作为以下运行时例外,问题清单本身:

java.lang.IllegalArgumentException: ELY05131: Invalid ASCII control "0xA"

这是因为断言中生成的 SignatureValue 中的格式化更改导致。在以前的版本中,生成的值类似如下:

<dsig:SignatureValue xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">cUNpFJIZlLYrBDZtQSTDrq2K6PbnAHyg2qbx/D5FuB4XMjdQ5oxQjkMejLyelnA7s4GFusoLhahlqlTOT8UrOyxrR4yYAmJ/e5s+f4gys926+tbiraT/3/wG8wM/Lvcjvk5Ap69zODuRYpypsWfA4jrI7TTBXVPGy8g4KUdnFviUiTuFTc2Ghgxp53AmUuLis/THyP28jE7+28//q8bi/bQrFwHC6tWX67+NK1duFCOcQ6IPIKeVrePZz55Ivgl+WWdkF6uYCz5IdMzurhzmeQ3K8DAMIxz/MG67VWJIOnuGNWF7nmdye5zd9AFcRsr1XadvZJCbGNfuc89AL5inCg==</dsig:SignatureValue>

在 JBoss EAP 7.2 中,生成的字符串值现在包含无效隐藏 ASCII 0xD carriage 返回和 0xA 行源控制字符的实例。

<dsig:SignatureValue xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">cUNpFJIZlLYrBDZtQSTDrq2K6PbnAHyg2qbx/D5FuB4XMjdQ5oxQjkMejLyelnA7s4GFusoLhahl&#13;
qlTOT8UrOyxrR4yYAmJ/e5s+f4gys926+tbiraT/3/wG8wM/Lvcjvk5Ap69zODuRYpypsWfA4jrI&#13;
7TTBXVPGy8g4KUdnFviUiTuFTc2Ghgxp53AmUuLis/THyP28jE7+28//q8bi/bQrFwHC6tWX67+N&#13;
K1duFCOcQ6IPIKeVrePZz55Ivgl+WWdkF6uYCz5IdMzurhzmeQ3K8DAMIxz/MG67VWJIOnuGNWF7&#13;
nmdye5zd9AFcRsr1XadvZJCbGNfuc89AL5inCg==</dsig:SignatureValue>

如果您遇到描述的运行时异常,请更新您的客户端代码,从返回的断言字符串中删除隐藏的 ASCII 字符。例如,假设您的当前代码类似以下示例:

WSTrustClient client = new WSTrustClient("PicketLinkSTS", "PicketLinkSTSPort",
                "http://localhost:8080/picketlink-sts/PicketLinkSTS", new WSTrustClient.SecurityInfo(username, password));
Element assertion = client.issueToken(SAMLUtil.SAML2_TOKEN_TYPE);

// Return the assertion as a string
String assertionString = DocumentUtil.getNodeAsString(assertion);
...
properties.put("remote.connection.main.password", assertionString);

您必须添加一个代码行,以删除无效隐藏的 ASCII 0xD carriage 返回和 0xA 行源字符的发生次数;例如:

WSTrustClient client = new WSTrustClient("PicketLinkSTS", "PicketLinkSTSPort",
                "http://localhost:8080/picketlink-sts/PicketLinkSTS", new WSTrustClient.SecurityInfo(username, password));
Element assertion = client.issueToken(SAMLUtil.SAML2_TOKEN_TYPE);

// Return the assertion as a string, stripping the invalid hidden ASCII characters
String assertionString = DocumentUtil.getNodeAsString(assertion).replace(String.valueOf((char) 0xA), "").replace(String.valueOf((char) 0xD), "");
...
properties.put("remote.connection.main.password", assertionString);

5.13. 迁移客户端以使用 WildFly 配置文件

在发布 7.1 之前,JBoss EAP 客户端库(如 EJB 和命名)使用不同的配置策略。JBoss EAP 7.1 引入了 wildfly-config.xml 文件,其目的是将所有客户端配置统一至单个配置文件,这与处理服务器配置的方式类似。

例如,在 JBoss EAP 7.1 之前,您可以使用 jboss-ejb-client.properties 文件或以编程方式使用 Properties 类设置属性,为 EJB 客户端创建新的 InitialContext

示例: jboss-ejb-client.properties 属性文件

remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
remote.connections=one
remote.connection.one.port=8080
remote.connection.one.host=127.0.0.1
remote.connection.one.username=quickuser
remote.connection.one.password=quick-123

在 JBoss EAP 7.1 及之后的版本中,您可以在客户端存档的 META-INF/ 目录中创建 wildfly-config.xml 文件。这是使用 wildfly-config.xml 文件相同的配置。

示例:使用 wildfly-config.xml 文件评估配置

<configuration>
    <authentication-client xmlns="urn:elytron:client:1.2">
        <authentication-rules>
            <rule use-configuration="ejb"/>
        </authentication-rules>
        <authentication-configurations>
            <configuration name="ejb">
                <set-user-name name="quickuser"/>
                <credentials>
                    <clear-password password="quick-123"/>
                </credentials>
            </configuration>
        </authentication-configurations>
    </authentication-client>
    <jboss-ejb-client xmlns="urn:jboss:wildfly-client-ejb:3.0">
        <connections>
            <connection uri="remote+http://127.0.0.1:8080" />
        </connections>
    </jboss-ejb-client>
</configuration>

其他资源

5.14. 迁移部署计划配置

Java EE 应用程序部署规格(JSR-88) 旨在定义标准合同,以便从多个供应商提供工具,以便在任何 Java EE 平台产品中配置和部署应用程序。需要 Java EE 产品提供程序的合同要求用于实施 DeploymentManager 和其他 javax.enterprise.deploy.spi 接口,以便由工具提供者访问。对于 JBoss EAP 6,则部署计划由名为 deployment-plan.xml 的 XML 描述符来标识,该描述符在 ZIP 或 JAR 存档中捆绑。

此规范的采用率非常少,因为大多数应用服务器产品提供了他们自己的"功能丰富"部署解决方案。因此,Java EE 7 丢弃了 JSR-88 支持,并随后从 JBoss EAP 7 中丢弃了 JSR-88 的支持。

如果您使用 JSR-88 来部署应用,则必须使用其他方法来部署应用。JBoss EAP 管理 CLI 部署命令提供了将存档部署到单机服务器或受管域中的服务器组的标准方式。有关管理 CLI 的更多信息,请参阅 管理 CLI 指南

5.15. 迁移自定义应用程序 Valves

您必须手动迁移 jboss-web.xml XML 文件中定义的任何 valves 或 valves。这包括通过扩展 jboss-web.xml 描述符文件的 <valve> 元素配置的 org.apache.catalina.valves.ValveBase 创建的值。

重要

自定义 valves 以及在 jboss-web.xml 文件中定义的 valves 必须被重写,或由相应的对应的 Undertow built-in handler 替代。有关映射 valves 到 Undertow 处理程序的信息,请参阅迁移 JBoss Web Valves

使用 Undertow 内置身份验证机制,必须手动替换身份验证 valves。

在部署中迁移 Valves 配置

在 JBoss EAP 6 中,您可以在应用程序级别定义自定义 valves,方法是在 jboss-web.xml web 应用描述符文件中配置它们。在 JBoss EAP 7 中,也可以使用 Undertow 处理程序进行此操作。

以下是 JBoss EAP 6 中 jboss-web.xml 文件中配置的 valve 示例。

<jboss-web>
    <valve>
        <class-name>org.jboss.examples.MyValve</class-name>
​        <param>
    ​        <param-name>myParam</param-name>
​            <param-value>foobar</param-value>
    ​    </param>
    </valve>
</jboss-web>

有关如何在 JBoss EAP 中创建和配置自定义处理程序的更多信息,请参阅 JBoss EAP 开发指南中的创建自定义处理程序

迁移自定义身份验证器 Valves

有关如何迁移验证器的详情,请参考本指南中的 Migrate Authenticator Valves

5.16. 安全应用程序更改

使用 Undertow 取代 JBoss Web 需要更改 JBoss EAP 7 中的安全配置。

5.16.1. 迁移 Authenticator Valves

如果您创建了自定义验证器 valve 在 JBoss EAP 6.4 中扩展了 AuthenticatorBase,则必须手动将它替换为 JBoss EAP 7 中的自定义 HTTP 身份验证实施。HTTP 身份验证机制是在 elytron 子系统中创建的,然后注册到 undertow 子系统。有关如何实施自定义 HTTP 身份验证机制的详情,请参考 JBoss EAP 开发指南中的自定义 HTTP 机制

5.16.3. 其他安全应用程序更改

有关使用 Kerberos 进行 SSO 配置差异的信息,请参阅如何为 JBoss EAP 设置 SSO 中的配置旧版本 JBoss EAP 中的区别

5.17. JBoss Logging 更改

如果您的应用程序使用 JBoss Logging,请注意在 JBoss EAP 7 中弃用了 org.jboss.logging 软件包中的注解。它们已移到 org.jboss.logging.annotations 软件包中,因此您必须更新源代码来导入新软件包。

该注解还移至单独的 Maven groupId:artifactId:version (GAV)ID,您需要在项目 pom.xml 文件中为 org.jboss.logging:jboss-logging-annotations 添加一个新项目依赖项。

注意

只有日志记录注解已移动。org.jboss.logging.BasicLoggerorg.jboss.logging.Logger 仍存在于 org.jboss.logging 软件包中。

下表列出了已弃用的注解类和对应的替换。

表 5.1. 弃用的日志记录注解

弃用的类替换类

org.jboss.logging.Cause

org.jboss.logging.annotations.Cause

org.jboss.logging.Field

org.jboss.logging.annotations.Field

org.jboss.logging.FormatWith

org.jboss.logging.annotations.FormatWith

org.jboss.logging.LoggingClass

org.jboss.logging.annotations.LoggingClass

org.jboss.logging.LogMessage

org.jboss.logging.annotations.LogMessage

org.jboss.logging.Message

org.jboss.logging.annotations.Message

org.jboss.logging.MessageBundle

org.jboss.logging.annotations.MessageBundle

org.jboss.logging.MessageLogger

org.jboss.logging.annotations.MessageLogger

org.jboss.logging.Param

org.jboss.logging.annotations.Param

org.jboss.logging.Property

org.jboss.logging.annotations.Property

5.18. jakarta Server Faces 代码更改

丢弃了对 Jakarta Server Faces 1.2 的支持

注意

Jakarta Server Faces 是 JavaServer Faces 的新名称。

使用 JBoss EAP 6.4,您可以通过创建 jboss-deployment-structure.xml 文件,在应用程序部署中继续使用 Jakarta Server Faces 1.2。JBoss EAP 7.4 包含 Jakarta Server Faces 2.3,不再支持 Jakarta Server Faces 1.2 API。如果您的应用程序使用 Jakarta Server Faces 1.2,您必须重写为使用 Jakarta Server Faces 2.3。

5.19. 模块类加载更改

在 JBoss EAP 7 中,当多个模块包含多个类或软件包时,类加载行为已更改。

假设有两个模块 MODULE_AMODULE_B,它们相互依赖,并包含其中一些相同的软件包。在 JBoss EAP 6 中,从依赖项加载的类或软件包优先于 module.xml 文件的 resource-root 中指定的。这意味着 MODULE_A 看到 MODULE_BMODULE_B 的软件包会看到 MODULE_A 的软件包。这个行为令人混淆,可能会导致冲突。JBoss EAP 7 中已更改此行为。现在,module.xml 文件中的 resource-root 指定的类或软件包优先于由依赖项指定的那些。这意味着 MODULE_A 查看 MODULE_AMODULE_B 的软件包是 MODULE_B 的软件包。这可防止冲突,并提供更多适当的行为。

如果您定义了包含资源根库或软件包(其模块依赖项中重复)的 resource-root 库或软件包的自定义模块,您可能会看到 ClassCastExceptionLinkageError、类加载错误,或者您将迁移到 JBoss EAP 7 时行为的其他更改。要解决这个问题,您必须配置 module.xml 文件,以确保只使用一个类版本。这可以通过以下方法之一来完成。

  • 您可以避免指定在模块依赖项中重复类的 resource-root
  • 您可以使用 imports and exports 元素的 includeexclude 子元素来控制 module.xml 文件中的类加载。以下是排除类在指定软件包中的导出元素。

    <exports>
      <exclude path="com/mycompany/duplicateclassespath/"/>
    </exports>

如果要保留现有行为,则必须使用 filter 元素过滤 module.xml 文件中的依赖 resource-root 中的依赖关系软件包。这样,您可以在 JBoss EAP 6 下保留现有行为。以下是一个 root-resource 示例,它可过滤指定软件包中的类。

<resource-root path="mycompany.jar">
  <filter>
    <exclude path="com/mycompany/duplicateclassespath"/>
  </filter>
</resource-root>

如需有关模块和类加载的更多信息,请参阅 JBoss EAP 开发指南中的类加载和模块

5.20. 应用程序集群更改

5.20.1. 新集群功能概述

以下列表介绍了在将应用从 JBoss EAP 6 迁移到 JBoss EAP 7 时要了解的一些新的集群功能。

  • JBoss EAP 7 引入了一个新的公共 API,用于构建可显著简化流程的单例服务。有关单例服务的信息,请参阅 JBoss EAP 开发指南中的 HA 单例服务
  • 可以配置单例部署,以一次仅在集群的单个节点上部署和启动。有关更多信息,请参阅 JBoss EAP 开发指南中的 HA 单例部署
  • 现在,您可以定义集群单例 MDB。有关更多信息,请参阅 JBoss EAP 开发 Jakarta Enterprise Beans 中的 Clustered Singleton MDB
  • JBoss EAP 7 包括 Undertow mod_cluster 实施。这提供了一个纯 Java 负载平衡解决方案,不需要 httpd Web 服务器。如需更多信息,请参阅 JBoss EAP 配置指南中的将 JBoss EAP 配置为前端 Load Balancer

本节的其余部分论述了集群更改将如何影响应用程序迁移到 JBoss EAP 7 的迁移。

5.20.2. Web Session 集群更改

JBoss EAP 7 引入了一个新的 Web 会话集群实施。它取代了以前的实施,它与旧的 JBoss Web 子系统源代码紧密耦合。

新的 Web 会话集群实施会影响在 jboss-web.xml JBoss EAP 专有 Web 应用 XML 描述符文件中配置应用程序的方式。以下是保留在此文件中的唯一集群配置元素。

<jboss-web>
  ...
  <max-active-sessions>...</max-active-sessions>
  ...
  <replication-config>
    <replication-granularity>...</replication-granularity>
    <cache-name>...</cache-name>
  </replication-config>
  ...
</jboss-web>

distributable-web 子系统弃用了 jboss-web.xml<replication-config> 元素。它通过生成临时分布式 web 会话配置集来提高 <replication-config> 的使用。

您可以通过按名称引用会话管理配置集或提供特定于部署的会话管理配置来覆盖默认的可分发的会话管理行为。如需更多信息,请参阅 Overide Default Distribut Session Management Behavior

下表论述了如何为 jboss-web.xml 文件中的元素实现类似行为,这些行为现已过时。

Configuration Element更改描述

<max-active-sessions/>

在以前的版本中,如果会话创建超过 < max-active-sessions/> 指定的值,则会话创建会失败

在新的实现中,<max-active-sessions/> 用于启用会话传递。如果会话创建将导致活跃会话的数量超过 & lt;max-active-sessions />,则会话管理器最旧的会话会传给新会话腾出空间。

<passivation-config/>

JBoss EAP 7 不再使用此配置元素及其子元素。

<use-session-passivation/>

在以前的版本中,使用此属性启用 passivation。

在新的实现中,通过为 <max-active-sessions/> 指定非负值来启用 passivation。

<passivation-min-idle-time/>

在以前的版本中,会话需要活跃在成为通过者前的最短时间。这可能导致会话创建失败,即使启用了传递。

新的实现不支持这个逻辑,因此避免这种差异服务(DoS)漏洞。

<passivation-max-idle-time/>

在以前的版本中,会话会在闲置特定时间后被传递。

新实施只支持 lazy passivation。它不支持强制传递。只有在需要符合 <max-active-sessions/> 时,会话才会被传递。

<replication-config/>

distributable-web 子系统弃用此元素。如需更多信息,请参阅分布式 Web 会话配置的 distribut-web 子系统覆盖默认分布式会话管理行为

<replication-trigger/>

在以前的版本中,这个元素用于决定何时触发会话复制。新的实现将这个配置选项替换为单一可靠的策略。如需更多信息,请参阅 JBoss EAP 开发指南中的不可变会话属性

<use-jk/>

在以前的版本中,处理给定请求的节点的 instance-id 附加到 jsessionid 中,供负载均衡器(如 mod_jk、mod_proxy_balancer、mod_cluster)使用,具体取决于为 < use-jk/> 指定的值。

在新的实现中,如果定义,instance-id 始终附加到 jsessionid

<max-unreplicated-interval/>

在以前的版本中,这个配置选项被设计为一种优化,可防止在没有会话属性改变时复制会话的时间戳。虽然这听起来很好,但实际上它不会阻止任何 RPC,因为会话访问需要缓存事务 RPC,无论任何会话属性都已更改。

在新的实现中,会话的时间戳在每次请求中都会复制。这可防止在故障切换后进行过时的会话元数据。

<snapshot-mode/>

在以前的版本中,可以将 <snapshot-mode/> 配置为 INSTANTINTERVAL。Infinispan 的异步复制使该配置选项变得过时。

<snapshot-interval/>

这只适用于 <snapshot-mode>INTERVAL</snapshot-mode>。因为 <snapshot-mode /> 已过时,所以这个选项现在也已过时。

<session-notification-policy/>

在以前的版本中,此属性指定的值定义了用于触发会话事件的策略。

在新的实现中,这种行为由规范驱动的,不可配置。

这个新的实现也支持直写缓存存储以及只激活的缓存存储。通常,将 write-through 缓存存储与无效的缓存结合使用。与内部缓存一同使用时,JBoss EAP 6 中的 Web 会话集群实施无法正常工作。

5.20.3. 覆盖默认的总会话管理行为

您可以使用以下方法之一覆盖默认的可分布式会话管理行为:

  • 按名称引用会话管理配置集
  • 提供特定于部署的会话管理配置
引用现有的会话管理配置集
  • 要使用现有的分布式会话管理配置集,请在应用程序的 /WEB-INF 目录中包含一个 distributable-web.xml 部署描述符。例如:

/WEB-INF/distributable-web.xml

<?xml version="1.0" encoding="UTF-8"?>
<distributable-web xmlns="urn:jboss:distributable-web:1.0">
    <session-management name="foo"/>
</distributable-web>
  • 或者,在现有的 jboss-all.xml 部署描述符中定义目标分布式会话管理配置集:

/META-INF/jboss-all.xml

<?xml version="1.0" encoding="UTF-8"?>
<jboss xmlns="urn:jboss:1.0">
    <distributable-web xmlns="urn:jboss:distributable-web:1.0">
        <session-management name="foo"/>
    </distributable-web>
</jboss>
使用特定于 Deployment 的 Session Management 配置集

如果只有一个 Web 应用使用自定义会话管理配置,您可以在部署描述符本身中定义配置。临时配置与 distributable-web 子系统使用的配置相同。

  • 在部署描述符中定义自定义会话管理配置。例如:

    /WEB-INF/distributable-web.xml

<?xml version="1.0" encoding="UTF-8"?>
<distributable-web xmlns="urn:jboss:distributable-web:1.0">
    <infinispan-session-management cache-container="foo" cache="bar" granularity="SESSION">
        <primary-owner-affinity/>
    </infinispan-session-management>
</distributable-web>
  • 或者,在现有的 jboss-all.xml 部署描述符中定义会话管理配置:

/META-INF/jboss-all.xml

<?xml version="1.0" encoding="UTF-8"?>
<jboss xmlns="urn:jboss:1.0">
    <distributable-web xmlns="urn:jboss:distributable-web:1.0">
        <infinispan-session-management cache-container="foo" cache="bar" granularity="ATTRIBUTE">
            <local-affinity/>
        </infinispan-session-management>
    </distributable-web>
</jboss>

5.20.4. 有状态会话 EJB 集群更改

在 JBoss EAP 6 中,您需要以以下方式之一启用有状态会话 Bean(SFSB)的集群行为:

  • 您可以在 session bean 中添加 org.jboss.ejb3.annotation.Clustered 注解。

    @Stateful
    @Clustered
    public class MyBean implements MySessionInt {
    
       public void myMethod() {
          //
       }
    }
  • 您可以将 < clustered&gt; 元素添加到 jboss-ejb3.xml 文件中。

    <c:clustering>
      <ejb-name>DDBasedClusteredSFSB</ejb-name>
      <c:clustered>true</c:clustered>
    </c:clustering>

JBoss EAP 7 不再需要您启用集群行为。默认情况下,如果服务器使用 HA 配置文件启动,则 SFSBs 的状态将自动复制。您可以使用以下方法之一禁用这个默认行为:

  • 您可以使用 @Stateful(passivationCapable=false) 来禁用单个有状态会话的默认行为,该行为是 EJB 3.2 规范的新。
  • 您可以在服务器配置中 ejb3 子系统的配置全局禁用此行为。
注意

如果 @Clustered 注释没有从应用中删除,它将被简单地忽略,不会影响应用的部署。

5.20.5. 集群服务更改

在 JBoss EAP 6 中,集群服务的 API 位于私有模块中,且不被支持。

JBoss EAP 7 引入了应用程序使用的公共集群服务 API。新服务的设计成轻便、易于注入,并且不需要外部依赖项。

  • 新的 org.wildfly.clustering.group.Group 接口提供了对当前集群状态的访问,并允许侦听集群成员资格更改。
  • 新的 org.wildfly.clustering.dispatcher.CommandDispatcher 接口允许在所有这些或所选节点子集中运行代码。

这些服务取代了之前版本中提供的类似 API,即 JBoss EAP 5 中的 HAPartition,以及 JBoss EAP 6 中的 GroupCommunicationService, GroupMembershipNotifier, 和 GroupRpcDispatcher

如需更多信息,请参阅 JBoss EAP 开发指南中的集群服务公共 API

5.20.6. 迁移集群 HA 单例

在 JBoss EAP 6 中,没有可用于集群范围的 HA 单例服务的公共 API。如果您使用了私有 org.jboss.as.clustering.singleton.* 类,在将应用迁移到 JBoss EAP 7 时,您必须更改您的代码以使用新的公共 org.wildfly.clustering.singleton.* 软件包。

有关 HA 单例服务的更多信息,请参阅 JBoss EAP 开发指南中的 HA 单例服务。有关 HA 单例部署的信息,请参阅 JBoss EAP 开发指南中的 HA 单例部署

第 6 章 其他更改

6.1. JBoss EAP 原生和 Apache HTTP 服务器的交付更改

与过去相比,JBoss EAP 7 原生提供在此版本中。现在,有些产品附带了新的 Red Hat JBoss Core Services 产品,它是大量红帽 JBoss 中间件产品的补充软件。新产品可以加快更新发布速度,以及更一致的更新体验。JBoss Core Services 产品可下载红帽客户门户网站上的不同位置。

  • 下表列出了发行版本间交付方法的不同。

    软件包JBoss EAP 6JBoss EAP 7

    AIO Natives for Messaging

    在单独的 "Native 实用程序" 下载中交付产品

    包括在 JBoss EAP 分发中。不需要额外的下载。

    Apache HTTP 服务器

    在单独的 "Apache HTTP Server" 下载中交付产品

    提供了新的 JBoss Core Services 产品

    mod_cluster、mod_jk、isoapi 和 nsapi 连接器

    在单独的 "Webserver Connector Natives" 下载中交付产品

    提供了新的 JBoss Core Services 产品

    JSVC

    在单独的 "Native 实用程序" 下载中交付产品

    提供了新的 JBoss Core Services 产品

    OpenSSL

    在单独的 "Native 实用程序" 下载中交付产品

    提供了新的 JBoss Core Services 产品

    tcnatives

    在单独的"Native Components" 下载中交付产品

    JBoss EAP 7 中已取消了这一点

  • 您还应该了解以下更改:

    • 已取消将 mod_cluster 和 mod_jk 连接器用于来自 Red Hat Enterprise Linux RPM 频道的 Apache HTTP 服务器的支持。如果您从 Red Hat Enterprise Linux RPM 频道运行 Apache HTTP 服务器,且需要为 JBoss EAP 7 服务器配置负载均衡,您可以执行以下操作之一:

      • 使用 JBoss Core Services 提供的 Apache HTTP 服务器。
      • 您可以配置 JBoss EAP 7 以充当前端负载平衡器。如需更多信息,请参阅 JBoss EAP 配置指南中的将 JBoss EAP 配置为前端 Load Balancer
      • 您可以在支持和认证的机器上部署 Apache HTTP 服务器,然后在该机器上运行负载均衡器。有关支持的配置列表,请参阅 JBoss EAP 7 配置指南中的 HTTP Connectors 概述
  • 您可以在 Apache HTTP 服务器安装指南中找到有关 JBoss Core Services 的更多信息。

6.2. 在 Amazon EC2 上部署更改

在 JBoss EAP 7 中对 Amazon Machine Images(AMI)进行了大量更改。本节简要总结了其中一些更改。

  • 您在 Amazon EC2 中启动非集群和集群 JBoss EAP 实例和域的方式发生了重大变化。
  • JBoss EAP 6 使用 User Data: 字段用于 JBoss EAP 配置。在 User Data: 字段中解析配置的 AMI 脚本,并在实例启动时自动启动服务器已从 JBoss EAP 7 中删除。
  • Red Hat JBoss Operations Network 代理安装在以前的 JBoss EAP 版本中。在 JBoss EAP 7 中,您必须单独安装它。

有关在 Amazon EC2 上部署 JBoss EAP 7 的详情,请参考在 Amazon Web Services 上部署 JBoss EAP

6.3. 取消部署包含共享文件系统的应用

在尝试取消部署您的应用程序时,JBoss EAP 7.1 服务器和 Maven 插件的更改可能会导致以下故障:如果您的应用程序包含交互或相互依赖的模块,则可能发生此错误。

WFLYCTL0184:    New missing/unsatisfied dependencies

例如,假设您有一个包含两个 Maven WAR 项目模块 application-Aapplication-B 的应用-B 的应用,它们共享由 data-sharing 模块管理的数据。

当您部署此应用程序时,必须首先部署共享 data-sharing 模块,然后部署依赖于它的模块。部署顺序在父 pom.xml 文件的 & lt;modules> 元素中指定。在 JBoss EAP 6.4 中通过 JBoss EAP 7.4 来说是如此。

在 JBoss EAP 7.1 之前的发行版本中,您可以使用以下命令从父项目的根目录取消部署此应用的所有存档。

$ mvn wildfly:undeploy

在 JBoss EAP 7.1 和更高版本中,您必须首先取消部署使用共享模块的存档,然后取消部署共享模块。由于无法在 pom.xml 文件中指定未部署的顺序,因此您必须手动取消部署模块。您可以从父目录的根目录运行以下命令完成此操作。

$ mvn wildfly:undeploy -pl application-A,application-B
$ mvn wildfly:undeploy -pl data-shared

此新取消部署的行为更为正确,可确保您不会处于不稳定的部署状态。

6.4. JBoss EAP 脚本的更改

由于密码策略的变化,在 JBoss EAP 7 中更改了 add-user 脚本的行为。JBoss EAP 6 具有严格的密码策略。因此,add-user 脚本会拒绝没有满足最低要求的弱密码。在 JBoss EAP 7 中,接受弱密码,并发出警告。如需更多信息,请参阅 JBoss EAP 配置指南中的设置附加用户实用程序密码限制

6.5. 删除 OSGi 支持

首次发布 JBoss EAP 6.0 GA 时,JBoss OSGi 规范的实施将作为技术预览功能提供。随着 JBoss EAP 6.1.0 的发布,JBoss OSGi 已从技术预览降级为 Unsupported。

在 JBoss EAP 6.1.0 中,单机服务器的 configadminosgi 扩展模块和子系统配置已移到单独的 EAP_HOME/standalone/configuration/standalone-osgi.xml 配置文件中。因为您不应该迁移这个不支持的配置文件,所以删除 JBoss OSGi 支持不会影响独立服务器配置的迁移。如果您修改了任何其他独立配置文件来配置 osgiconfigadmin,则必须删除这些配置。

对于受管域,JBoss EAP 6.1.0 发行版中的 osgi 扩展和子系统配置已从 EAP_HOME/domain/configuration/domain.xml 文件中删除。但是,configadmin 模块扩展和子系统配置保留在 EAP_HOME/domain/configuration/domain.xml 文件中。JBoss EAP 7 中不再支持此配置,必须被删除。

6.6. Java Platform 模块系统名称的变化

使用 JPMS 架构的独立 Java 应用程序需要更新代码,因为 JBoss EAP 7.3 中的 Java 平台模块系统(JPMS)名称更改。

使用新的 JPMS 模块名称更新独立应用程序代码,以便使用 JBoss EAP 7.3 正常工作。JPMS 模块名称中的更改仅影响独立应用,因此服务器上部署的 JBoss EAP 应用程序不需要更新代码。

表 6.1. JPMS 名称更改

GroupIDJBoss EAP 7.2JBoss EAP 7.3

org.jboss.spec.javax.ws.rs:jboss-jaxrs-api_2.1_spec

beta.jboss.jaxrs.api_2_1

java.ws.rs

org.jboss.spec.javax.security.jacc:jboss-jacc-api_1.5_spec

beta.jboss.jacc.api_1_5

java.security.jacc

org.jboss.spec.javax.security.auth.message:jboss-jaspi-api_1.1_spec

beta.jboss.jaspi.api_1_1

java.security.auth.message

6.7. 使用 Java 的附件 API 中的 SOAP 的变化

在迁移到 JBoss EAP 7.3 时,更新用户定义的 SOAP 处理程序以符合 SAAJ 1.4 规格。

由于 JBoss EAP 7.3 附带了 SAAJ 1.4,因此为之前的 JBoss EAP 版本(随 SAAJ 1.3 一同提供)的 SOAP 处理程序可能会因为 SAAJ 1.4 和 1.3 规格中的不同而无法正常工作。有关 SAAJ 1.4 的详情请参考 SOAP with Attachments

在更新 SOAP 处理程序时,可以通过设置系统属性 -Djboss.saaj.api.version=1.3 在 JBoss EAP 7.3 中使用 SAAJ 1.3。在更新了 SOAP 处理程序后,删除系统属性以恢复默认功能。

6.8. Jakarta EE Maven 工件的变化

一些 javax Maven 工件已被 JBoss EAP 7.3 的 jakarta Maven 工件替代。

在为 JBoss EAP 7.3 构建项目时,您必须使用新的 jakarta Maven 工件更新项目依赖项。不更新项目依赖项会在为 JBoss EAP 7.3 构建项目时造成构建失败。有关管理项目依赖项的信息,请参阅开发指南中的管理项目依赖项

下表列出了 javax 工件和在 JBoss EAP 7.3 中替换它们的 jakarta 工件。

表 6.2. javax 工件和 jakarta 工件替换它们

javax 工件jakarta 工件

com.sun.mail:javax.mail

com.sun.mail:jakarta.mail

javax.activation:activation

com.sun.activation:jakarta.atcivation

javax.enterprise:cdi-api

jakarta.enterprise:jakarta.enterprise.cdi-api

javax.inject:javax.inject

jakarta.inject:jakarta.inject-api

javax.json:javax.json-api

jakarta.json:jakarta.json-api

javax.json.bind:javax.json.bind-api

jakarta.json.bind:jakarta.json.bind-api

javax.persistence:javax.persistence-api

jakarta.persistence:jakarta.persistence-api

javax.security.enterprise:javax.security.enterprise-api

jakarta.security.enterprise:jakarta.security.enterprise-api

javax.validation:validation-api

jakarta.validation:jakarta.validation-api

org.glassfish:javax.json

org.glassfish:jakarta.json

org.jboss.spec.javax.xml.soap:jboss-saaj-api_1.3_spec

org.jboss.spec.javax.xml.soap:jboss-saaj-api_1.4_spec

org.jboss.spec.javax.transaction:jboss-transaction-api_1.2_spec

org.jboss.spec.javax.transaction:jboss-transaction-api_1.3_spec

注意

com.sun.mail:jakarta.mail 由 Jakarta mail 1.6.4 库引入。有关 Jakarta 邮件兼容性的详情,请参考 Eclipse 维护的兼容性说明

第 7 章 迁移到 Elytron

7.1. Elytron 概述

JBoss EAP 7.1 引入了 Elytron,它提供了一个统一的框架,可以管理和配置单机服务器和托管域的访问。它还可用来为部署到 JBoss EAP 服务器的应用程序配置安全访问。

重要

Elytron 的架构和传统的安全子系统基于 PicketBox 非常不同。通过 Elytron,尝试创建一个解决方案,供您在当前运行的同一安全环境中运行。但是,这并不表示 每个 PicketBox 配置选项在 Elytron 中有等同的配置选项。

如果您无法在文档中查找信息,以帮助您使用旧安全实现时提供的类似功能,您可以通过以下方法之一查找帮助:

您的 JBoss EAP 7.0 服务器配置和使用旧的 安全 子系统(基于 PicketBox)的部署应在不更改 JBoss EAP 7.1 及之后的版本上运行。Picketbox 继续支持安全域,允许应用程序继续使用现有的登录模块。供管理层用于安全性的安全域也被 Elytron 传输和模拟。这样,您可以在 elytron 和传统的 security 子系统中定义身份验证,并并行使用它们。有关如何将应用程序配置为使用 Elytron 和 legacy 安全性的更多信息,请参阅如何在如何为 JBoss EAP 配置身份管理 验证中使用 Elytron 或 Legacy 安全

虽然 PicketBox 身份验证将继续被支持,但建议您在准备迁移应用程序时切换到 Elytron。使用 Elytron 安全性的一个优点是,它为服务器和应用程序提供了一致的安全解决方案。有关如何迁移 PicketBox 身份验证和授权以使用 Elytron 的信息,请参阅本指南中的迁移身份验证配置

有关 elytron 子系统中可用新资源的概述,请参阅 JBoss EAP 安全架构指南中的 Elytron subsystem 中的资源。

重要

请注意,如果您选择在部署中同时使用旧的 security 子系统和 Elytron,则不支持使用不同的安全架构在部署之间调用。

有关并行使用这些子系统的更多信息,请参阅 JBoss EAP 的 How to Configure Identity Management 中的 Using Elytron and Legacy Security Subsystems in Parallel

7.2. 迁移安全 Vault 和属性

7.2.1. 将 Vault 迁移到安全凭证存储

用于将纯文本字符串加密存储在 JBoss EAP 7.0 中的旧 安全 子系统中的密码库与 JBoss EAP 7.1 或更高版本中的 Elytron 不兼容,使用新设计的凭证存储来存储字符串。凭据安全地存储在 JBoss EAP 配置文件之外的存储文件中。您可以使用 Elytron 提供的实现,也可以使用凭据存储 API 和 SPI 来自定义配置。每个 JBoss EAP 服务器都可以包含多个凭据存储。

注意

如果您之前使用 vault 表达式对非敏感数据进行参数化,建议您将数据替换为 Elytron 安全属性

如果继续使用旧的 security 子系统,则应该不需要修改或更新您的 vault 数据。但是,如果您计划迁移应用程序以使用 Elytron,您必须将现有的 vaults 转换为凭证存储,以便可以通过 elytron 子系统来处理它们。有关凭证存储的更多信息,请参阅如何配置 JBoss EAP 服务器安全性中的凭据存储

使用 WildFly Elytron 工具迁移 Vault 数据

JBoss EAP 附带的 WildFly Elytron 工具提供了 vault 命令,可帮助您将 vault 内容迁移到凭据存储中。您可以通过运行 elytron-tool 脚本(位于 EAP_HOME/bin 目录中)来执行该工具。

$ EAP_HOME/bin/elytron-tool.sh vault VAULT_ARGUMENTS

如果您愿意,可以通过运行 java -jar 命令来执行该工具。

$ java -jar EAP_HOME/bin/wildfly-elytron-tool.jar vault VAULT_ARGUMENTS

您可以使用以下命令获取所有可用参数的描述。

$ EAP_HOME/bin/elytron-tool.sh vault --help
注意
  • WildFly Elytron 工具无法处理安全 vault 数据文件的第一个版本。
  • 您可以使用屏蔽的格式输入 --keystore-password 参数,如下例所示,以迁移单个 vault 或使用明文。
  • 提供的 --salt--iteration 参数用于提供解密已屏蔽密码的信息,或在输出中生成屏蔽的密码。如果省略 --salt--iteration 参数,则使用默认值。
  • --summary 参数生成格式化的管理 CLI 命令,该命令可用于将转换的凭据存储添加到 JBoss EAP 配置中。纯文本密码在概述输出中屏蔽。
重要

请注意,凭证存储只能用于保护密码。它们不支持管理模型中任何位置可以使用的 vault 表达式功能。

选择以下迁移选项之一:

将单一安全 Vault 迁移到凭证存储

以下是 命令的一个示例,用于将单一安全密码库转换为凭据存储。

$ EAP_HOME/bin/elytron-tool.sh vault --enc-dir vault_data/ --keystore vault-jceks.keystore --keystore-password MASK-2hKo56F1a3jYGnJwhPmiF5 --iteration 34 --salt 12345678 --alias test --location cs-v1.store --summary

此命令将安全密码库转换为凭据存储,并打印用于在输出中进行转换的管理 CLI 命令摘要。

Vault (enc-dir="vault_data/";keystore="vault-jceks.keystore") converted to credential store "cs-v1.store"
Vault Conversion summary:
--------------------------------------
Vault Conversion Successful
CLI command to add new credential store:
/subsystem=elytron/credential-store=test:add(relative-to=jboss.server.data.dir,create=true,modifiable=true,location="cs-v1.store",implementation-properties={"keyStoreType"=>"JCEKS"},credential-reference={clear-text="MASK-2hKo56F1a3jYGnJwhPmiF5;12345678;34"})
将多个安全 Vault 迁移至 Bulk 中的凭证存储

您可以使用 --bulk-convert 参数将多个 vault 转换为凭证存储,并指向批量转换描述符文件。

本节中的示例使用以下批量转换描述符文件。

示例: bulk-vault-conversion-descriptor.txt 文件

keystore:vault-v1/vault-jceks.keystore
keystore-password:MASK-2hKo56F1a3jYGnJwhPmiF5
enc-dir:vault-v1/vault_data/
salt:12345678
iteration:34
location:v1-cs-1.store
alias:test

keystore:vault-v1/vault-jceks.keystore
keystore-password:secretsecret
enc-dir:vault-v1/vault_data/
location:v1-cs-2.store
alias:test

# different vault vault-v1-more
keystore:vault-v1-more/vault-jceks.keystore
keystore-password:MASK-2hKo56F1a3jYGnJwhPmiF5
enc-dir:vault-v1-more/vault_data/
salt:12345678
iteration:34
location:v1-cs-more.store
alias:test

当遇到每个新 密钥存储: 行时,将开始新的转换。除 salt, iteration, 和 properties 外,所有选项均是必需的。

要执行批量转换并生成格式管理 CLI 命令的输出结果,请执行以下命令:

$ EAP_HOME/bin/elytron-tool.sh vault --bulk-convert path/to/bulk-vault-conversion-descriptor.txt --summary

此命令将文件中指定的所有安全库转换为凭据存储,并打印用于在输出中转换它们的管理 CLI 命令摘要。

Vault (enc-dir="vault-v1/vault_data/";keystore="vault-v1/vault-jceks.keystore") converted to credential store "v1-cs-1.store"
Vault Conversion summary:
--------------------------------------
Vault Conversion Successful
CLI command to add new credential store:
/subsystem=elytron/credential-store=test:add(relative-to=jboss.server.data.dir,create=true,modifiable=true,location="v1-cs-1.store",implementation-properties={"keyStoreType"=>"JCEKS"},credential-reference={clear-text="MASK-2hKo56F1a3jYGnJwhPmiF5;12345678;34"})
--------------------------------------

Vault (enc-dir="vault-v1/vault_data/";keystore="vault-v1/vault-jceks.keystore") converted to credential store "v1-cs-2.store"
Vault Conversion summary:
--------------------------------------
Vault Conversion Successful
CLI command to add new credential store:
/subsystem=elytron/credential-store=test:add(relative-to=jboss.server.data.dir,create=true,modifiable=true,location="v1-cs-2.store",implementation-properties={"keyStoreType"=>"JCEKS"},credential-reference={clear-text="secretsecret"})
--------------------------------------

Vault (enc-dir="vault-v1-more/vault_data/";keystore="vault-v1-more/vault-jceks.keystore") converted to credential store "v1-cs-more.store"
Vault Conversion summary:
--------------------------------------
Vault Conversion Successful
CLI command to add new credential store:
/subsystem=elytron/credential-store=test:add(relative-to=jboss.server.data.dir,create=true,modifiable=true,location="v1-cs-more.store",implementation-properties={"keyStoreType"=>"JCEKS"},credential-reference={clear-text="MASK-2hKo56F1a3jYGnJwhPmiF5;12345678;34"})
--------------------------------------

7.2.2. 将安全属性迁移到 Elytron

本节中的示例假定 group.nameencoding.algorithm 安全属性定义为旧 security-properties 中的 security -properties,如下所示。

示例:在 security 子系统中定义的安全属性

<subsystem xmlns="urn:jboss:domain:security:2.0">
    ...
    <security-properties>
        <property name="group.name" value="engineering-group" />
        <property name="encoding.algorithm" value="BASE64" />
    </security-properties>
</subsystem>

要在 elytron 子系统中定义相同的安全属性,可使用以下管理 CLI 命令设置 elytron 子系统的 security-properties 属性。

/subsystem=elytron:write-attribute(name=security-properties, value={ group.name = "engineering-group", encoding.algorithm = "BASE64" })

这会在服务器配置文件中的 elytron 子系统中配置以下 security-properties

<subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
    <security-properties>
        <security-property name="group.name" value="engineering-group"/>
        <security-property name="encoding.algorithm" value="BASE64"/>
    </security-properties>
    ...
</subsystem>

上一命令中使用的 write-attribute 操作会覆盖现有属性。要在不影响其他安全属性的情况下添加或更改安全属性,请在管理 CLI 命令中使用 map 操作。

/subsystem=elytron:map-put(name=security-properties, key=group.name, value=technical-support)

同样,您可以使用 map-remove 操作删除特定的安全属性。

/subsystem=elytron:map-remove(name=security-properties, key=group.name)

7.3. 迁移身份验证配置

7.3.1. 将基于属性的身份验证和授权迁移到 Elytron

7.3.1.1. 将基于 PicketBox Properties 的配置迁移到 Elytron

这部分论述了如何将基于 PicketBox 属性的身份验证迁移到 Elytron。您可以选择 部分迁移 基于属性的身份验证,方法是仅将 PicketBox 安全域公开给 Elytron,或者您可以 完全迁移 基于属性的验证配置来使用 Elytron。

以下流程假定您要实施的 Web 应用程序被配置为需要基于表单的身份验证。应用程序正在引用 PicketBox 安全域,并使用 UsersRolesLoginModuleexample-users.propertiesexample-roles.properties 文件中加载用户信息。这些示例也假定使用下列管理 CLI 命令,在传统的 security 子系统中定义安全域:

示例:基于 PicketBox 属性的配置命令

/subsystem=security/security-domain=application-security:add
/subsystem=security/security-domain=application-security/authentication=classic:add(login-modules=[{code=UsersRoles, flag=Required, module-options={usersProperties=file://${jboss.server.config.dir}/example-users.properties, rolesProperties=file://${jboss.server.config.dir}/example-roles.properties}}])

这会生成以下服务器配置。

示例:基于 PicketBox Properties 的安全域配置

<security-domain name="application-security">
  <authentication>
    <login-module code="UsersRoles" flag="required">
      <module-option name="usersProperties" value="file://${jboss.server.config.dir}/example-users.properties"/>
      <module-option name="rolesProperties" value="file://${jboss.server.config.dir}/example-roles.properties"/>
    </login-module>
  </authentication>
</security-domain>

选择以下迁移选项之一:

通过公开 PicketBox Security Domain to Elytron 的部分迁移

您可以将 PicketBox 安全域公开为 Elytron 安全域,以便它可以进入 Elytron 配置中;但是,这样做会为旧 安全 子系统创建依赖项。如果您只迁移基于属性的身份验证,建议您 完全将应用程序迁移到 Elytron,以避免对安全 子系统的不必要的依赖。但是,当无法完全迁移应用程序以使用 Elytron 时,部分迁移可以是中间解决方案。

按照以下步骤,将现有的 PicketBox 安全域配置添加为 Elytron 安全域。

  1. 添加到旧安全子系统中 Elytron 安全域 的映射。

    /subsystem=security/elytron-realm=application-security:add(legacy-jaas-config=application-security)

    这会在服务器配置文件的 security 子系统中配置以下 Elytron 安全域 :

    <subsystem xmlns="urn:jboss:domain:security:2.0">
      ...
      <elytron-integration>
        <security-realms>
          <elytron-realm name="application-security" legacy-jaas-config="application-security"/>
        </security-realms>
      </elytron-integration>
      ...
    </subsystem>
  2. elytron 子系统中定义引用导出的安全域的安全域。

    /subsystem=elytron/security-domain=application-security:add(realms=[{realm=application-security}], default-realm=application-security, permission-mapper=default-permission-mapper)

    这会在服务器配置文件中生成以下 elytron 子系统配置。

    <subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
      ...
      <security-domains>
        ...
        <security-domain name="application-security" default-realm="application-security" permission-mapper="default-permission-mapper">
          <realm name="application-security"/>
        </security-domain>
      </security-domains>
      ...
    </subsystem>
  3. undertow 子系统中,将部署引用的应用安全域映射到新定义的安全域。

    /subsystem=undertow/application-security-domain=application-security:add(security-domain=application-security)

    这会在服务器配置文件中生成以下 undertow 子系统配置。

    <subsystem xmlns="urn:wildfly:elytron:4.0">
      ...
      <application-security-domains>
        <application-security-domain name="application-security" security-domain="application-security"/>
      </application-security-domains>
      ...
    </subsystem>
    注意
    • 如果应用程序已在此配置之前部署,您必须重新加载服务器或重新部署应用,以使新应用安全域映射生效。
    • 在当前的 Web 服务中,为保护 Web 服务端点和 Elytron 安全域名指定的安全域的名称必须相同。
  4. 使用以下管理 CLI 命令,验证映射是否已应用到部署。本例中使用的部署是 HelloWorld.war。此命令的输出显示此部署正在引用 Elytron 映射。

    /subsystem=undertow/application-security-domain=application-security:read-resource(include-runtime=true)
    
    {
    "outcome" => "success",
        "result" => {
            "enable-jacc" => false,
            "http-authentication-factory" => undefined,
            "override-deployment-config" => false,
            "referencing-deployments" => ["HelloWorld.war"],
            "security-domain" => "application-security",
            "setting" => undefined
        }
    }

在这个阶段,之前定义的安全域用于其 LoginModule 配置,但被 Elytron 组件包装(通过身份验证)。

完全将基于属性的身份验证迁移到 Elytron

按照以下步骤,将基于 PicketBox 的属性身份验证完全迁移到 Elytron。此流程假设您从本节介绍中所述的传统配置开始,但没有迁移到部分迁移的解决方案。完成此过程后,传统 security 子系统中存在的任何安全域定义都会完全独立于 Elytron 配置。

  1. elytron 子系统定义一个新的安全域,它将引用 PicketBox 属性文件。

    /subsystem=elytron/properties-realm=application-properties:add(users-properties={path=example-users.properties, relative-to=jboss.server.config.dir, plain-text=true, digest-realm-name="Application Security"}, groups-properties={path=example-roles.properties, relative-to=jboss.server.config.dir}, groups-attribute=Roles)
  2. elytron 子系统中定义安全域子系统。

    /subsystem=elytron/security-domain=application-security:add(realms=[{realm=application-properties}], default-realm=application-properties, permission-mapper=default-permission-mapper)

    这会在服务器配置文件中生成以下 elytron 子系统配置。

    <subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
      ...
      <security-domains>
        ...
        <security-domain name="application-security" default-realm="application-properties" permission-mapper="default-permission-mapper">
          <realm name="application-properties"/>
        </security-domain>
      </security-domains>
      <security-realms>
        ...
        <properties-realm name="application-properties" groups-attribute="Roles">
          <users-properties path="example-users.properties" relative-to="jboss.server.config.dir" digest-realm-name="Application Security" plain-text="true"/>
          <groups-properties path="example-roles.properties" relative-to="jboss.server.config.dir"/>
        </properties-realm>
      </security-realms>
      ...
    </subsystem>
  3. 将部署引用的应用安全域映射到 undertow 子系统中新定义的 HTTP 身份验证工厂。

    /subsystem=undertow/application-security-domain=application-security:add(security-domain=application-security)

    这会在服务器配置文件中生成以下 undertow 子系统配置。

    <subsystem xmlns="urn:jboss:domain:undertow:10.0">
      ...
      <application-security-domains>
        <application-security-domain name="application-security" security-domain="application-security"/>
      </application-security-domains>
      ...
    </subsystem>
    注意

    在当前的 Web 服务中,为保护 Web 服务端点和 Elytron 安全域名指定的安全域的名称必须相同。

  4. 您必须重新加载服务器或重新部署应用,以使新的应用安全域映射生效。

身份验证现在被配置为等同于 PicketBox 配置,但 Elytron 组件现在专门用于身份验证。

7.3.1.2. 将基于传统属性的配置迁移到 Elytron

这部分论述了如何将加载用户、密码和组信息的传统安全域从属性文件迁移到 Elytron。这种类型的传统安全域通常用于保护管理接口或重新移动连接器。

这些示例假定使用下列管理 CLI 命令定义传统安全域:

示例:传统安全性 Realm 命令

/core-service=management/security-realm=ApplicationSecurity:add
/core-service=management/security-realm=ApplicationSecurity/authentication=properties:add(relative-to=jboss.server.config.dir, path=example-users.properties, plain-text=true)
/core-service=management/security-realm=ApplicationSecurity/authorization=properties:add(relative-to=jboss.server.config.dir, path=example-roles.properties)

这会生成以下服务器配置。

示例:传统安全域配置

<security-realm name="ApplicationSecurity">
  <authentication>
    <properties path="example-users.properties" relative-to="jboss.server.config.dir" plain-text="true"/>
  </authentication>
  <authorization>
    <properties path="example-roles.properties" relative-to="jboss.server.config.dir"/>
  </authorization>
</security-realm>

在应用程序服务器中添加 Elytron 安全性的动机之一是允许在服务器中使用一致的安全解决方案。将基于属性的传统安全域迁移到 Elytron 的初始步骤与用于将 PicketBox 属性验证迁移到 Elytron 的验证类似。按照以下步骤将基于属性的传统安全域迁移到 Elytron。

  1. elytron 子系统定义引用属性文件的新安全域。

    /subsystem=elytron/properties-realm=application-properties:add(users-properties={path=example-users.properties, relative-to=jboss.server.config.dir, plain-text=true, digest-realm-name="Application Security"}, groups-properties={path=example-roles.properties, relative-to=jboss.server.config.dir}, groups-attribute=Roles)
  2. elytron 子系统中定义安全域子系统。

    /subsystem=elytron/security-domain=application-security:add(realms=[{realm=application-properties}], default-realm=application-properties, permission-mapper=default-permission-mapper)

    这会生成以下 Elytron 配置。

    <subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
      ...
      <security-domains>
        ...
        <security-domain name="application-security" default-realm="application-properties" permission-mapper="default-permission-mapper">
          <realm name="application-properties"/>
        </security-domain>
      </security-domains>
      <security-realms>
        ...
        <properties-realm name="application-properties" groups-attribute="Roles">
          <users-properties path="example-users.properties" relative-to="jboss.server.config.dir" digest-realm-name="Application Security" plain-text="true"/>
          <groups-properties path="example-roles.properties" relative-to="jboss.server.config.dir"/>
        </properties-realm>
      </security-realms>
        ...
    </subsystem>
  3. 定义 sasl-authentication-factory,以便传统安全域也可以用于简单身份验证安全层(SASL)身份验证。

    /subsystem=elytron/sasl-authentication-factory=application-security-sasl:add(sasl-server-factory=elytron, security-domain=application-security, mechanism-configurations=[{mechanism-name=PLAIN}])

    这会生成以下 Elytron 配置。

    <subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
      ...
      <sasl>
        ...
        <sasl-authentication-factory name="application-security-sasl" sasl-server-factory="elytron" security-domain="application-security">
          <mechanism-configuration>
            <mechanism mechanism-name="PLAIN"/>
          </mechanism-configuration>
        </sasl-authentication-factory>
        ...
      </sasl>
    </subsystem>
  4. 为 SASL 身份验证配置 remoting connector,并删除与传统安全域的关联。

    /subsystem=remoting/http-connector=http-remoting-connector:write-attribute(name=sasl-authentication-factory, value=application-security-sasl)
    /subsystem=remoting/http-connector=http-remoting-connector:undefine-attribute(name=security-realm)

    这会在服务器配置文件的 remoting subsystem 中生成以下配置:

    <subsystem xmlns="urn:jboss:domain:remoting:4.0">
      ...
      <http-connector name="http-remoting-connector" connector-ref="default" sasl-authentication-factory="application-security-sasl"/>
    </subsystem>
  5. 添加两个身份验证工厂并删除旧安全域,以使用 Elytron 保护 http-interface

    /core-service=management/management-interface=http-interface:write-attribute(name=http-authentication-factory, value=application-security-http)
    /core-service=management/management-interface=http-interface:write-attribute(name=http-upgrade.sasl-authentication-factory, value=application-security-sasl)
    /core-service=management/management-interface=http-interface:undefine-attribute(name=security-realm)

    这会生成以下配置。

    <management-interfaces>
      <http-interface http-authentication-factory="application-security-http">
        <http-upgrade enabled="true" sasl-authentication-factory="application-security-sasl"/>
        <socket-binding http="management-http"/>
      </http-interface>
    </management-interfaces>
    注意

    在保护管理界面时,您应该选择比这些示例中使用的更合适的名称。

现在完成将基于旧属性的配置迁移到 Elytron。

7.3.2. 使用 filesystem-realm 命令迁移到基于文件系统的安全 Realm

这部分论述了如何使用 elytron.sh 工具的 filesystem-realm 命令,将传统的基于属性的安全域迁移到 Elytronon 中的基于文件系统的域。

基于文件系统的域是一种基于文件系统的身份存储,供 Elytron 用于存储用户身份。filesystem-realm 命令将 properties-realm 文件转换为 filesystem-realm。它还生成将这个域和安全域添加到 elytron 子系统的命令。

将基于属性的身份验证迁移到基于文件系统的身份验证的步骤如下:

  1. 迁移属性文件。

    您可以一次迁移单个 user-properties 文件,或者批量迁移属性文件。以下示例演示了这两种迁移的步骤。

    • 迁移单个属性文件。

      以下示例将关联 roles-properties 文件的单个用户/操作文件转换为 filesystem-realm。示例假定旧安全域具有以下 user-properties 和 role-properties 文件:

      example-users.properties
      example-roles.properties

      示例:单个 user-property 文件迁移

      $./bin/elytron-tool.sh filesystem-realm --users-file example-users.properties --roles-file example-roles.properties --output-location realms/example

      这将创建 filesystem-realm 文件以及包含管理 CLI 命令的脚本。该脚本存储在 realms/example 目录中。

    • 迁移多个属性文件。

      以下示例将含有关联 roles-properties 文件的用户/操作文件转换为 filesystem-realm。示例假定旧的安全域具有以下属性文件:

      users-1.properties
      users-2.properties
      roles-1.properties
      roles-2.properties

      要批量转换用户角色文件,必须创建一个描述符文件,以便与 filesystem-realm 命令搭配使用。在本例中,使用以下内容创建 /bin 目录中的描述符文件 example-descriptor-file

      示例:描述符文件

      users-file:/full/path/to/users-1.properties
      roles-file:/full/path/to/roles-1.properties
      output-location:./realms/bulk-1-example
      filesystem-realm-name:exampleFileSystemRealm1
      security-domain-name:exampleSecurityDomain1
      
      users-file:/full/path/to/users-2.properties
      roles-file:/full/path/to/roles-2.properties
      output-location:./realms/bulk-2-example
      filesystem-realm-name:exampleFileSystemRealm2
      security-domain-name:exampleSecurityDomain2

      描述符文件中的一个空行用于分隔各个用户/不可操作的文件的操作。

      以下示例将两个用户/操作文件与关联的 role-properties 文件转换为 filesystem-realm

      示例:Bulk migration

      $./bin/elytron-tool.sh filesystem-realm --bulk-convert example-descriptor-file

      这将创建 filesystem-realm 文件和包含管理 CLI 命令的脚本。脚本存储在描述符文件 output-location 属性中指定的目录中。

  2. 将文件系统安全域添加到 Elytron。

    迁移文件后,使用 Elytron 工具生成的 CLI 命令添加新的安全域和安全域到 elytron 子系统。

    示例:添加 filesystem-realm

    /subsystem=elytron/filesystem-realm=converted-properties-filesystem-realm:add(path=/full/path/to/realms/example)
    
    /subsystem=elytron/security-domain=converted-properties-security-domain:add(realms=[{realm=converted-properties-filesystem-realm}],default-realm=converted-properties-filesystem-realm,permission-mapper=default-permission-mapper)

7.3.3. 将 LDAP 身份验证配置迁移到 Elytron

这部分论述了如何将旧的 LDAP 身份验证迁移到 Elytron,以便它可以将信息作为身份属性进行管理。在这里应用了授权 迁移基于属性的验证和授权至 Elytron 的部分提供的大部分信息,特别是如何定义安全域和身份验证因素以及如何映射以进行身份验证。本节没有重复这些指令,因此务必在继续操作前通读该部分。

以下示例假定组或角色信息直接从 LDAP 加载,并且旧 LDAP 身份验证配置如下。

  • LDAP 服务器包含以下用户和组条目:

    示例:LDAP 服务器用户条目

    dn: uid=TestUserOne,ou=users,dc=group-to-principal,dc=wildfly,dc=org
    objectClass: top
    objectClass: inetOrgPerson
    objectClass: uidObject
    objectClass: person
    objectClass: organizationalPerson
    cn: Test User One
    sn: Test User One
    uid: TestUserOne
    userPassword: {SSHA}UG8ov2rnrnBKakcARVvraZHqTa7mFWJZlWt2HA==

    示例:LDAP 服务器组条目

    dn: uid=GroupOne,ou=groups,dc=group-to-principal,dc=wildfly,dc=org
    objectClass: top
    objectClass: groupOfUniqueNames
    objectClass: uidObject
    cn: Group One
    uid: GroupOne
    uniqueMember: uid=TestUserOne,ou=users,dc=group-to-principal,dc=wildfly,dc=org

    为了进行身份验证,用户名与 uid 属性匹配,生成的组名则取自组条目的 uid 属性。

  • 与 LDAP 服务器和相关安全域的连接使用下列管理 CLI 命令进行定义。

    示例:LDAP 安全域配置命令

    batch
    /core-service=management/ldap-connection=MyLdapConnection:add(url="ldap://localhost:10389", search-dn="uid=admin,ou=system", search-credential="secret")
    
    /core-service=management/security-realm=LDAPRealm:add
    /core-service=management/security-realm=LDAPRealm/authentication=ldap:add(connection="MyLdapConnection", username-attribute=uid, base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org")
    
    /core-service=management/security-realm=LDAPRealm/authorization=ldap:add(connection=MyLdapConnection)
    /core-service=management/security-realm=LDAPRealm/authorization=ldap/username-to-dn=username-filter:add(attribute=uid, base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org")
    /core-service=management/security-realm=LDAPRealm/authorization=ldap/group-search=group-to-principal:add(base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org", iterative=true, prefer-original-connection=true, principal-attribute=uniqueMember, search-by=DISTINGUISHED_NAME, group-name=SIMPLE, group-name-attribute=uid)
    run-batch

    这会生成以下服务器配置。

    示例:LDAP 安全域配置

    <management>
      <security-realms>
        ...
        <security-realm name="LDAPRealm">
          <authentication>
            <ldap connection="MyLdapConnection" base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org">
              <username-filter attribute="uid"/>
            </ldap>
          </authentication>
          <authorization>
            <ldap connection="MyLdapConnection">
              <username-to-dn>
                <username-filter base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org" attribute="uid"/>
              </username-to-dn>
              <group-search group-name="SIMPLE" iterative="true" group-name-attribute="uid">
                <group-to-principal search-by="DISTINGUISHED_NAME" base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org" prefer-original-connection="true">
                  <membership-filter principal-attribute="uniqueMember"/>
                </group-to-principal>
              </group-search>
            </ldap>
          </authorization>
        </security-realm>
      </security-realms>
      <outbound-connections>
        <ldap name="MyLdapConnection" url="ldap://localhost:10389" search-dn="uid=admin,ou=system" search-credential="secret"/>
      </outbound-connections>
      ...
    </management>

  • 以下管理 CLI 命令用于配置 PicketBox 安全域,它使用 LdapExtLoginModule 来验证用户名和密码。

    示例:安全域配置命令

    /subsystem=security/security-domain=application-security:add
    /subsystem=security/security-domain=application-security/authentication=classic:add(login-modules=[{code=LdapExtended, flag=Required, module-options={ java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory, java.naming.provider.url=ldap://localhost:10389, java.naming.security.authentication=simple, bindDN="uid=admin,ou=system", bindCredential=secret, baseCtxDN="ou=users,dc=group-to-principal,dc=wildfly,dc=org", baseFilter="(uid={0})", rolesCtxDN="ou=groups,dc=group-to-principal,dc=wildfly,dc=org", roleFilter="(uniqueMember={1})", roleAttributeID="uid" }}])

    这会生成以下服务器配置。

    示例:安全域配置

    <subsystem xmlns="urn:jboss:domain:security:2.0">
      ...
      <security-domains>
        ...
        <security-domain name="application-security">
          <authentication>
            <login-module code="LdapExtended" flag="required">
              <module-option name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory"/>
              <module-option name="java.naming.provider.url" value="ldap://localhost:10389"/>
              <module-option name="java.naming.security.authentication" value="simple"/>
              <module-option name="bindDN" value="uid=admin,ou=system"/>
              <module-option name="bindCredential" value="secret"/>
              <module-option name="baseCtxDN" value="ou=users,dc=group-to-principal,dc=wildfly,dc=org"/>
              <module-option name="baseFilter" value="(uid={0})"/>
              <module-option name="rolesCtxDN" value="ou=groups,dc=group-to-principal,dc=wildfly,dc=org"/>
              <module-option name="roleFilter" value="(uniqueMember={1})"/>
              <module-option name="roleAttributeID" value="uid"/>
            </login-module>
          </authentication>
        </security-domain>
      </security-domains>
    </subsystem>

7.3.3.1. 将传统 LDAP 身份验证迁移到 Elytron

按照以下步骤将之前的 LDAP 身份验证示例配置迁移到 Elytron。本节适用于迁移 旧安全 LDAP 域以及 PicketBox LDAP 安全域

  1. elytron 子系统中定义与 LDAP 的连接。

    /subsystem=elytron/dir-context=ldap-connection:add(url=ldap://localhost:10389, principal="uid=admin, ou=system", credential-reference={clear-text=secret})
  2. 创建安全域以搜索 LDAP 并验证提供的密码。

    /subsystem=elytron/ldap-realm=ldap-realm:add(dir-context=ldap-connection, direct-verification=true, identity-mapping={search-base-dn="ou=users, dc=group-to-principal, dc=wildfly, dc=org", rdn-identifier="uid", attribute-mapping=[{filter-base-dn="ou=groups, dc=group-to-principal, dc=wildfly, dc=org", filter="(uniqueMember={1})", from="uid", to="Roles"}]})

这些步骤会在服务器配置文件中生成以下 elytron 子系统配置。

<subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
  ...
  <security-realms>
    ...
    <ldap-realm name="ldap-realm" dir-context="ldap-connection" direct-verification="true">
      <identity-mapping rdn-identifier="uid" search-base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org">
        <attribute-mapping>
          <attribute from="uid" to="Roles" filter="(uniqueMember={1})" filter-base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org"/>
        </attribute-mapping>
      </identity-mapping>
    </ldap-realm>
  </security-realms>
  ...
  <dir-contexts>
    <dir-context name="ldap-connection" url="ldap://localhost:10389" principal="uid=admin,ou=system">
      <credential-reference clear-text="secret"/>
    </dir-context>
  </dir-contexts>
</subsystem>
注意

默认情况下,如果没有为给定 security-domain 定义 role-decoder,则 "Roles" identity 属性映射到 identity 角色。

从 LDAP 加载的信息现在可以与身份关联。这些属性可以映射到角色,但也可以加载和用于其他目的。新创建的安全域可以在安全域中使用,其方式与本指南的 Migrate Properties-based Authentication and Authorization to Elytron 部分相同。

7.3.4. 将数据库身份验证配置迁移到 Elytron

这部分论述了如何将基于 JDBC 数据源的 PicketBox 身份验证迁移到 Elytron。在这里应用了授权 迁移基于属性的验证和授权至 Elytron 的部分提供的大部分信息,特别是如何定义安全域和身份验证因素以及如何映射以进行身份验证。本节没有重复这些指令,因此务必在继续操作前通读该部分。

以下示例假定用户身份验证数据存储在使用类似以下示例的语法创建的数据库表中。

示例:创建数据库用户表的语法

CREATE TABLE User (
    id BIGINT NOT NULL,
    username VARCHAR(255),
    password VARCHAR(255),
    role ENUM('admin', 'manager', 'user'),
    PRIMARY KEY (id),
    UNIQUE (username)
)

出于身份验证目的,用户名与用户名列中存储的数据匹配,密码应以十六进制编码的 MD5 哈希存储在 password 列中,以及用于授权目的的用户角色存储在 role 列中。

PicketBox 安全域已配置为使用 JBDC 数据源从数据库表中检索数据,然后使用它来验证用户名和密码,再分配角色。假定 PicketBox 安全域使用以下管理 CLI 命令进行配置。

示例:PicketBox Database LoginModule Configuration Commands

/subsystem=security/security-domain=application-security:add
/subsystem=security/security-domain=application-security/authentication=classic:add( login-modules=[ { code=Database, flag=Required, module-options={ dsJndiName="java:jboss/datasources/ExampleDS", principalsQuery="SELECT password FROM User WHERE username = ?", rolesQuery="SELECT role, 'Roles' FROM User WHERE username = ?", hashAlgorithm=MD5, hashEncoding=base64 } } ] )

这会在旧的 security 子系统中生成以下 登录模块 配置。

示例:PicketBox LoginModule Configuration

<subsystem xmlns="urn:jboss:domain:security:2.0">
  <security-domains>
    ...
    <security-domain name="application-security">
      <authentication>
        <login-module code="Database" flag="required">
          <module-option name="dsJndiName" value="java:jboss/datasources/ExampleDS"/>
          <module-option name="principalsQuery" value="SELECT password FROM User WHERE username = ?"/>
          <module-option name="rolesQuery" value="SELECT role, 'Roles' FROM User WHERE username = ?"/>
          <module-option name="hashAlgorithm" value="MD5"/>
          <module-option name="hashEncoding" value="base64"/>
        </login-module>
      </authentication>
    </security-domain>
  </security-domains>
</subsystem>

7.3.4.1. 将传统数据库身份验证迁移到 Elytron

要将前面的数据库身份验证示例配置迁移到 Elytron,您必须定义一个 JDBC 域才能启用 Elytron 的 JDBC 数据源访问。

使用以下管理命令定义 jdbc-realm

/subsystem=elytron/jdbc-realm=jdbc-realm:add(principal-query=[ { data-source=ExampleDS, sql="SELECT role, password FROM User WHERE username = ?", attribute-mapping=[{index=1, to=Roles } ] simple-digest-mapper={algorithm=simple-digest-md5, password-index=2} } ] )

这会在服务器配置文件的 elytron 子系统中生成以下 jdbc-realm 配置:

<subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
  ...
  <security-realms>
    ...
    <jdbc-realm name="jdbc-realm">
      <principal-query sql="SELECT role, password FROM User WHERE username = ?" data-source="ExampleDS">
        <attribute-mapping>
          <attribute to="Roles" index="1"/>
        </attribute-mapping>
        <simple-digest-mapper password-index="2"/>
      </principal-query>
    </jdbc-realm>
    ...
  </security-realms>
  ...
</subsystem>

Elytron 现在使用 JDBC 域配置来管理数据库身份验证。Elytron 比 PicketBox 更高效,因为它使用一个 SQL 查询来获取所有用户属性和凭证,然后从 SQL 结果中提取数据并创建用于身份验证的属性映射。

7.3.5. 将 Kerberos 身份验证迁移到 Elytron

在使用 Kerberos 配置时,JBoss EAP 服务器可以依赖环境中的配置信息,或者使用系统属性指定密钥配置。本节讨论如何迁移 Kerberos HTTPKerberos SASL 身份验证。

以下示例假设使用以下系统属性配置 Kerberos。这些系统属性适用于旧的配置和迁移的 Elytron 配置。

示例:Kerberos 系统属性管理 CLI 命令

# Enable debugging
/system-property=sun.security.krb5.debug:add(value=true)
# Identify the Kerberos realm to use
/system-property=java.security.krb5.realm:add(value=ELYTRON.ORG)
# Identify the address of the KDC
/system-property=java.security.krb5.kdc:add(value=kdc.elytron.org)

示例:Kerberos 系统属性服务器配置

<system-properties>
  <property name="sun.security.krb5.debug" value="true"/>
  <property name="java.security.krb5.realm" value="ELYTRON.ORG"/>
  <property name="java.security.krb5.kdc" value="kdc.elytron.org"/>
</system-properties>

选择以下迁移选项之一:

迁移 Kerberos HTTP 身份验证

在传统的安全配置中,您可以定义安全域来为 HTTP 管理界面启用 SPNEGO 身份验证,如下所示:

示例:为 HTTP 管理界面启用 SPNEGO 身份验证

/core-service=management/security-realm=Kerberos:add
/core-service=management/security-realm=Kerberos/server-identity=kerberos:add
/core-service=management/security-realm=Kerberos/server-identity=kerberos/keytab=HTTP\/test-server.elytron.org@ELYTRON.ORG:add(path=/path/to/test-server.keytab, debug=true)
/core-service=management/security-realm=Kerberos/authentication=kerberos:add(remove-realm=true)

示例:Kerberos 安全域配置

<security-realms>
  ...
  <security-realm name="Kerberos">
    <server-identities>
      <kerberos>
        <keytab principal="HTTP/test-server.elytron.org@ELYTRON.ORG" path="/path/to/test-server.keytab" debug="true"/>
      </kerberos>
    </server-identities>
    <authentication>
      <kerberos remove-realm="true"/>
    </authentication>
  </security-realm>
</security-realms>

您还可以定义一对旧的安全域,以允许应用程序使用 Kerberos HTTP 身份验证。

示例:定义多个安全域

# Define the first security domain
/subsystem=security/security-domain=host:add
/subsystem=security/security-domain=host/authentication=classic:add
/subsystem=security/security-domain=host/authentication=classic/login-module=1:add(code=Kerberos, flag=Required, module-options={storeKey=true, useKeyTab=true, principal=HTTP/test-server.elytron.org@ELYTRON.ORG, keyTab=path/to/test-server.keytab, debug=true}

# Define the second SPNEGO security domain
/subsystem=security/security-domain=SPNEGO:add
/subsystem=security/security-domain=SPNEGO/authentication=classic:add
/subsystem=security/security-domain=SPNEGO/authentication=classic/login-module=1:add(code=SPNEGO, flag=requisite,  module-options={password-stacking=useFirstPass, serverSecurityDomain=host})
/subsystem=security/security-domain=SPNEGO/authentication=classic/login-module=1:write-attribute(name=module, value=org.jboss.security.negotiation)
/subsystem=security/security-domain=SPNEGO/authentication=classic/login-module=2:add(code=UsersRoles, flag=required, module-options={password-stacking=useFirstPass, usersProperties=  /path/to/kerberos/spnego-users.properties, rolesProperties=  /path/to/kerberos/spnego-roles.properties, defaultUsersProperties=  /path/to/kerberos/spnego-users.properties, defaultRolesProperties=  /path/to/kerberos/spnego-roles.properties})

示例:使用对安全域进行配置

<subsystem xmlns="urn:jboss:domain:security:2.0">
  <security-domains>
    ...
    <security-domain name="host">
      <authentication>
        <login-module name="1" code="Kerberos" flag="required">
          <module-option name="storeKey" value="true"/>
          <module-option name="useKeyTab" value="true"/>
          <module-option name="principal" value="HTTP/test-server.elytron.org@ELYTRON.ORG"/>
          <module-option name="keyTab" value="/path/to/test-server.keytab"/>
          <module-option name="debug" value="true"/>
        </login-module>
      </authentication>
    </security-domain>
    <security-domain name="SPNEGO">
      <authentication>
        <login-module name="1" code="SPNEGO" flag="requisite" module="org.jboss.security.negotiation">
          <module-option name="password-stacking" value="useFirstPass"/>
          <module-option name="serverSecurityDomain" value="host"/>
        </login-module>
        <login-module name="2" code="UsersRoles" flag="required">
          <module-option name="password-stacking" value="useFirstPass"/>
          <module-option name="usersProperties" value="path/to/kerberos/spnego-users.properties"/>
          <module-option name="rolesProperties" value="  /path/to/kerberos/spnego-roles.properties"/>
          <module-option name="defaultUsersProperties" value="  /path/to/kerberos/spnego-users.properties"/>
          <module-option name="defaultRolesProperties" value="  /path/to/kerberos/spnego-roles.properties"/>
        </login-module>
      </authentication>
    </security-domain>
  </security-domains>
</subsystem>

旧应用程序会部署引用 SPNEGO 安全域并使用 SPNEGO 机制的安全。

将 Kerberos HTTP 身份验证迁移到 Elytron

通过使用安全域和 Kerberos 安全因素,管理接口和应用程序都可以在 Elytron 中进行保护。

  1. 定义用于加载身份信息的安全域。

    /subsystem=elytron/properties-realm=spnego-properties:add(users-properties={path=path/to/spnego-users.properties, plain-text=true, digest-realm-name=ELYTRON.ORG}, groups-properties={path=path/to/spnego-roles.properties})
  2. 定义一个 Kerberos 安全工厂,使服务器可以加载自己的 Kerberos 身份。

    /subsystem=elytron/kerberos-security-factory=test-server:add(path=path/to/test-server.keytab, principal=HTTP/test-server.elytron.org@ELYTRON.ORG, debug=true)
  3. 定义安全域,以拉取策略以及身份验证策略的 HTTP 身份验证工厂。

    /subsystem=elytron/security-domain=SPNEGODomain:add(default-realm=spnego-properties, realms=[{realm=spnego-properties, role-decoder=groups-to-roles}], permission-mapper=default-permission-mapper)
    /subsystem=elytron/http-authentication-factory=spnego-http-authentication:add(security-domain=SPNEGODomain, http-server-mechanism-factory=global,mechanism-configurations=[{mechanism-name=SPNEGO, credential-security-factory=test-server}])

    这会在服务器配置文件的 elytron 子系统中生成以下配置:

    示例:迁移 Elytron 配置

    <subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
      ...
      <security-domains>
      ...
        <security-domain name="SPNEGODomain" default-realm="spnego-properties" permission-mapper="default-permission-mapper">
          <realm name="spnego-properties" role-decoder="groups-to-roles"/>
        </security-domain>
      </security-domains>
      <security-realms>
        ...
        <properties-realm name="spnego-properties">
          <users-properties path="path/to/spnego-users.properties" digest-realm-name="ELYTRON.ORG" plain-text="true"/>
          <groups-properties path="path/to/spnego-roles.properties"/>
        </properties-realm>
      </security-realms>
      <credential-security-factories>
        <kerberos-security-factory name="test-server" principal="HTTP/test-server.elytron.org@ELYTRON.ORG" path="path/to/test-server.keytab" debug="true"/>
      </credential-security-factories>
      ...
      <http>
        ...
        <http-authentication-factory name="spnego-http-authentication" http-server-mechanism-factory="global" security-domain="SPNEGODomain">
          <mechanism-configuration>
            <mechanism mechanism-name="SPNEGO" credential-security-factory="test-server"/>
          </mechanism-configuration>
        </http-authentication-factory>
        ...
      </http>
      ...
    </subsystem>

  4. 为保护应用,请在 undertow 子系统中定义应用安全域,将安全域映射到此 http-authentication-factory。可以更新 HTTP 管理界面,以引用此配置中定义的 http-authentication-factory。这个过程包括在本指南的 Migrate Properties- authentication and Authorization to Elytron 部分。
迁移 Kerberos 远程 SASL 身份验证

可以为 Kerberos/ GSSAPI SASL 身份验证定义旧安全域,以用于重新访问身份验证,如原生管理接口。

示例:用于删除管理 CLI 命令的 Kerberos 身份验证

/core-service=management/security-realm=Kerberos:add
/core-service=management/security-realm=Kerberos/server-identity=kerberos:add
/core-service=management/security-realm=Kerberos/server-identity=kerberos/keytab=remote\/test-server.elytron.org@ELYTRON.ORG:add(path=path/to/remote-test-server.keytab, debug=true)
/core-service=management/security-realm=Kerberos/authentication=kerberos:add(remove-realm=true)

示例:Kerberos 远程安全域配置

<management>
  <security-realms>
    ...
    <security-realm name="Kerberos">
      <server-identities>
        <kerberos>
          <keytab principal="remote/test-server.elytron.org@ELYTRON.ORG" path="path/to/remote-test-server.keytab" debug="true"/>
        </kerberos>
      </server-identities>
      <authentication>
        <kerberos remove-realm="true"/>
      </authentication>
    </security-realm>
  </security-realms>
  ...
</management>

将 Kerberos 远程 SASL 身份验证迁移到 Elytron

定义同等的 Elytron 配置的步骤与 迁移 Kerberos HTTP 身份验证 中所述的步骤非常相似。

  1. 定义用于加载身份信息的安全域。

    /path=kerberos:add(relative-to=user.home, path=src/kerberos)
    /subsystem=elytron/properties-realm=kerberos-properties:add(users-properties={path=kerberos-users.properties, relative-to=kerberos, digest-realm-name=ELYTRON.ORG}, groups-properties={path=kerberos-groups.properties, relative-to=kerberos})
  2. 为服务器身份定义 Kerberos 安全因素。

    /subsystem=elytron/kerberos-security-factory=test-server:add(relative-to=kerberos, path=remote-test-server.keytab, principal=remote/test-server.elytron.org@ELYTRON.ORG)
  3. 定义安全域和 SASL 身份验证工厂。

    /subsystem=elytron/security-domain=KerberosDomain:add(default-realm=kerberos-properties, realms=[{realm=kerberos-properties, role-decoder=groups-to-roles}], permission-mapper=default-permission-mapper)
    /subsystem=elytron/sasl-authentication-factory=gssapi-authentication-factory:add(security-domain=KerberosDomain, sasl-server-factory=elytron, mechanism-configurations=[{mechanism-name=GSSAPI, credential-security-factory=test-server}])

这会在服务器配置文件的 elytron 子系统中生成以下配置:

<subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
  ...
  <security-domains>
    ...
    <security-domain name="KerberosDomain" default-realm="kerberos-properties" permission-mapper="default-permission-mapper">
      <realm name="kerberos-properties" role-decoder="groups-to-roles"/>
    </security-domain>
  </security-domains>
  <security-realms>
   ...
     <properties-realm name="kerberos-properties">
       <users-properties path="kerberos-users.properties" relative-to="kerberos" digest-realm-name="ELYTRON.ORG"/>
       <groups-properties path="kerberos-groups.properties" relative-to="kerberos"/>
     </properties-realm>
   </security-realms>
   <credential-security-factories>
     <kerberos-security-factory name="test-server" principal="remote/test-server.elytron.org@ELYTRON.ORG" path="remote-test-server.keytab" relative-to="kerberos"/>
   </credential-security-factories>
   ...
   <sasl>
     ...
     <sasl-authentication-factory name="gssapi-authentication-factory" sasl-server-factory="elytron" security-domain="KerberosDomain">
       <mechanism-configuration>
         <mechanism mechanism-name="GSSAPI" credential-security-factory="test-server"/>
       </mechanism-configuration>
     </sasl-authentication-factory>
     ...
   </sasl>
 </subsystem>

现在,可以更新管理界面或补救连接器来引用 SASL 身份验证工厂。

此处定义的两个 Elytron 示例也可以合并使用共享安全域和安全域,且仅使用特定于协议的身份验证因素,每个都引用其自己的 Kerberos 安全工厂。

7.3.6. 将 Composite Stores 迁移到 Elytron

本节论述了如何将 PicketBox旧安全域 配置迁移到 Elytron。在使用 PicketBox 或传统的安全域时,可以定义针对一个身份存储进行身份验证的配置,同时从不同的存储中加载用于授权的信息。迁移到 Elytron 时,可以使用聚合安全域来实现。

以下示例使用 example-users.properties 属性文件执行用户身份验证,然后查询 LDAP 来加载组和角色信息。

注意

显示的配置基于以下部分中的示例,它们提供额外的背景信息:

Picketbox Composite Store Configuration

此情境的 PicketBox 安全域使用以下管理 CLI 命令进行配置。

示例:PicketBox 配置命令

/subsystem=security/security-domain=application-security:add

/subsystem=security/security-domain=application-security/authentication=classic:add(login-modules=[ {code=UsersRoles, flag=Required, module-options={ password-stacking=useFirstPass, usersProperties=file://${jboss.server.config.dir}/example-users.properties}} {code=LdapExtended, flag=Required, module-options={ password-stacking=useFirstPass, java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory, java.naming.provider.url=ldap://localhost:10389, java.naming.security.authentication=simple, bindDN="uid=admin,ou=system", bindCredential=secret, baseCtxDN="ou=users,dc=group-to-principal,dc=wildfly,dc=org", baseFilter="(uid={0})", rolesCtxDN="ou=groups,dc=group-to-principal,dc=wildfly,dc=org",roleFilter="(uniqueMember={1})", roleAttributeID="uid" }}])

这会生成以下服务器配置。

示例:PicketBox 安全域配置

<security-domain name="application-security">
  <authentication>
    <login-module code="UsersRoles" flag="required">
      <module-option name="password-stacking" value="useFirstPass"/>
      <module-option name="usersProperties" value="file://${jboss.server.config.dir}/example-users.properties"/>
    </login-module>
    <login-module code="LdapExtended" flag="required">
      <module-option name="password-stacking" value="useFirstPass"/>
      <module-option name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory"/>
      <module-option name="java.naming.provider.url" value="ldap://localhost:10389"/>
      <module-option name="java.naming.security.authentication" value="simple"/>
      <module-option name="bindDN" value="uid=admin,ou=system"/>
      <module-option name="bindCredential" value="secret"/>
      <module-option name="baseCtxDN" value="ou=users,dc=group-to-principal,dc=wildfly,dc=org"/>
      <module-option name="baseFilter" value="(uid={0})"/>
      <module-option name="rolesCtxDN" value="ou=groups,dc=group-to-principal,dc=wildfly,dc=org"/>
      <module-option name="roleFilter" value="(uniqueMember={1})"/>
      <module-option name="roleAttributeID" value="uid"/>
    </login-module>
  </authentication>
</security-domain>

请参阅 Elytron Aggregate Security Realm Configuration,了解如何在 elytron 子系统中配置聚合安全域,以完成此操作。

传统的安全性 Realm Composite Store 配置

此情境的传统安全域配置使用下列管理 CLI 命令进行配置。

示例:传统安全实时配置命令

/core-service=management/ldap-connection=MyLdapConnection:add(url="ldap://localhost:10389", search-dn="uid=admin,ou=system", search-credential="secret")

/core-service=management/security-realm=ApplicationSecurity:add
/core-service=management/security-realm=ApplicationSecurity/authentication=properties:add(path=example-users.properties, relative-to=jboss.server.config.dir, plain-text=true)

batch
/core-service=management/security-realm=ApplicationSecurity/authorization=ldap:add(connection=MyLdapConnection)
/core-service=management/security-realm=ApplicationSecurity/authorization=ldap/username-to-dn=username-filter:add(attribute=uid, base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org")
/core-service=management/security-realm=ApplicationSecurity/authorization=ldap/group-search=group-to-principal:add(base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org", iterative=true, prefer-original-connection=true, principal-attribute=uniqueMember, search-by=DISTINGUISHED_NAME, group-name=SIMPLE, group-name-attribute=uid)
run-batch

这会生成以下服务器配置。

示例:传统安全域配置

<security-realms>
  ...
  <security-realm name="ApplicationSecurity">
    <authentication>
      <properties path="example-users.properties" relative-to="jboss.server.config.dir" plain-text="true"/>
    </authentication>
    <authorization>
      <ldap connection="MyLdapConnection">
        <username-to-dn>
          <username-filter base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org" attribute="uid"/>
        </username-to-dn>
        <group-search group-name="SIMPLE" iterative="true" group-name-attribute="uid">
          <group-to-principal search-by="DISTINGUISHED_NAME" base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org" prefer-original-connection="true">
            <membership-filter principal-attribute="uniqueMember"/>
          </group-to-principal>
        </group-search>
      </ldap>
    </authorization>
  </security-realm>
</security-realms>
<outbound-connections>
  <ldap name="MyLdapConnection" url="ldap://localhost:10389" search-dn="uid=admin,ou=system" search-credential="secret"/>
</outbound-connections>

请参阅 Elytron Aggregate Security Realm Configuration,了解如何在 elytron 子系统中配置聚合安全域,以完成此操作。

Elytron Aggregate Security Realm 配置

此情境对应的 Elytron 配置使用以下管理 CLI 命令进行配置。

示例: Elytron Configuration 命令

/subsystem=elytron/dir-context=ldap-connection:add(url=ldap://localhost:10389, principal="uid=admin,ou=system", credential-reference={clear-text=secret})

/subsystem=elytron/ldap-realm=ldap-realm:add(dir-context=ldap-connection, direct-verification=true, identity-mapping={search-base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org", rdn-identifier="uid", attribute-mapping=[{filter-base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org",filter="(uniqueMember={1})",from="uid",to="Roles"}]})

/subsystem=elytron/properties-realm=application-properties:add(users-properties={path=example-users.properties, relative-to=jboss.server.config.dir, plain-text=true, digest-realm-name="Application Security"})

/subsystem=elytron/aggregate-realm=combined-realm:add(authentication-realm=application-properties, authorization-realm=ldap-realm)

/subsystem=elytron/security-domain=application-security:add(realms=[{realm=combined-realm}], default-realm=combined-realm, permission-mapper=default-permission-mapper)
/subsystem=elytron/http-authentication-factory=application-security-http:add(http-server-mechanism-factory=global, security-domain=application-security, mechanism-configurations=[{mechanism-name=BASIC}])

这会生成以下服务器配置。

示例:Elytron 配置

<subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
  ...
  <security-domains>
    ...
    <security-domain name="application-security" default-realm="combined-realm" permission-mapper="default-permission-mapper">
      <realm name="combined-realm"/>
    </security-domain>
  </security-domains>
  <security-realms>
    <aggregate-realm name="combined-realm" authentication-realm="application-properties" authorization-realm="ldap-realm"/>
      ...
      <properties-realm name="application-properties">
        <users-properties path="example-users.properties" relative-to="jboss.server.config.dir" digest-realm-name="Application Security" plain-text="true"/>
      </properties-realm>
      <ldap-realm name="ldap-realm" dir-context="ldap-connection" direct-verification="true">
        <identity-mapping rdn-identifier="uid" search-base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org">
          <attribute-mapping>
            <attribute from="uid" to="Roles" filter="(uniqueMember={1})" filter-base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org"/>
          </attribute-mapping>
        </identity-mapping>
      </ldap-realm>
  </security-realms>
  ...
  <http>
    ...
    <http-authentication-factory name="application-security-http" http-server-mechanism-factory="global" security-domain="application-security">
      <mechanism-configuration>
        <mechanism mechanism-name="BASIC"/>
      </mechanism-configuration>
    </http-authentication-factory>
    ...
  </http>
  ...
  <dir-contexts>
    <dir-context name="ldap-connection" url="ldap://localhost:10389" principal="uid=admin,ou=system">
      <credential-reference clear-text="secret"/>
    </dir-context>
  </dir-contexts>
</subsystem>

elytron 子系统中,定义了 aggregate-realm,它指定了用于身份验证的安全性和用于授权决策的安全域。

7.3.7. 将使用缓存的安全域迁移到 Elytron

使用 PicketBox 时,可以定义一个安全域并启用内存缓存的访问权限。这可让您访问内存中的身份数据,并避免对身份存储进行额外的直接访问。可以通过 Elytron 实现类似的配置。这部分论述了如何在使用 Elytron 时配置安全域缓存。

Picketbox Cached Security Domain configuration

以下命令显示如何配置启用缓存的 PicketBox 安全域。

示例:PicketBox Cached Security Domain Commands

/subsystem=security/security-domain=application-security:add(cache-type=default)
/subsystem=security/security-domain=application-security/authentication=classic:add(login-modules=[{code=LdapExtended, flag=Required, module-options={ java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory, java.naming.provider.url=ldap://localhost:10389, java.naming.security.authentication=simple, bindDN="uid=admin,ou=system", bindCredential=secret, baseCtxDN="ou=users,dc=group-to-principal,dc=wildfly,dc=org", baseFilter="(uid={0})", rolesCtxDN="ou=groups,dc=group-to-principal,dc=wildfly,dc=org", roleFilter="(uniqueMember={1})", roleAttributeID="uid" }}])

这会生成以下服务器配置。

示例:PicketBox Cached Security Domain Configuration

<subsystem xmlns="urn:jboss:domain:security:2.0">
  <security-domains>
    ...
    <security-domain name="application-security" cache-type="default">
      <authentication>
        <login-module code="LdapExtended" flag="required">
          <module-option name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory"/>
          <module-option name="java.naming.provider.url" value="ldap://localhost:10389"/>
          <module-option name="java.naming.security.authentication" value="simple"/>
          <module-option name="bindDN" value="uid=admin,ou=system"/>
          <module-option name="bindCredential" value="secret"/>
          <module-option name="baseCtxDN" value="ou=users,dc=group-to-principal,dc=wildfly,dc=org"/>
          <module-option name="baseFilter" value="(uid={0})"/>
          <module-option name="rolesCtxDN" value="ou=groups,dc=group-to-principal,dc=wildfly,dc=org"/>
          <module-option name="roleFilter" value="(uniqueMember={1})"/>
          <module-option name="roleAttributeID" value="uid"/>
        </login-module>
      </authentication>
    </security-domain>
  </security-domains>
</subsystem>

注意

此命令和生成的配置与将 LDAP 身份验证配置迁移到 Elytron 中的示例 类似,但此处的 cache-type 属性由 default 的值来定义。默认 缓存类型是一个内存中缓存。使用 PicketBox 时,您还可以指定 infinispancache-type,但这种类型不支持 Elytron。

Elytron Cached 安全域配置

按照以下步骤创建使用 Elytron 时缓存安全域的类似配置。

  1. 定义安全域,并将安全域嵌套在缓存域中。然后,缓存域就可以在安全域中使用,然后在身份验证工厂中使用。

    示例: Elytron Security Realm Configuration 命令

    /subsystem=elytron/dir-context=ldap-connection:add(url=ldap://localhost:10389, principal="uid=admin,ou=system", credential-reference={clear-text=secret})
    /subsystem=elytron/ldap-realm=ldap-realm:add(dir-context=ldap-connection, direct-verification=true, identity-mapping={search-base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org", rdn-identifier="uid", attribute-mapping=[{filter-base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org",filter="(uniqueMember={1})",from="uid",to="Roles"}]})
    /subsystem=elytron/caching-realm=cached-ldap:add(realm=ldap-realm)

  2. 定义安全域和 HTTP 身份验证工厂,它使用上一步中定义的 cached-ldap 域。

    示例:在安全域和验证因素配置命令

    /subsystem=elytron/security-domain=application-security:add(realms=[{realm=cached-ldap}], default-realm=cached-ldap, permission-mapper=default-permission-mapper)
    /subsystem=elytron/http-authentication-factory=application-security-http:add(http-server-mechanism-factory=global, security-domain=application-security, mechanism-configurations=[{mechanism-name=BASIC}])

    注意

    在这一步中,务必要引用 caching-realm,而不是原始域。否则,会绕过缓存。

这些命令会产生到服务器配置的以下新增功能。

示例: Elytron Cached Security Domain configuration

<subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
  ...
  <security-domains>
    ...
    <security-domain name="application-security" default-realm="cached-ldap" permission-mapper="default-permission-mapper">
      <realm name="cached-ldap"/>
    </security-domain>
  </security-domains>
  ...
  <security-realms>
    ....
  <ldap-realm name="ldap-realm" dir-context="ldap-connection" direct-verification="true">
      <identity-mapping rdn-identifier="uid" search-base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org">
        <attribute-mapping>
          <attribute from="uid" to="Roles" filter="(uniqueMember={1})" filter-base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org"/>
        </attribute-mapping>
      </identity-mapping>
    </ldap-realm>
    <caching-realm name="cached-ldap" realm="ldap-realm"/>
  </security-realms>
  ...
  <http>
    ...
    <http-authentication-factory name="application-security-http" http-server-mechanism-factory="global" security-domain="application-security">
      <mechanism-configuration>
        <mechanism mechanism-name="BASIC"/>
      </mechanism-configuration>
    </http-authentication-factory>
    ...
  </http>
   ...
  <dir-contexts>
    <dir-context name="ldap-connection" url="ldap://localhost:10389" principal="uid=admin,ou=system">
      <credential-reference clear-text="secret"/>
    </dir-context>
  </dir-contexts>
  ...

7.3.8. 将 Jakarta 授权安全性迁移到 Elytron

默认情况下,JBoss EAP 使用传统的 security 子系统配置 Jakarta 授权策略提供商和工厂。默认配置映射从 PicketBox 映射到实施。

elytron 子系统根据 Jakarta 授权规范提供内置的策略提供程序。在将服务器配置为允许 Elytron 管理 Jakarta Authorization 配置和其他策略之前,您必须首先使用以下管理 CLI 命令 在旧安全 子系统中禁用 Jakarta Authorization。

/subsystem=security:write-attribute(name=initialize-jacc, value=false)

如果不这样做,则会在服务器日志中包括以下信息:MSC000004: Failure during stop of service org.wildfly.security.policy: java.lang.StackOverflowError

有关如何启用 Jakarta 授权并在 elytron 子系统中定义 Jakarta 授权策略提供程序的信息,请参阅 JBoss EAP 开发指南中的 启用 Jakarta 授权

7.4. 迁移应用程序客户端

7.4.1. 将 Naming Client 配置迁移到 Elytron

本节介绍如何使用 org.jboss.naming.remote.client.InitialContext 类执行远程 JNDI 查找的客户端应用程序,该类由 org.jboss.naming.remote.client.InitialContext 类来支持。

以下示例假设通过为用户凭证指定属性和它连接到的命名供应商的 URL 创建 InitialContextFactory 类。

示例:之前版本中使用的 InitialContext 代码

Properties properties = new Properties();
properties.put(Context.INITIAL_CONTEXT_FACTORY, "org.jboss.naming.remote.client.InitialContextFactory");
properties.put(Context.PROVIDER_URL,"http-remoting://127.0.0.1:8080");
properties.put(Context.SECURITY_PRINCIPAL, "bob");
properties.put(Context.SECURITY_CREDENTIALS, "secret");
InitialContext context = new InitialContext(properties);
Bar bar = (Bar) context.lookup("foo/bar");
...

您可以从以下迁移方法之一中选择:

7.4.1.1. 使用配置文件方法迁移 Naming 客户端

按照以下步骤,使用配置方法将命名客户端迁移到 Elytron。

  1. 在客户端应用程序 META-INF/ 目录中创建 wildfly-config.xml 文件。该文件应包含要在建立与命名提供程序的连接时使用的用户凭据。

    示例: wildfly-config.xml 文件

    <configuration>
      <authentication-client xmlns="urn:elytron:client:1.2">
        <authentication-rules>
          <rule use-configuration="namingConfig">
            <match-host name="127.0.0.1"/>
          </rule>
        </authentication-rules>
        <authentication-configurations>
          <configuration name="namingConfig">
            <set-user-name name="bob"/>
            <credentials>
              <clear-password password="secret"/>
            </credentials>
          </configuration>
        </authentication-configurations>
      </authentication-client>
    </configuration>

  2. 如下例所示,创建一个 InitialContext。请注意,InitialContextorg.wildfly.naming.client.WildFlyInitialContextFactory 类支持。

    示例: InitialContext 代码

    Properties properties = new Properties();
    properties.put(Context.INITIAL_CONTEXT_FACTORY,"org.wildfly.naming.client.WildFlyInitialContextFactory");
    properties.put(Context.PROVIDER_URL,"remote+http://127.0.0.1:8080");
    InitialContext context = new InitialContext(properties);
    Bar bar = (Bar) context.lookup("foo/bar");
    ...

7.4.1.2. 使用编程方法迁移 Naming 客户端

使用此方法,您可以提供用于在应用程序代码中直接与命名提供程序建立连接的用户凭证。

示例:使用编程方法进行代码

// Create the authentication configuration
AuthenticationConfiguration namingConfig = AuthenticationConfiguration.empty().useName("bob").usePassword("secret");

// Create the authentication context
AuthenticationContext context = AuthenticationContext.empty().with(MatchRule.ALL.matchHost("127.0.0.1"), namingConfig);

// Create a callable that creates and uses an InitialContext
Callable<Void> callable = () -> {
    Properties properties = new Properties();
    properties.put(Context.INITIAL_CONTEXT_FACTORY,"org.wildfly.naming.client.WildFlyInitialContextFactory");
    properties.put(Context.PROVIDER_URL,"remote+http://127.0.0.1:8080");
    InitialContext context = new InitialContext(properties);
    Bar bar = (Bar) context.lookup("foo/bar");
    ...
    return null;
};

// Use the authentication context to run the callable
context.runCallable(callable);

7.4.2. 将 Jakarta Enterprise Beans 客户端迁移到 Elytron

此迁移示例假定客户端应用已配置为通过 jboss-ejb-client.properties 文件调用部署到远程服务器的 Jakarta Enterprise Beans。此文件位于客户端应用 META-INF/ 目录中,包含连接到远程服务器所需的以下信息。

示例: jboss-ejb-client.properties 文件

remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
remote.connections=default
remote.connection.default.host=127.0.0.1
remote.connection.default.port = 8080
remote.connection.default.username=bob
remote.connection.default.password=secret

客户端使用类似以下示例的代码查找 Jakarta Enterprise Beans 并调用其方法之一。

示例:调用远程 Jakarta Enterprise Bean 的客户端代码

// Create an InitialContext
Properties properties = new Properties();
properties.put(Context.URL_PKG_PREFIXES, "org.jboss.ejb.client.naming");
InitialContext context = new InitialContext(properties);

// Look up the {JEB} and invoke one of its methods
RemoteCalculator statelessRemoteCalculator = (RemoteCalculator) context.lookup(
    "ejb:/ejb-remote-server-side//CalculatorBean!" + RemoteCalculator.class.getName());
int sum = statelessRemoteCalculator.add(101, 202);

您可以从以下迁移方法之一中选择:

7.4.2.1. 使用配置文件迁移 Jakarta Enterprise Beans 客户端

按照以下步骤,使用配置方法将命名客户端迁移到 Elytron。

  1. 在客户端应用程序 META-INF/ 目录中配置 wildfly-config.xml 文件。该文件应包含要在建立与命名提供程序的连接时使用的用户凭据。

    示例: wildfly-config.xml 文件

    <configuration>
      <authentication-client xmlns="urn:elytron:client:1.2">
        <authentication-rules>
          <rule use-configuration="ejbConfig">
            <match-host name="127.0.0.1"/>
          </rule>
        </authentication-rules>
        <authentication-configurations>
          <configuration name="ejbConfig">
            <set-user-name name="bob"/>
            <credentials>
              <clear-password password="secret"/>
            </credentials>
          </configuration>
        </authentication-configurations>
      </authentication-client>
      <jboss-ejb-client xmlns="urn:jboss:wildfly-client-ejb:3.0">
        <connections>
          <connection uri="remote+http://127.0.0.1:8080" />
        </connections>
      </jboss-ejb-client>
    </configuration>

  2. 如下例所示,创建一个 InitialContext。请注意,InitialContextorg.wildfly.naming.client.WildFlyInitialContextFactory 类支持。

    示例: InitialContext 代码

    // Create an InitialContext
    Properties properties = new Properties();
    properties.put(Context.INITIAL_CONTEXT_FACTORY,"org.wildfly.naming.client.WildFlyInitialContextFactory");
    InitialContext context = new InitialContext(properties);
    
    // Look up an {JEB} and invoke one of its methods
    // Note that this code is the same as before
    RemoteCalculator statelessRemoteCalculator = (RemoteCalculator) context.lookup(
        "ejb:/ejb-remote-server-side//CalculatorBean!" + RemoteCalculator.class.getName());
    int sum = statelessRemoteCalculator.add(101, 202);----

  3. 现在,您可以删除过时的 jboss-ejb-client.properties 文件,因为不再需要该文件。

7.4.2.2. 以编程方式迁移 Jakarta Enterprise Beans 客户端

使用此方法,您可以提供在应用程序代码中直接连接远程服务器所需的信息。

示例:使用编程方法进行代码

// Create the authentication configuration
AuthenticationConfiguration ejbConfig = AuthenticationConfiguration.empty().useName("bob").usePassword("secret");

// Create the authentication context
AuthenticationContext context = AuthenticationContext.empty().with(MatchRule.ALL.matchHost("127.0.0.1"), ejbConfig);

// Create a callable that invokes the {JEB}
Callable<Void> callable = () -> {

    // Create an InitialContext
    Properties properties = new Properties();
    properties.put(Context.INITIAL_CONTEXT_FACTORY, "org.wildfly.naming.client.WildFlyInitialContextFactory");
    properties.put(Context.PROVIDER_URL, "remote+http://127.0.0.1:8080");
    InitialContext context = new InitialContext(properties);

    // Look up the {JEB} and invoke one of its methods
    // Note that this code is the same as before
    RemoteCalculator statelessRemoteCalculator = (RemoteCalculator) context.lookup(
        "ejb:/ejb-remote-server-side//CalculatorBean!" + RemoteCalculator.class.getName());
    int sum = statelessRemoteCalculator.add(101, 202);
    ...
    return null;
};

// Use the authentication context to run the callable
context.runCallable(callable);

现在,您可以删除过时的 jboss-ejb-client.properties 文件,因为不再需要该文件。

7.5. 迁移 SSL 配置

7.5.1. 将简单 SSL 配置迁移到 Elytron

如果您使用安全域保护了与 JBoss EAP 服务器的 HTTP 连接,您可以使用本节中提供的信息将该配置迁移到 Elytron。

以下示例假定您在 security-realm 中配置了以下 keystore

示例:使用安全域密钥存储进行 SSL 配置

<security-realm name="ApplicationRealm">
  <server-identities>
    <ssl>
      <keystore path="server.keystore" relative-to="jboss.server.config.dir" keystore-password="keystore_password" alias="server" key-password="key_password" />
    </ssl>
  </server-identities>
</security-realm>

按照以下步骤,以使用 Elytron 实现相同的配置。

  1. elytron 子系统中创建一个 key-store,用于指定密钥存储的位置及其加密的密码。此命令假定密钥存储是使用密钥tool 命令生成的,其类型是 JKS

    /subsystem=elytron/key-store=LocalhostKeyStore:add(path=server.keystore,relative-to=jboss.server.config.dir,credential-reference={clear-text="keystore_password"},type=JKS)
  2. elytron 子系统中创建 key- manager,用于指定上一步中定义的密钥存储、别名和密码。

    /subsystem=elytron/key-manager=LocalhostKeyManager:add(key-store=LocalhostKeyStore,alias-filter=server,credential-reference={clear-text="key_password"})
  3. elytron 子系统中创建 server-ssl-context,它引用了上一步中定义的 key-manager

    /subsystem=elytron/server-ssl-context=LocalhostSslContext:add(key-manager=LocalhostKeyManager)
  4. https-listener 从旧的 security-realm 切换到新创建的 Elytron ssl-context

    batch
    /subsystem=undertow/server=default-server/https-listener=https:undefine-attribute(name=security-realm)
    /subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context,value=LocalhostSslContext)
    run-batch
  5. 重新加载服务器。

    reload

这会在服务器配置文件中生成以下 elytron 子系统配置。

<subsystem xmlns="urn:wildfly:elytron:4.0" ...>
  ...
  <tls>
    <key-stores>
      <key-store name="LocalhostKeyStore">
        <credential-reference clear-text="keystore_password"/>
        <implementation type="JKS"/>
        <file path="server.keystore" relative-to="jboss.server.config.dir"/>
      </key-store>
    </key-stores>
    <key-managers>
      <key-manager name="LocalhostKeyManager" key-store="LocalhostKeyStore"  alias-filter="server">
        <credential-reference clear-text="key_password"/>
      </key-manager>
    </key-managers>
    <server-ssl-contexts>
      <server-ssl-context name="LocalhostSslContext" key-manager="LocalhostKeyManager"/>
    </server-ssl-contexts>
  </tls>
</subsystem>

这会在服务器配置文件中生成以下 undertow 子系统配置。

<https-listener name="https" socket-binding="https" ssl-context="LocalhostSslContext" enable-http2="true"/>

有关更多信息,请参阅如何为 JBoss EAP 配置服务器中的 Elytron 子系统如何保护管理接口

7.5.2. 将 CLIENT-CERT SSL 身份验证迁移到 Elytron

要启用 CLIENT-CERT SSL 身份验证,请将 truststore 元素添加到 身份验证 元素中。

<security-realm name="ManagementRealm">
  <server-identities>
    <ssl>
      <keystore path="server.keystore" relative-to="jboss.server.config.dir" keystore-password="KEYSTORE_PASSWORD" alias="server" key-password="key_password" />
    </ssl>
  </server-identities>
  <authentication>
    <truststore path="server.truststore" relative-to="jboss.server.config.dir" keystore-password="TRUSTSTORE_PASSWORD" />
    <local default-user="$local"/>
    <properties path="mgmt-users.properties" relative-to="jboss.server.config.dir"/>
  </authentication>
</security-realm>
注意

在没有 CLIENT-CERT 身份验证的情况下,客户端可以回退为使用本地机制 或用户名/密码 身份验证机制。要使基于 CLIENT-CERT 的身份验证强制使用,请删除 localproperties 元素。

传统的 truststore 可以通过两种方式使用:

传统的 truststore 只包括 CA

按照以下步骤配置服务器,以防止没有有效证书和私钥的用户使用 Elytron 访问服务器。

  1. elytron 子系统中创建一个 key-store,用于指定密钥存储的位置及其加密的密码。此命令假定密钥存储是使用密钥tool 命令生成的,其类型是 JKS

    /subsystem=elytron/key-store=LocalhostKeyStore:add(path=server.keystore,relative-to=jboss.server.config.dir,credential-reference={clear-text="keystore_password"},type=JKS)
  2. elytron 子系统中创建一个 key-store,用于指定信任存储的位置以及它加密的密码。此命令假定密钥存储是使用密钥tool 命令生成的,其类型是 JKS

    /subsystem=elytron/key-store=TrustStore:add(path=server.truststore,relative-to=jboss.server.config.dir,credential-reference={clear-text="truststore_password"},type=JKS)
  3. elytron 子系统中创建 key-manager,用于指定之前定义的 LocalhostKeyStore 密钥存储、别名和密码。

    /subsystem=elytron/key-manager=LocalhostKeyManager:add(key-store=LocalhostKeyStore,alias-filter=server,credential-reference={clear-text="key_password"})
  4. elytron 子系统中创建 trust-manager,用于指定之前创建的信任存储的 key-store

    /subsystem=elytron/trust-manager=TrustManager:add(key-store=TrustStore)
  5. elytron 子系统中创建 server-ssl-context,该子系统引用之前定义的 key-manager 属性,设置 trust-manager 属性并启用客户端身份验证。

    /subsystem=elytron/server-ssl-context=LocalhostSslContext:add(key-manager=LocalhostKeyManager,trust-manager=TrustManager,need-client-auth=true)
  6. https-listener 从旧的 security-realm 切换到新创建的 Elytron ssl-context

    batch
    /subsystem=undertow/server=default-server/https-listener=https:undefine-attribute(name=security-realm)
    /subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context,value=LocalhostSslContext)
    run-batch
  7. 重新加载服务器。

    reload

这会在服务器配置文件中生成以下 elytron 子系统配置。

<subsystem xmlns="urn:wildfly:elytron:4.0"...>
  ...
  <tls>
    <key-stores>
      <key-store name="LocalhostKeyStore">
        <credential-reference clear-text="keystore_password"/>
        <implementation type="JKS"/>
        <file path="server.keystore" relative-to="jboss.server.config.dir"/>
      </key-store>
      <key-store name="TrustStore">
        <credential-reference clear-text="truststore_password"/>
        <implementation type="JKS"/>
        <file path="server.truststore" relative-to="jboss.server.config.dir"/>
      </key-store>
    </key-stores>
    <key-managers>
      <key-manager name="LocalhostKeyManager" key-store="LocalhostKeyStore" alias-filter="server">
        <credential-reference clear-text="key_password"/>
      </key-manager>
    </key-managers>
    <trust-managers>
      <trust-manager name="TrustManager" key-store="TrustStore"/>
    </trust-managers>
    <server-ssl-contexts>
      <server-ssl-context name="LocalhostSslContext" need-client-auth="true" key-manager="LocalhostKeyManager" trust-manager="TrustManager"/>
    </server-ssl-contexts>
  </tls>
</subsystem>

这会在服务器配置文件中生成以下 undertow 子系统配置。

<subsystem xmlns="urn:jboss:domain:undertow:10.0">
...
<https-listener name="https" socket-binding="https" ssl-context="LocalhostSslContext" enable-http2="true"/>
...
</subsystem>
realm 和 domain

要允许使用预定义的 Elytron ManagementDomain 安全域和管理 Realm 安全域,用户存储在标准属性文件中。

<security-domains>
    <security-domain name="ManagementDomain" default-realm="ManagementRealm" permission-mapper="default-permission-mapper">
        <realm name="ManagementRealm" role-decoder="groups-to-roles"/>
        <realm name="local"/>
    </security-domain>
</security-domains>
<security-realms>
    <properties-realm name="ManagementRealm">
        <users-properties path="mgmt-users.properties" relative-to="jboss.server.config.dir" digest-realm-name="ManagementRealm"/>
        <groups-properties path="mgmt-groups.properties" relative-to="jboss.server.config.dir"/>
    </properties-realm>
</security-realms>

有两个情况下使用安全性域:

  • 当证书身份验证失败时,安全域将用于密码回退。
  • 为密码和证书完成授权后,域会提供各个用户的角色。

因此,对于任何客户端证书,安全域中必须存在一个用户。

主体 Decoder

当使用证书身份验证并且安全域接受用户名来解析身份时,必须有定义的方法是从客户端证书获取 用户名

在这种情况下,CN 属性在证书主体中使用。

/subsystem=elytron/x500-attribute-principal-decoder=x500-decoder:add(attribute-name=CN)
HTTP 身份验证工厂

对于 HTTP 连接,会使用之前定义的资源来定义 HTTP 身份验证工厂。它被配置为支持 CLIENT_CERTDIGEST 身份验证。

由于属性域仅验证密码且无法验证客户端证书,您需要首先添加配置机制工厂。这禁用对安全域的证书验证。

/subsystem=elytron/configurable-http-server-mechanism-factory=configured-cert:add(http-server-mechanism-factory=global, properties={org.wildfly.security.http.skip-certificate-verification=true})

HTTP 验证可以创建:

./subsystem=elytron/http-authentication-factory=client-cert-digest:add(http-server-mechanism-factory=configured-cert,security-domain=ManagementDomain,mechanism-configurations=[{mechanism-name=CLIENT_CERT,pre-realm-principal-transformer=x500-decoder},{mechanism-name=DIGEST, mechanism-realm-configurations=[{realm-name=ManagementRealm}]}])

以上命令结果如下:

<subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
  ...
  <http>
    ...
    <http-authentication-factory name="client-cert-digest" http-server-mechanism-factory="configured-cert" security-domain="ManagementDomain">
      <mechanism-configuration>
        <mechanism mechanism-name="CLIENT_CERT" pre-realm-principal-transformer="x500-decoder"/>
        <mechanism mechanism-name="DIGEST">
          <mechanism-realm realm-name="ManagementRealm"/>
        </mechanism>
      </mechanism-configuration>
    </http-authentication-factory>
    ...
    <configurable-http-server-mechanism-factory name="configured-cert" http-server-mechanism-factory="configured-cert">
        <properties>
            <property name="org.wildfly.security.http.skip-certificate-verification" value="true"/>
        </properties>
    </configurable-http-server-mechanism-factory>
    ...
  </http>
  ...
</subsystem>

第 8 章 从 JBoss EAP 的旧版本迁移

8.1. 从 JBoss EAP 5 迁移到 JBoss EAP 7

本指南重点介绍在 JBoss EAP 7 中成功运行和部署 JBoss EAP 6 应用程序所需的更改。如果您计划将应用程序直接从 JBoss EAP 5 迁移到 JBoss EAP 7,则有很多可用资源可帮助您规划和执行迁移。我们建议您采用以下方法。

  1. 有关 JBoss EAP 的每个发行版本的快速、高级别概述,请参阅本指南中每个发行版本的更改概述
  2. 阅读 JBoss EAP 6 迁移指南 和本指南,熟悉每个产品的内容。
  3. 使用 JBoss EAP 5 组件升级参考作为迁移特定组件和功能的快速参考。
  4. 应用的基于规则的 Migration Toolkit 继续添加规则以帮助您直接从 JBoss EAP 5 迁移到 JBoss EAP 7。您可以使用这些工具分析应用程序并生成有关迁移到 JBoss EAP 7 所需的更改的详细报告。如需更多信息,请参阅 使用 Migration Toolkit for Applications for Migration 分析应用程序
  5. 客户门户网站知识库 目前包含帮助从 JBoss EAP 5 迁移到 JBoss EAP 6 的文章和解决方案。有计划为从 JBoss EAP 5 迁移到 JBoss EAP 7 的额外内容。

8.2. 每个发行版本的更改概述

在规划迁移前,您应该了解对 JBoss EAP 6 和 JBoss EAP 7 所做的更改。

JBoss EAP 6 迁移指南覆盖了 JBoss EAP 5 和 JBoss EAP 6 之间的更改。以下是 JBoss EAP 6 中进行的最为显著更改的精简列表。

  • 实施了基于 Modular Service Container 构建的新架构
  • 经过 Java Enterprise Edition 6 规范的已认证实施
  • 引入了域管理、新的部署配置以及新的文件目录结构和脚本
  • 在新的可移植 Java 命名和目录接口命名空间中标准化

如需了解在此发行版本中进行的详细的更改列表,请参阅 JBoss EAP 6 迁移指南中的JBoss EAP 6 中的新内容和不同

JBoss EAP 7 基于与 JBoss EAP 6 相同的模块化结构构建,包括相同的域管理、部署配置、文件目录结构和脚本。它还使用相同的标准化 Java 命名和目录接口命名空间。但是,JBoss EAP 7 包括以下更改:

  • 添加了对 Jakarta Enterprise Edition(Jakarta EE)8 规格的支持
  • 使用 Undertow 替换 Web 服务器
  • 将 JacORB IIOP 实施替换为 OpenJDK ORB 的下游分支
  • 包括 Apache ActiveMQSOURCE 作为新消息传递提供程序
  • 删除 cmpjaxr线程 子系统
  • 删除对企业级实体 Bean 的支持

如需更完整的更改列表,请参阅 JBoss EAP 7 中的新内容

8.3. 查看迁移指南中的内容

查看每个发行版本的迁移指南的整个内容,了解已添加或已弃用的功能,并了解为该发行版本运行现有应用程序所需的服务器配置和应用更改。

由于 JBoss EAP 6 和 JBoss EAP 7 之间没有改变底层架构,因此 JBoss EAP 6 迁移指南中记录了的许多更改仍然适用。例如,大多数应用程序需要的更改 与 JBoss EAP 6 中的底层架构更改相关,该更改仍应用于此版本。对新模块化类加载系统的改变非常显著,影响几乎每个 JBoss EAP 5 应用的打包和依赖项。在应用程序架构 和组件上更改下列出的许多 更改仍然有效。但是,由于 JBoss EAP 7 替换了 Web 服务器、ORB 和消息传递提供程序,因此删除了 cmp线程jaxr 子系统,并且删除对实体 Bean 的支持,您必须参考本指南以获取与这些组件区域相关的任何更改。在开始之前,请特别注意本指南中详述的服务器配置更改应用迁移更改

8.4. JBoss EAP 5 组件升级参考

使用下表查找如何将特定功能或组件从 JBoss EAP 5 迁移到 JBoss EAP 7.4 的信息。

JBoss EAP 5
功能或组件
更改概述和
从哪里查找迁移信息

应用程序打包和类加载

在 JBoss EAP 6 中,以前的分层类加载结构被替换为基于 JBoss 模块的模块架构。由于新的模块化类加载结构,应用程序打包也会改变。此架构仍在 JBoss EAP 7 中使用。有关新模块化架构的详情,请参考 JBoss EAP 7.4 开发指南中的以下章节:

有关如何为新的模块化架构更新并重新打包应用程序的详情,请参考 JBoss EAP 6 迁移指南中的以下内容。

应用程序配置文件

由于 JBoss EAP 6 中的更改使用模块类加载,您可能需要创建或修改一个或多个应用配置文件来添加依赖项或防止自动依赖项加载。JBoss EAP 7 中的这一变化。详情请查看 JBoss EAP 6 迁移指南中的以下章节:

缓存和 Infinispan

JBoss 缓存被 Infinispan 替代,供服务器在 JBoss EAP 6 中供服务器使用。如需了解如何在应用程序代码中替换 JBoss Cache 的信息,请参阅 JBoss EAP 6 迁移指南 中的以下部分。

JBoss EAP 7 的 JBoss EAP 7 的缓存策略和配置更改记录在本指南的以下部分。

数据源和资源适配器

JBoss EAP 6 将数据源和资源适配器的配置整合为一个文件,这在 JBoss EAP 7 中仍如此。如需更多信息,请参阅 JBoss EAP 6 迁移指南中的 以下章节。

目录结构、脚本和部署配置

在 JBoss EAP 6 中,目录结构、脚本和部署配置已改变。这些更改在 JBoss EAP 7 中仍然有效。如需更多信息,请参阅 JBoss EAP 6 迁移指南 的以下部分。

Enterprise Bean

您的应用程序代码必须使用 enterprise Bean 3.x API 和 Jakarta Persistence。有关运行 Enterprise Beans 2.1 所需的已弃用的功能和更改的详情,请参考 JBoss EAP 6 迁移指南中的以下章节 :

在 JBoss EAP 6 中,有状态会话 bean 缓存和无状态会话 bean 池大小在服务器配置文件的 ejb3 子系统中配置。jboss-ejb3.xml 部署描述符替换了 jboss.xml 部署描述符文件。有关这些更改的更多信息,请参阅 JBoss EAP 6 迁移指南中的以下内容:

JBoss EAP 7 中更改了默认远程连接器和端口。有关这个和服务器配置更改的更多信息,请参阅本指南中的以下部分。

JBoss EAP 7 不支持 Enterprise bean 实体 Bean。有关如何将实体 Bean 迁移到 Jakarta Persistence 的信息,请参阅本指南的以下部分。

Hibernate 和 Jakarta Persistence

JBoss EAP 7.4 实施 Jakarta Persistence 2.2 并包括 Hibernate 5.3。它还包括 Hibernate Search 版本 5.10。其他变更包括删除 Jakarta Enterprise Beans 实体 Beans 实体 Bean 以及 Jakarta Persistence 属性的其他更新。有关这些更改对应用程序如何影响的详情,请参考本指南中的以下部分。

注意

不支持使用与 JBoss EAP 附带的版本不同的 Hibernate 版本。JBoss EAP 附带的版本是唯一经过测试的 Hibernate 版本,也是为缺陷提供补丁的唯一版本。

jakarta RESTful Web 服务和 RESTEasy

JBoss EAP 7 包括 RESTEasy 3 和许多类已被弃用。Jackson 的版本从版本 1.9.9 改为 2.6.3 或更高版本。有关这些更改的详情,请查看本指南中的以下部分。

JBoss AOP

JBoss AOP(Aspect Oriented programming)已在 JBoss EAP 6 中删除。有关如何重构使用 JBoss AOP 的应用的详情,请参考 JBoss EAP 6 迁移指南中的以下章节。

JGroups 和集群

在 JBoss EAP 6 中启用集群并指定绑定地址的方式。如需更多信息,请参阅 JBoss EAP 6 迁移指南中的 以下章节。

在 JBoss EAP 7 中,JGroups 现在默认使用私有网络接口而不是公共网络接口,同时也向 jgroups 子系统引入 & lt;channel > 元素。JBoss EAP 7 还包括 Undertow mod_cluster 实施,它引入了一个新的 API,用于构建单例服务和其他新的集群功能。这些更改记录在本指南的以下部分。

Java 命名和目录接口

JBoss EAP 6 实施了新的标准化全局 Java 命名和目录接口命名空间和一系列相关命名空间,它们映射到应用程序的各种范围。有关使用新 Java 命名和目录接口命名空间规则所需的应用程序更改的信息,请参阅 JBoss EAP 6 迁移指南的以下部分。

jakarta Server Faces

在 JBoss EAP 6.4 上,您可以将您的应用程序配置为使用较旧版本。JBoss EAP 7.4 中无法再做到这一点,它现在包含 Jakarta Server Faces 2.3。如需更多信息,请参阅本指南中的以下部分。

日志记录

JBoss EAP 6 引入了新的 JBoss Logging 框架,仍在 JBoss EAP 7 中使用。使用第三方日志记录框架的应用程序可能会受到模块类加载更改的影响。有关这些更改的信息,请参阅 JBoss EAP 6 迁移指南中的 以下部分。

在 JBoss EAP 7 中,org.jboss.logging 软件包中的注解现已弃用,这会影响源代码和 Maven GAVs(groupId:artifactId:version)。所有日志消息的前缀也被更改。有关这些更改的详情,请参考本指南中的以下部分。

消息传递和 Jakarta Messaging

在 JBoss EAP 7 中,ActiveMQ(0)被取代 HornetQ 作为内置的消息传递提供程序。

迁移消息传递配置的最佳方法是从 JBoss EAP 7 默认服务器配置开始,并使用以下指南应用您当前的消息传递配置更改。

如果您想了解从 JBoss Messaging 迁移到 HornetQ 所需的更改,请查看 JBoss EAP 6 迁移指南中的以下章节:

然后,请参阅以下有关如何迁移 HornetQ 配置和相关消息传递数据的以下信息。

ORB

在 JBoss EAP 6 中,JacORB 配置已经从 EAP_HOME/server/production/conf/jacorb.properties 文件移动到服务器配置文件。JBoss EAP 7 然后将 JacORB IIOP 实施替换为 OpenJDK ORB 的下游分支。

迁移 ORB 配置的最佳方法是从 JBoss EAP 7 默认服务器配置开始,并使用 JBoss EAP 7.4 配置指南中的以下小节 来应用您当前的 ORB 配置更改。

远程调用

JBoss EAP 6 中引入了一个新的企业级客户端 API,用于远程调用;但是,如果您更喜欢不重写应用程序代码以使用新的 API,您可以修改现有代码以使用 ejb:BEAN_REFERENCE,以便远程访问企业级 Bean。如需更多信息,请参阅 JBoss EAP 6 迁移指南中的 以下章节。

在 JBoss EAP 7 中,默认的连接器和默认远程连接端口已更改。如需更多信息,请参阅本指南中的以下部分。

Seam 2.x

虽然 JBoss EAP 6 中丢弃了对 Seam 2.2 应用程序的官方支持,但仍可以配置 Seam 2.2 应用程序的依赖项,以便在该版本上运行。JBoss EAP 7.4(现在包含 Jakarta Server Faces 2.3 和 Hibernate 5.3)由于 Red Hat JBoss Web Framework Kit 的生命周期结束,所以不支持 Seam 2.2 或 Seam 2.3。建议您使用 Weld CDI Bean 重写 Seam 组件。

安全性

JBoss EAP 6 中的安全更新包括对安全域名的更改,以及如何配置基本身份验证的安全。LDAP 安全域配置已移到服务器配置文件中。如需更多信息,请参阅 JBoss EAP 6 迁移指南 中的以下章节。

影响 JBoss EAP 7 中的安全性的更新包括服务器配置更改和应用变化。可在本指南的以下部分中找到信息。

Spring 应用程序

Spring 4.2.x 是 JBoss EAP 7 支持的早期稳定 Spring 版本。有关 Apache CXF Spring web 服务和 Spring RESTEasy 集成更改的详情,请参考本指南中的以下部分。

Transactions

在 JBoss EAP 6 中,事务配置合并并移到服务器配置文件。其他更新包括对 JTA 节点标识符设置的更改以及如何启用 JTS。详情请查看 JBoss EAP 6 迁移指南中的以下章节:

JBoss EAP 6 中的 transaction 子系统中提供的一些交易管理器配置属性在 JBoss EAP 7 中有所变化。如需更多信息,请参阅本指南的以下部分。

Valves

Undertow 在 JBoss EAP 7 中取代了 JBoss Web,因此不再支持 valves。请参见本指南中的以下部分。

Web 服务

JBoss EAP 6 包括 JBossWS 4.有关该版本更新所需更改的详情,请参考 JBoss EAP 6 迁移指南中的以下内容。

JBoss EAP 7 引入了 JBossWS 5。如需所需更新,请参见本指南中的以下部分。

附录 A. 参考资料

A.1. Jacorb 子系统迁移操作警告

迁移操作无法处理所有资源和属性。下表列出了您在运行 jacorb 子系统的 migratedescribe-migration 操作时可能会看到的一些警告。

注意

如果您在迁移操作输出中看到 "Could not migrate" 或 "Can not migrate " 条目,这表示成功完成了服务器配置,但无法自动迁移所有元素和属性。您必须遵循"migration-warnings"提供的建议来修改这些配置。

警告信息它代表什么/如何修复它

当服务器处于 admin-only 模式时,可以执行 iiop 迁移

迁移操作需要以 admin-only 模式启动服务器,这通过将 --start-mode=admin-only 添加到 server start 命令中来实现:

$ EAP_HOME/bin/standalone.sh --start-mode=admin-only

属性 X 不能使用 OpenJDK ORB 模拟,且不被支持

不支持配置指定属性,并且没有包括在新的 iiop-openjdk 子系统配置中。JBoss EAP 之前版本中此属性所呈现的行为没有迁移,并且管理员必须验证 JBoss EAP 7 中的新 iiop-openjdk 子系统能够在没有该行为的情况下正常运行。

不支持的属性包括: cache-poa-names,cache-typecodes,chunk-custom-rmi-valuetypes,client-timeout,got , indirection-encoding-disable,iona,lax-boolean-encoding,max-managed-buf-size, max-server-connections,max-threads,outbuf-cache-timeout,outbuf-size,queue-max,queue-min,poa-monitoring,print-version,retries,retry-interval, queue-wait,server-timeout,strict-check-on-tc-creation,use-bom,use-imr.

属性 X 使用表达式。用于解析这些表达式的配置属性应该手动转换为新的 iiop-openjdk 子系统格式

管理员必须手动配置使用表达式的属性。

例如,JBoss EAP 6 中的 jacorb 子系统定义了 giop-minor-version 属性。JBoss EAP 7 中的 iiop-openjdk 子系统定义一个 giop-version 属性。假设 jacorb 子系统次要 version 属性设为 ${iiop-giop-minor-version},并且系统属性在 standalone.conf 文件中配置为 -Diiop-giop-minor-version=1迁移操作后,adminstrator 必须将系统属性值更改为 1.1,以确保正确配置了新子系统。

无法迁移:新的 iiop-openjdk 子系统已经定义

消息中包含解释。

A.2. 消息传递子系统迁移操作警告

迁移操作无法处理所有资源和属性。当您为 messaging 子系统运行 migratedescribe-migration 操作,可能会看到包括在以下列表中的警告。

注意

如果您在迁移操作输出中看到 "Could not migrate" 或 "Can not migrate " 条目,这表示成功完成了服务器配置,但无法自动迁移所有元素和属性。您必须遵循"migration-warnings"提供的建议来修改这些配置。

警告信息它代表什么/如何修复它

无法执行 迁移操作:服务器必须处于 仅限管理员 模式

迁移操作需要以 admin-only 模式启动服务器,这通过将 --start-mode=admin-only 添加到 server start 命令中来实现:

$ EAP_HOME/bin/standalone.sh --start-mode=admin-only

无法从资源 X 迁移属性 local-bind-address。改为使用 socket-binding 属性来配置这个 broadcast-group

这个消息包含解释以及如何修复它。

无法从资源 X 迁移属性 local-bind-port。改为使用 socket-binding 属性来配置这个 broadcast-group

这个消息包含解释以及如何修复它。

无法从资源 X 迁移属性 group-address。改为使用 socket-binding 属性来配置这个 broadcast-group

这个消息包含解释以及如何修复它。

无法从资源 X 中迁移属性 group-port。改为使用 socket-binding 属性来配置这个 broadcast-group

broadcast-group 资源不再接受 local-bind-addresslocal-bind-portgroup-addressgroup-port 属性。它仅接受 socket-binding 属性。警告是通知资源 X 具有不支持的属性。您必须在资源上手动设置 socket-binding 属性,并确保它与定义的 socket-binding 资源对应。

提供 X 的类会在迁移期间丢弃。要在新的 messaging-activemq 子系统中使用它们,您必须扩展基于IOMMU 的 Interceptor

在 JBoss EAP 7 中,消息拦截器支持有很大不同。在之前版本的子系统中配置的任何拦截器都会在迁移过程中丢弃。如需更多信息,请参阅迁移消息拦截器

无法迁移 X 的 HA 配置。其 shared-storebackup 属性包含表达式,无法判断不确定如何为 messaging-activemq 的服务器创建对应的 ha-policy

这意味着 hornetq-server Xshared-storebackup 属性包含表达式,如 ${xxx},并且迁移操作无法将其解析为 concrete 表达式。该值将被丢弃,并且必须手动更新 messaging-activemqha-policy

无法从资源 X 迁移属性 local-bind-address。使用 socket-binding 属性来配置此 discovery-group

这个消息包含解释以及如何修复它。

无法从资源 X 迁移属性 local-bind-port。使用 socket-binding 属性来配置此 discovery-group

这个消息包含解释以及如何修复它。

无法从资源 X 迁移属性 group-address。使用 socket-binding 属性来配置此 discovery-group

这个消息包含解释以及如何修复它。

无法从资源 X 中迁移属性 group-port。使用 socket-binding 属性来配置此 discovery-group

discovery-group 资源不再接受 local-bind-addresslocal-bind-portgroup-addressgroup-port 属性。它仅接受 socket-binding。警告是通知资源 X 具有不支持的属性。您必须在资源上手动设置 socket-binding 属性,并确保它与定义的 socket-binding 资源对应。

无法基于 connection-factory X 创建 legacy-connection-factory。它使用一个与在vm in-vm 连接器不兼容的 HornetQ in-vm 连接器

传统的 HornetQ 远程 connection-factory 资源迁移到 legacy-connection-factory 资源,以便 JBoss EAP 6 客户端连接到 JBoss EAP 7。但是,legacy-connection-factory 资源仅在 connection-factory 使用远程连接器时创建。任何使用 in-vmconnection-factory 都不会被迁移,因为 in-vm 客户端基于 JBoss EAP 7,而非 JBoss EAP 6。这个警告是没有迁移 in-vm connection-factory 的通知。

无法从资源 Y 迁移属性 X。属性使用表达式,可以按照系统属性的不同方式解析。迁移后,此属性必须使用实际值而非表达式来重新添加。

当迁移无法将属性 X 在升级过程中解析为 Concrete 值时会出现这个警告。该值被丢弃,必须手动迁移 属性。在以下情况下发生这种情况:

  • cluster-connection forward-when-no-consumers:

    此布尔值属性已被 message-load-balancing-type 属性替代,它是 enum,值为 OFFSTRICTON_DEMAND

  • broadcast-groupdiscovery-group的 's jgroups-stackjgroups-channel 属性

    它们引用了其他资源,JBoss EAP 7 不再接受这些表达式。

无法从资源 Y 迁移属性 X。新的 messaging-activemq 子系统不支持此属性。

新的 messaging-activemq 子系统不再支持一些属性,直接丢弃:

  • hornetq-serverfailback-delay
  • HTTP-connector's use-nio 属性
  • HTTP-acceptor's use-nio 属性
  • remote-connectoruse-nio 属性
  • remote-acceptoruse-nio 属性

无法从资源 X 迁移属性 failedback-delay。runc 可检测到故障恢复的确定性,不再需要指定故障恢复的延迟。

消息中包含解释。

替换 Deprecated broadcast-group 或 discovery-group 属性

如果建议将已弃用的 broadcast-groupdiscovery-group 属性替换为 socket-binding 属性,您可以使用管理 CLI 添加新属性。

本例假设您正在迁移一个单机服务器,该服务器在 messaging 子系统中包含以下 discovery-group 配置:

<discovery-groups>
    <discovery-group name="my-discovery-group">
        <group-address>224.0.1.105</group-address>
        <group-port>56789</group-port>
    </discovery-group>
</discovery-groups>

当您为 messaging 子系统运行迁移操作时,您会看到以下输出和警告:

/subsystem=messaging:migrate
{
    "outcome" => "success",
    "result" => {"migration-warnings" => [
        "WFLYMSG0084: Can not migrate attribute group-address from resource [
    (\"subsystem\" => \"messaging-activemq\"),
    (\"server\" => \"default\"),
    (\"discovery-group\" => \"my-discovery-group\")
]. Use instead the socket-binding attribute to configure this discovery-group.",
        "WFLYMSG0084: Can not migrate attribute group-port from resource [
    (\"subsystem\" => \"messaging-activemq\"),
    (\"server\" => \"default\"),
    (\"discovery-group\" => \"my-discovery-group\")
]. Use instead the socket-binding attribute to configure this discovery-group."
    ]}
}

migrate 操作会在新的 messaging-activemq 子系统中创建一个名为 "my- discovery-group " 的 discovery-group,该组现在配置如下:

<discovery-group name="my-discovery-group"/>

现在,您必须使用以下管理 CLI 命令在服务器配置文件中创建一个名为 "my-discovery-group- socket-binding " 的 socket-binding 元素。

/socket-binding-group=standard-sockets/socket-binding=my-discovery-group-socket-binding:add(multicast-address=224.0.1.105, multicast-port=56789)

接下来,使用下列管理 CLI 命令将新创建的 socket-binding 添加到服务器配置文件中的 messaging-activemq 子系统中名为"my- discovery-group "的 discovery-group。

/subsystem=messaging-activemq/server=default/discovery-group=my-discovery-group:write-attribute(name=socket-binding,value=my-discovery-group-socket-binding)

这些命令在服务器配置文件中创建以下 XML。

<subsystem xmlns="urn:jboss:domain:messaging-activemq:4.0">
    <server name="default">
        ...
        <discovery-group name="my-discovery-group" socket-binding="my-discovery-group-socket-binding"/>
        ...
    </server>
</subsystem>
...
<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
    ...
    <socket-binding name="my-discovery-group-socket-binding" multicast-address="224.0.1.105" multicast-port="56789"/>
    ...
</socket-binding-group>

A.3. Web 子系统迁移操作警告

迁移操作无法处理所有资源和属性。下表列出了您在运行 web 子系统的 migratedescribe-migration 操作时可能会看到的一些警告。

注意

如果您在迁移操作输出中看到 "Could not migrate" 或 "Can not migrate " 条目,这表示成功完成了服务器配置,但无法自动迁移所有元素和属性。您必须遵循"migration-warnings"提供的建议来修改这些配置。

警告信息它代表什么/如何修复它

仅在管理员模式中允许迁移操作

迁移操作需要以 admin-only 模式启动服务器,这通过将 --admin-only 添加到 server start 命令中来实现:

$ EAP_HOME/bin/standalone.sh --admin-only

无法迁移资源 X

JBoss EAP 之前版本中此资源表现出的行为没有迁移。管理员必须验证 JBoss EAP 7 中的新 undertow 子系统能否正确操作,无需该行为,还是必须手动迁移其行为。

无法从资源 Y 迁移属性 X

JBoss EAP 先前版本中此 resource 属性所呈现的行为没有迁移。管理员必须验证 JBoss EAP 7 中的新 undertow 子系统能否正确操作,无需该行为,还是必须手动迁移其行为。

如需未迁移的属性列表,请参阅 Web 子系统迁移操作属性警告

无法迁移 SSL 连接器,因为未定义 SSL 配置

消息中包含解释。

无法将 verify-client 属性 X 迁移到对应的 Undertow 属性

消息中包含解释。

无法迁移 verify-client 表达式 X

消息中包含解释。

无法迁移 valve X

前面版本的 JBoss EAP 出示的行为没有迁移。管理员必须验证 JBoss EAP 7 中的新 undertow 子系统能否正确操作,无需该行为,还是必须手动迁移其行为。

对以下 valves 可能会出现这个警告:

  • org.apache.catalina.valves.RemoteAddrValve

    它必须至少有允许或拒绝的值。

  • org.apache.catalina.valves.RemoteHostValve

    它必须至少有允许或拒绝的值。

  • org.apache.catalina.authenticator.BasicAuthenticator
  • org.apache.catalina.authenticator.DigestAuthenticator
  • org.apache.catalina.authenticator.FormAuthenticator
  • org.apache.catalina.authenticator.SSLAuthenticator
  • org.apache.catalina.authenticator.SpnegoAuthenticator
  • 自定义 valves

无法从 valve Y迁移属性 X

JBoss EAP 先前版本中的 valve 属性显示的行为没有迁移。管理员必须验证 JBoss EAP 7 中的新 undertow 子系统能否正确操作,无需该行为,还是必须手动迁移其行为。以下 valve 属性可能会出现这个警告:

  • org.apache.catalina.valves.AccessLogValve

    • resolveHosts
    • fileDateFormat
    • renameOnRotate
    • encoding
    • locale
    • requestAttributesEnabled
    • buffered
  • org.apache.catalina.valves.ExtendedAccessLogValve

    • resolveHosts
    • fileDateFormat
    • renameOnRotate
    • encoding
    • locale
    • requestAttributesEnabled
    • buffered
  • org.apache.catalina.valves.RemoteIpValve

    • httpServerPort
    • httpsServerPort
    • remoteIpHeader

      如果它被定义但没有设置为 "x-forwarded-for"

    • protocolHeader

      如果定义了,但没有设置为 "x-forwarded-proto"

Web 子系统迁移操作属性警告

迁移操作无法处理所有 JBoss Web 属性。有关如何手动迁移未处理属性的信息,请参见以下参考表。

Web SSL 连接器属性

JBoss EAP 6 中使用以下属性来配置 SSL 连接器。JBoss EAP 7 不支持 openssl 原生库,因此没有对应的设置。

属性描述Undertow Equivalent

ca-revocation-url

包含撤销列表的文件或 URL。

Undertow 中没有等效的。

certificate-file

使用 OpenSSL 加密时,包含服务器证书的文件的路径。

Undertow 中没有等效的。

ssl-protocol

SSL 协议字符串。

Undertow 中没有等效的。

verify-depth

在决定客户端没有有效证书前检查的中间证书签发者的最大数量。

Undertow 中没有等效的。

Web 静态资源属性

以下 static-resources 元素属性用于描述由 DefaultServletWebdavServlet 处理静态资源的方式。这些属性没有等效的,因为 Undertow 不支持 WebDAV。如需更多信息,请参阅 https://issues.jboss.org/browse/JBEAP-1036

属性描述Undertow Equivalent

disabled

启用默认的 Servlet 映射。

Undertow 中没有等效的设置。

file-encoding

读取静态文件时要使用的文件编码。

Undertow 中没有等效的设置。

max-depth

PROPFIND 的最大递归。

Undertow 不支持该 WebDAV 设置和 WebDAV。

只读

允许写入 HTTP 方法(PUT、DELETE)。

Undertow 不支持该 WebDAV 设置和 WebDAV。

secret

WebDAV 锁定操作的机密。

Undertow 不支持该 WebDAV 设置和 WebDAV。

sendfile

如果可能,启用 sendfile,对于大于指定字节大小的文件。

这设置为 Undertow 中的可识别的默认值,不可配置。

webdav

启用 WebDAV 功能。

Undertow 不支持 WebDAV。

Web SSO 资源属性

SSO 的处理方式与上一版本中不同,在 JBoss EAP 7 中没有对应的属性设置。

JBoss Web 属性描述Undertow Equivalent

cache-container

用于集群 SSO 的缓存容器的名称。

Undertow 中不再需要此设置。这在分布式集群环境中默认正常工作。

cache-name

用于集群 SSO 的缓存名称。

Undertow 中不再需要此设置。这在分布式集群环境中默认正常工作。

重新验证

每个请求是否需要重新进行身份验证。

Undertow 中没有对应的设置,它的行为与 JBoss EAP 6 中的 reauthenticate=true 设置相似。在 reauthenticate=false 可能会提高性能时,它也可能会造成安全问题。

Web 访问日志属性
JBoss Web 属性描述Undertow Equivalent

resolve-hosts

是否启用解析主机来访问日志记录。

使用连接器上的 设置来实现相同的行为。

Web Connector 属性
JBoss Web 属性描述Undertow Equivalent

executor

应使用的 executor 名称,用于处理这个连接器的线程。

现在,引用在 io 子系统中定义的 worker。

如需更多信息,请参阅迁移线程子系统配置

proxy-binding

套接字绑定,用于定义发送重定向时使用的主机和端口。

没有直接等效的。

有关可用配置选项,请参阅 JBoss EAP 配置指南中的 https-listener 属性

redirect-port

重定向至安全连接器的端口。

此属性在 JBoss EAP 6 中已弃用,并被 redirect-binding 替代。Undertow 在 http-listener 元素上提供 redirect-socket 属性,这是 redirect-binding 的替代。

如需更多信息,请参阅 JBoss EAP 配置指南中的 https-listener 属性

A.4. 迁移 JBoss Web 系统属性参考

本参考描述了如何将之前用于 JBoss Web 配置的系统属性映射到 JBoss EAP 7 中对 Undertow 的等效配置。

表 A.1. 映射 Servlet 容器和连接器系统属性

JBoss EAP 6 系统属性

描述

等同于 JBoss EAP 7

jvmRoute

jvmRoute 属性提供默认值。在使用 standalone-ha.xml 配置文件时,它不会覆盖自动生成的值。

它支持 重新加载

管理 CLI 命令:

/subsystem=undertow:write-attribute(name=instance-id,value=VALUE)

org.apache.tomcat.util.buf.StringCache.byte.enabled

如果为 true,则会为 ByteChunk 启用字符串缓存。如果没有指定值,则使用默认值 false

没有等效的配置

org.apache.tomcat.util.buf.StringCache.char.enabled

如果为 true,则为 CharChunk 启用字符串缓存。如果没有指定值,则使用默认值 false

没有等效的配置

org.apache.tomcat.util.buf.StringCache.cacheSize

String 缓存的大小。如果没有指定值,则使用默认值 5000

没有等效的配置

org.apache.tomcat.util.buf.StringCache.maxStringSize

将要缓存的 String 的最大长度。如果没有指定值,则使用默认值 128

没有等效的配置

org.apache.tomcat.util.http.FastHttpDateFormat.CACHE_SIZE

使用已解析和格式化的日期值的缓存大小。如果没有指定值,则使用默认值 1000

没有等效的配置

org.apache.catalina.core.StandardService.DELAY_CONNECTOR_STARTUP

如果为 true,则不会自动进行连接器启动。它在嵌入式模式下很有用。

没有等效的配置

org.apache.catalina.connector.Request.SESSION_ID_CHECK

如果为 true,则 Servlet 容器会在创建带有该 ID 的会话之前验证包含指定会话 ID 的上下文中是否存在。

没有等效的配置

org.apache.coyote.USE_CUSTOM_STATUS_MSG_IN_HEADER

如果为 true,在 HTTP 标头中使用自定义 HTTP 状态信息。用户必须确保任何此类消息都是 ISO-8859-1 编码,特别是在消息中包括用户提供的输入时,以防止可能的 XSS 漏洞。如果没有指定值,则使用默认值 false

必须通过实施自定义 io.undertow.servlet.ServletExtension 来以编程方式启用。然后,使用扩展在 io.undertow.servlet.api.DeploymentInfo 结构实例上调用 setSendCustomReasonPhraseOnError(true)

org.apache.tomcat.util.http.Parameters.MAX_COUNT

可以在后正文中解析的最大参数数。如果超过,则使用 IllegalStateException 解析失败。默认值为 512 参数。

管理 CLI 命令:

/subsystem=undertow/server=default-server/http-listener=default:write-attribute(name=max-parameters,value=VALUE)
/subsystem=undertow/server=default-server/https-listener=default:write-attribute(name=max-parameters,value=VALUE)
/subsystem=undertow/server=default-server/ajp-listener=default:write-attribute(name=max-parameters,value=VALUE)

org.apache.tomcat.util.http.MimeHeaders.MAX_COUNT

HTTP 请求中可发送的最大标头数。如果超过,则解析将使用 IllegalStateException 会失败。默认值为 128 标头。

管理 CLI 命令:

/subsystem=undertow/server=default-server/http-listener=default:write-attribute(name=max-headers,value=VALUE)
/subsystem=undertow/server=default-server/https-listener=default:write-attribute(name=max-headers,value=VALUE)
/subsystem=undertow/server=default-server/ajp-listener=default:write-attribute(name=max-headers,value=VALUE)

org.apache.tomcat.util.net.MAX_THREADS

连接器将用于处理请求的最大线程数量。默认值为 32 x 512。(512 x Runtime.getRuntime().availableProcessors() 用于 JIO 连接器)

管理 CLI 命令:

/subsystem=io/worker=default:write-attribute(name=task-max-threads, value=VALUE)

org.apache.coyote.http11.Http11Protocol.MAX_HEADER_SIZE

HTTP 标头的最大大小,以字节为单位。如果超过了,则使用 ArrayOutOfBoundsException 会失败。默认值为 8192 字节。

管理 CLI 命令:

/subsystem=undertow/server=default-server/http-listener=default:write-attribute(name=max-header-size,value=VALUE)
/subsystem=undertow/server=default-server/https-listener=default:write-attribute(name=max-header-size,value=VALUE)
/subsystem=undertow/server=default-server/ajp-listener=default:write-attribute(name=max-header-size,value=VALUE)

org.apache.coyote.http11.Http11Protocol.COMPRESSION

允许通过 HTTP 连接器使用简单的压缩。默认值为 off,可以使用 上的 值启用压缩,以有条件地启用它,或强制始终启用它。

使用管理 CLI 配置过滤器:

# Create a filter
/subsystem=undertow/configuration=filter/gzip=gzipfilter:add()
/subsystem=undertow/server=default-server/host=default-host/filter-ref=gzipfilter:add()

org.apache.coyote.http11.Http11Protocol.COMPRESSION_RESTRICTED_UA

用户代理 regexps 将不会接收压缩内容。默认值为空。

使用管理 CLI 在过滤器中配置 predicate:

# Use a predicate in a filter
/subsystem=undertow/configuration=filter/gzip=gzipfilter:add()
/subsystem=undertow/server=default-server/host=default-host/filter-ref=gzipfilter:add(predicate="regex[pattern='AppleWebKit',value=%{i,User-Agent}]")

org.apache.coyote.http11.Http11Protocol.COMPRESSION_MIME_TYPES

压缩内容的内容类型前缀。默认值为 text/html,text/xml,text/plain

使用管理 CLI 在过滤器中配置 predicate:

# Use a predicate in a filter
/subsystem=undertow/configuration=filter/gzip=gzipfilter:add()
/subsystem=undertow/server=default-server/host=default-host/filter-ref=gzipfilter:add(predicate="regex[pattern='text/html',value=%{o,Content-Type}]")

org.apache.coyote.http11.Http11Protocol.COMPRESSION_MIN_SIZE

将压缩的最小内容大小。默认值为 2048 字节。

使用管理 CLI 在过滤器中配置 predicate:

# Use a predicate in a filter
/subsystem=undertow/configuration=filter/gzip=gzipfilter:add()
/subsystem=undertow/server=default-server/host=default-host/filter-ref=gzipfilter:add(predicate="max-content-size[value=MIN_SIZE]")

org.apache.coyote.http11.DEFAULT_CONNECTION_TIMEOUT

默认套接字超时。默认值为 60000 ms。

管理 CLI 命令:

/subsystem=undertow/server=default-server/http-listener=default:write-attribute(name=no-request-timeout,value=VALUE)
/subsystem=undertow/server=default-server/https-listener=default:write-attribute(name=no-request-timeout,value=VALUE)
/subsystem=undertow/server=default-server/ajp-listener=default:write-attribute(name=no-request-timeout,value=VALUE)

org.jboss.as.web.deployment.DELETE_WORK_DIR_ONCONTEXTDESTROY

使用此属性删除 .java.class 文件,以确保重新编译 JSP 源。默认值为 false。用于 keep-alive 的默认套接字超时。默认值为 -1 ms,这意味着它将使用默认的套接字超时。

没有等效的配置

org.apache.tomcat.util.buf.StringCache.trainThreshold

指定在激活缓存前必须调用 toString() 的次数。默认值为 100000

没有等效的配置

表 A.2. 映射 EL 系统属性

JBoss EAP 6 系统属性

描述

等同于 JBoss EAP 7

org.apache.el.parser.COERCE_TO_ZERO

根据 Expression Language(EL)2.0 规格,如果为 true,则当将表达式与非辅助数据类型、空字符串("")和 null 保持一致时,则为零。如果没有指定值,则使用默认值 true

没有等效的配置。根据 EL 3.0 规格,对于非正式数据类型,空字符串和 null 不会合并为零。

表 A.3. 映射服务器页面系统属性

JBoss EAP 6 系统属性

描述

等同于 JBoss EAP 7

org.apache.jasper.compiler.Generator.VAR_EXPRESSIONFACTORY

用于表达式语言表达式工厂的变量名称。如果没有指定值,则使用默认值 _el_expressionfactory

系统属性尚未更改

org.apache.jasper.compiler.Generator.VAR_INSTANCEMANAGER

用于实例管理器工厂的变量名称。如果没有指定值,则使用默认值 _jsp_instancemanager

系统属性尚未更改

org.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING

如果为 false,则调整 JSP 属性中的转义引号的要求,以便缺少所需的引用引用不会出现错误。如果没有指定值,则使用规格合规默认值 true

系统属性尚未更改

org.apache.jasper.Constants.DEFAULT_TAG_BUFFER_SIZE

任何超过 org.apache.jasper.Constants.DEFAULT_TAG_SIZE 的标签缓冲区都会被销毁,并创建一个新的缓冲区。如果没有指定值,则使用默认值 512

系统属性尚未更改

org.apache.jasper.runtime.JspFactoryImpl.USE_POOL

如果为 true,则使用 ThreadLocal PageContext 池。如果没有指定值,则使用默认值 true

系统属性尚未更改

org.apache.jasper.runtime.JspFactoryImpl.POOL_SIZE

ThreadLocal PageContext 的大小。如果没有指定值,则使用默认值 8

系统属性尚未更改

org.apache.jasper.Constants.JSP_SERVLET_BASE

从 JSP 生成的 Servlet 基础类。如果没有指定值,则使用 org.apache.jasper.runtime.HttpJspBase 默认值。

系统属性尚未更改

org.apache.jasper.Constants.SERVICE_METHOD_NAME

基本类调用的服务方法的名称。如果没有指定值,则使用默认值 _jspService

系统属性尚未更改

org.apache.jasper.Constants.SERVLET_CLASSPATH

为 JSP 提供类路径的 ServletContext 属性的名称。如果没有指定值,则使用 org.apache.catalina.jsp_classpath 的默认值。

系统属性尚未更改

org.apache.jasper.Constants.JSP_FILE

servlet 定义的 <jsp-file> 元素的 request 属性的名称。如果请求存在,这将覆盖 request.getServletPath() 返回的值,以选择要执行的 JSP。如果没有指定值,则使用 org.apache.catalina.jsp_file 的默认值。

系统属性尚未更改

org.apache.jasper.Constants.PRECOMPILE

查询参数的名称,该名称使 JSP 引擎仅预设 servlet,但不调用它。如果没有指定值,则使用 org.apache.catalina.jsp_precompile 的默认值。

系统属性尚未更改

org.apache.jasper.Constants.JSP_PACKAGE_NAME

编译的默认 JSP 软件包名称。如果没有指定值,则使用 org.apache.jsp 的默认值。

系统属性尚未更改

org.apache.jasper.Constants.TAG_FILE_PACKAGE_NAME

从标签文件生成的标签处理程序的默认软件包名称。如果没有指定值,则使用 org.apache.jsp.tag 的默认值。

系统属性尚未更改

org.apache.jasper.Constants.TEMP_VARIABLE_NAME_PREFIX

用于生成的临时变量名称的前缀。如果没有指定值,则使用默认值 _jspx_temp

系统属性尚未更改

org.apache.jasper.Constants.USE_INSTANCE_MANAGER_FOR_TAGS

如果为 true,则使用实例管理器来获取标签处理器实例。如果没有指定值,则使用 true

系统属性尚未更改

org.apache.jasper.Constants.INJECT_TAGS

如果为 true,则标签中指定的注解将进行处理并注入。这在使用简单标签或者标签池时对性能产生影响。如果没有指定值,则使用 false

系统属性尚未更改

表 A.4. 映射安全系统属性

JBoss EAP 6 系统属性

描述

等同于 JBoss EAP 7

org.apache.catalina.connector.RECYCLE_FACADES

如果情况为 true,或者如果正在使用一个安全管理器,则会为每个请求创建一个新的 facade 对象。如果没有指定值,则使用默认值 false

没有等效的配置

org.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH

如果出现这种情况 则允许 '\' 字符作为路径分隔符。如果没有指定值,则使用默认值 false

没有等效的配置

org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH

如果是 true,则允许 '%2F' 和 '%5C' 作为路径分隔符。如果没有指定值,则使用默认值 false

管理 CLI 命令:

/subsystem=undertow/server=default-server/http-listener=default:write-attribute(name=allow-encoded-slash,value=VALUE)
/subsystem=undertow/server=default-server/https-listener=default:write-attribute(name=allow-encoded-slash,value=VALUE)
/subsystem=undertow/server=default-server/ajp-listener=default:write-attribute(name=allow-encoded-slash,value=VALUE)

org.apache.catalina.STRICT_SERVLET_COMPLIANCE

如果没有指定值,则使用 true。如果为 true,则会发生以下操作:任何传递给应用程序分配程序的任何封装请求或响应对象会被检查,以确保其已包装原始请求或响应。(SRV.8.2 / SRV.14.2.5.1)调用 Response.getWriter() 如果没有指定字符编码会导致后续对 Response.getCharacterEncoding() 返回 ISO-8859-1 的调用,Content-Type 响应标头将包含 charset=ISO-8859-1 组件。(SRV.15.2.22.1)与会话相关联的每个请求都会导致更新会话最后一次访问的时间,无论请求是否明确访问会话。(SRV.7.6)

默认合规

org.apache.catalina.core.StandardWrapperValve.SERVLET_STATS

如果为 true,或者如果 org.apache.catalina.STRICT_SERVLET_COMPLIANCE 为 true,则打包程序会收集单个 servlet 的 JSR-77 统计信息。如果没有指定值,则使用默认值 false。此映射安全系统属性等效的 Jakarta 是 Jakarta 管理。

没有等效的配置

org.apache.catalina.session.StandardSession.ACTIVITY_CHECK

如果这是 true,或者 org.apache.catalina.STRICT_SERVLET_COMPLIANCEtrue Tomcat,跟踪每个会话的活动请求数。在决定会话是否有效时,任何至少有一个活跃请求的会话始终被视为有效。如果没有指定值,则使用默认值 false

没有等效的配置

A.5. 版本间的兼容性和互操作性

本节介绍 JBoss EAP 5、JBoss EAP 6 和 JBoss EAP 7 版本之间的客户端和服务器企业级消息传递组件的兼容性和互操作性。

Enterprisean remoting over IIOP

您应该不会在以下任何配置中遇到问题。

  • 从 JBoss EAP 5 客户端连接到 JBoss EAP 7 服务器
  • 从 JBoss EAP 6 客户端连接到 JBoss EAP 7 服务器
  • 从 JBoss EAP 7 客户端连接到 JBoss EAP 6 服务器
  • 从 JBoss EAP 7 客户端连接到 JBoss EAP 5 服务器

使用 Java 命名和目录接口进行企业 Beans

您应该不会在以下任何配置中遇到问题。

  • 从 JBoss EAP 6 客户端连接到 JBoss EAP 7 服务器
  • 从 JBoss EAP 7 客户端连接到 JBoss EAP 6 服务器

JBoss EAP 6 支持 Enterprise Beans 3.1 规格,并引入了使用标准化的全局 Java 命名和目录接口命名空间,它们仍在 JBoss EAP 7 中使用。由于 Java 命名和目录接口命名空间名称的变化,以下配置不兼容:

  • 从 JBoss EAP 5 客户端连接到 JBoss EAP 7 或 JBoss EAP 6 服务器
  • 从 JBoss EAP 7 或 JBoss EAP 6 客户端连接到 JBoss EAP 5 服务器

有关标准化 Java 命名和目录接口命名空间更改的更多信息,请参阅 JBoss EAP 6 迁移指南 中的 Java 命名和目录接口更改

使用 @WebService 进行企业级删除

您应该不会在以下任何配置中遇到问题。

  • 从 JBoss EAP 5 客户端连接到 JBoss EAP 7 服务器
  • 从 JBoss EAP 6 客户端连接到 JBoss EAP 7 服务器
  • 从 JBoss EAP 7 客户端连接到 JBoss EAP 6 服务器
  • 从 JBoss EAP 7 客户端连接到 JBoss EAP 5 服务器

消息传递独立客户端

您应该不会在以下任何配置中遇到问题。

  • 从 JBoss EAP 6 客户端连接到 JBoss EAP 7 服务器
  • 从 JBoss EAP 7 客户端连接到 JBoss EAP 6 服务器

在以下配置中,如果客户端使用特定于消息传递代理的 HornetQ API 而不是通用消息 API,则连接可能。但是,必须使用 JBoss EAP 旧 Java 命名和目录接口命名扩展(随 JBoss EAP 7 一起交付)解决 Java 命名与目录接口查找。

  • 从 JBoss EAP 5 客户端连接到 JBoss EAP 7 服务器

JBoss EAP 7 内置消息传递无法连接 JBoss EAP 5 随附的 HornetQ 2.2.x,因为协议兼容性问题。因此,以下配置不兼容。

  • 从 JBoss EAP 7 客户端连接到 JBoss EAP 5 服务器

消息传递 MDB

您应该不会在以下任何配置中遇到问题。

  • 从 JBoss EAP 6 客户端连接到 JBoss EAP 7 服务器
  • 从 JBoss EAP 7 客户端连接到 JBoss EAP 6 服务器

在以下配置中,如果客户端使用特定于消息传递代理的 HornetQ API 而不是通用 Jakarta Messaging API,则连接可能。但是,必须使用 JBoss EAP 旧 Java 命名和目录接口命名扩展(随 JBoss EAP 7 一起交付)解决 Java 命名与目录接口查找。

  • 从 JBoss EAP 5 客户端连接到 JBoss EAP 7 服务器

JBoss EAP 7 内置消息传递无法连接 JBoss EAP 5 随附的 HornetQ 2.2.x,因为协议兼容性问题。因此,以下配置不兼容。

  • 从 JBoss EAP 7 客户端连接到 JBoss EAP 5 服务器

消息传递桥接

您应该不会在以下任何配置中遇到问题。

  • 从 JBoss EAP 5 客户端连接到 JBoss EAP 7 服务器
  • 从 JBoss EAP 6 客户端连接到 JBoss EAP 7 服务器
  • 从 JBoss EAP 7 客户端连接到 JBoss EAP 6 服务器
  • 从 JBoss EAP 7 客户端连接到 JBoss EAP 5 服务器





更新于 2024-02-09

法律通告

Copyright © 2024 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.