迁移指南

Red Hat JBoss Enterprise Application Platform 7.3

将应用程序从一个主要红帽 JBoss 企业应用平台版本迁移到下一个版本的说明.

摘要

本指南提供有关如何从以前版本的红帽 JBoss 企业应用平台迁移应用的信息。

第 1 章 简介

本指南记录了在红帽 JBoss 企业应用平台 7 上成功运行和部署红帽 JBoss 企业应用平台 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)时,需要进行重大升级或迁移。如果应用遵循 Java 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.3 目录。
  • 如果您使用 RPM 安装方法安装 JBoss EAP,安装目录为 /opt/rh/eap7/root/usr/share/wildfly/
  • 如果您使用安装程序安装 JBoss EAP,EAP _HOME 的默认路径为 ${user.home}/EAP-7.3.0

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

    • 对于红帽企业 Linux: /home/USER_NAME/devstudio/runtimes/jboss-eap/
    • 对于 Microsoft Windows: C:\Users\USER_NAME\devstudio\runtimes\jboss-eapC:\Documents 和 Settings\USER_NAME\devstudio\runtimes\jboss-eap\
注意

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

第 2 章 准备迁移

2.1. 准备概述

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

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

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

2.2. 查看 Java EE 8 功能

Java EE 8 基于 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.Java EE 8 增强功能包括全新的可移植安全 API、支持具有 HTTP/2 支持的 Java Servlet 4.0、JPA 2.2、JAX-RS 2.1、JSF 2.3、CDI 2.0、增强的 JSON 支持和新 JSON 绑定 API、支持异步 CDI 事件等。

您可以在 Oracle 网站上找到有关 Java EE 8 的更多信息,包括教程:Glance 上的 Java EE。

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 的新功能和增强功能

Java EE 7
JBoss EAP 7 是经认证的 Java EE 7 实施,同时满足 Web 配置文件和完整平台规格要求。它还包括对 CDI 1.2 和 WebSockets 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 为 JCA 和数据源提供了稳定且丰富的支持。
JBossWS 5
第五个 JBossWS 是向前发展的重大飞跃,为 JBoss EAP 7 Web 服务带来了新功能和性能改进。
resteasy 3
JBoss EAP 7 包括最新一代的 RESTEasy。它提供许多有用的扩展,如 JSON Web 加密、Jackson、JSON-P 和 Jettison,它超越标准的 Java EE REST API(JAX-RS 2.0)。
OpenJDK ORB
JBoss EAP 7 用 OpenJDK ORB 的下游分支取代了 JacORB IIOP 实施,从而提高了与 JVM ORB 和 Java EE RI 的互操作性。
丰富集群功能
JBoss EAP 7 中大量重构了集群支持,包括多个供应用访问的公共 API。
端口缩减
利用 HTTP 升级,JBoss EAP 7 已经转移了其几乎所有协议,以仅通过两个 HTTP 端口进行多路复用:管理端口(9990)和应用端口(8080)。
增强的日志记录
管理 API 现在支持列出和查看服务器上的可用日志文件,甚至定义默认模式格式器以外的自定义格式器。部署的日志设置也大大增强。

有关 JBoss EAP 7.0 中引入的新功能的完整列表,请参阅 JBoss EAP 7.0.0 发行注记中的新功能 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.0/html-single/7.0.0_release_notes/#release_notes_new_features 和增强功能

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

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

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

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

Java EE 8
JBoss EAP 7.2 是 Java EE 8 认证实施。它包括对 Java Servlet 4.0、Java Persistence 2.2、CDI 2.0、JSF 2.3、JSON-B 1.0、JSON-P 1.1 和 JAX-RS 2.1 等的支持。如需有关 Java 企业版(Java EE)8 平台支持的技术的更多信息,请参阅 Java™ EE 8 技术。
可用于应用程序开发的BOM
提供了一组新的 BOM,为 Java EE 8 提供 JBoss EAP 运行时依赖关系。其中,Java EE 7 BOM 名称包含 javaee7,此版本中的 BOM 现在在其名称中包含 javaee8。如需有关新 BOM 的更多信息,请参阅 JBoss EAP 开发指南中的 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/development_guide/#manage_project_dependencies 管理项目依赖项

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

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

集群
mod_cluster 子系统现在定义一个新属性 initial-loadinitial-load 属性有助于逐渐增加新加入节点的负载值,以避免在加入群集时出现过载。
Eclipse MicroProfile 指标
Eclipse MicroProfile 指标功能为 JBoss EAP 提供监控数据。此发行版本增强了 SmallRye Metrics 组件,以 Prometheus 格式提供 JBoss EAP 指标。
EJB
消息驱动型 Bean(MDB)现在可以属于多个交付组。
Elytron
本发行版本中 的 elytron 子系统现在提供了来自用于容器的 Java Authentication SPI(JASPI)的 Servlet 配置集的实施。Elytron 现在包括增强的 JwtValidator 支持。还包括对 JSR 375 中定义的 Java EE Security API(Security 1.0 API)的支持。此支持的 Jakarta 等效于 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. BOM Artifacts 被替换到 Group ID org.jboss.bom for Jakarta EE 中

旧工件 ID新工件 ID

jboss-eap-javaee8

jboss-eap-jakartaee8

jboss-eap-javaee8-with-spring4

jboss-eap-jakartaee8-with-spring4

jboss-eap-javaee8-with-tools

jboss-eap-jakartaee8-with-tools

有关配置项目依赖项的信息,请参阅开发指南中的管理项目 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/development_guide/#manage_project_dependencies 依赖项

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

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

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

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

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

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

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

EJB实体 Bean
EJB 实体 Bean 不再被支持。如果您的应用使用 EJB 实体 bean,您应该迁移代码以使用 JPA,这可提供性能更高且更灵活的 API。
JAX-RPC
由于 JAX-WS 提供了更加准确、更完整的解决方案,因此应当将为 JAX-RPC 编写的代码迁移到使用 JAX-WS。
JSR-88
Java EE 应用程序部署 API 规范(JSR-88)定义了一项合同,使多个提供商的工具能够在任何 Java EE 平台产品上配置和部署应用程序,但并未广泛采用。您必须使用另一个 JBoss EAP 支持的选项来进行应用部署,如管理控制台、管理 CLI、部署扫描程序或 Maven。
Generic JMS Resource Adapter
不再支持通过配置通用 JMS 资源适配器来连接 JMS 供应商的功能。
IO 子系统
IO 缓冲池已弃用,但它们仍设置为当前版本中的默认设置。如果需要,您可以将 Undertow 字节缓冲区池设置为默认值。
缓存存储
远程 缓存存储已被弃用,而是使用 热路缓存 存储。
平台和功能
先前版本中提供的多个平台和数据库已在 JBoss EAP 7.3 中弃用。

有关 JBoss EAP 7.0 中已弃用和不支持的功能的完整列表,请参阅红帽客户门户上的 JBoss EAP 7.0.0 发行注记中的不受支持和 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.0/html-single/7.0.0_release_notes/#release_notes_unsupported_and_deprecated_functionality 已弃用的功能

有关 JBoss EAP 7.1 中已弃用和不支持的功能的完整列表,请参阅红帽客户门户上的 JBoss EAP 7.1.0 发行注记中的不受支持和 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.1/html-single/7.1.0_release_notes/#unsupported_and_deprecated_functionality 已弃用的功能

有关 JBoss EAP 7.2 中已弃用和不支持的功能的完整列表,请参阅红帽客户门户网站上的 JBoss EAP 7.2.0 发行注记中的不受支持和 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.2/html-single/7.2.0_release_notes/#unsupported_and_deprecated_functionality 已弃用的功能

有关 JBoss EAP 7.3 中已弃用和不支持的功能的完整列表,请参阅红帽客户门户网站上的 JBoss EAP 7.3.0 发行注记中的不受支持和 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/7.3.0_release_notes/#unsupported_and_deprecated_functionality 已弃用的功能

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 版本
  • 与其他红帽应用服务器中间件组件集成
  • 与专有第三方软件集成
  • 使用需要替换的已弃用功能
  • 应用配置,包括部署描述符、JNDI、持久性、JDBC 配置和池、JMS 主题和队列以及日志记录

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

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

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

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

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

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

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

2.9. 迁移 RPM 安装

重要

不支持在单个红帽企业 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.3

JBoss 服务器迁移工具随附 JBoss EAP 7.3,因此无需单独下载或安装。此工具支持从 JBoss EAP 6.4 和更高版本迁移至 JBoss EAP 7.3。您可以通过执行位于 EAP_HOME/bin 目录中的 jboss-server-migration 脚本来运行该工具。有关如何配置和运行该工具的更多信息,请参阅使用 JBoss 服务器迁移工具

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

从 WildFly 迁移到 JBoss EAP

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

重要

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

第 4 章 服务器配置更改

4.1. RPM 安装更改

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

JBoss EAP 7 专为 Software Collections Library 约定而构建。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 迁移 操作来更新 JBoss EAP 6 服务器配置文件中的 jacorb消息传递Web 子系统,以允许它们在新版本上运行,但请注意其结果不是完整的 JBoss EAP 7 配置。例如:

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

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

4.3. 管理 CLI 迁移操作

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

重要

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

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

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

CMP

没有替换

remove

jacorb

iiop-openjdk

migrate

JAXR

没有替换

remove

消息传递

messaging-activemq

migrate

线程

没有替换

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. 执行 迁移 操作,将子系统配置迁移到 JBoss EAP 7 中的替换子系统。该操作使用以下语法:

    /subsystem=SUBSYSTEM_NAME:migrate
    注意

    Messaging 子系统 描述-迁移和迁移 操作,您可以通过参数来配置传统客户端的访问权限。有关命令语法的更多信息,请参阅 Messaging Subsystem Migration 和 Forward Compatibility

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

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

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

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

    示例:使用 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."
        ]}
    }

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

    注意

    您必须使用以下命令为每个 jacorb消息传递web 子系统重复此过程:

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

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

    /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
重要

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

4.4. 日志更改

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

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

有关 JBoss EAP 7 中使用的新日志消息项目代码前缀的完整列表,请参阅 JBoss EAP 开发指南 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/development_guide/#project_codes_used_in_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 子系统配置。

  • 服务器 配置文件中的 Theurn: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 迁移 操作,将 Web 子系统迁移到服务器配置文件中的 undertow。但是,请注意,此操作无法迁移所有 JBoss Web 子系统配置。如果您看到"migration-warning"条目,则必须运行其他管理 CLI 命令将这些配置迁移到 Undertow。如需有关管理 CLI 迁移 操作的更多信息,请参阅 管理 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.3 中默认 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 迁移 操作无法自动迁移重写条件。它们报告为"迁移警告",您必须手动迁移。您可以使用 Undertow Predicates Attributes 和 Handlers 在 JBoss EAP 7 中创建等效的配置。

以下是包含 重写 配置的 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

当您在上述配置上运行 迁移 操作时,将报告以下"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 是插入到应用的请求处理管道中的自定义类,在 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 迁移 操作自动迁移满足以下条件的全局 valves:

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

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

JDBCAccessLogValve Manual Migration Procedure

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 开发指南中的配置 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/development_guide/#configure_the_default_welcome_Web_application 默认欢迎 Web 应用

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

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

  • 服务器,设置为 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.3 中新默认 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> 部分中定义 的公共 接口。

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

4.6.2. JGroups Channels Changes

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

有关如何配置 JGroups 的更多信息,请参阅 JBoss EAP 配置指南中 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/configuration_guide/#cluster_communication_jgroups 的通过 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 支持预先传递,并根据 闲置超时值进行 传递。JBoss EAP 7.1 及更高版本支持放送,在达到 最大大小 阈值时放送。
  • 在 JBoss EAP 7.1 及更高版本中,EJB 客户端使用的集群名称由通道的实际集群名称决定,如 jgroups 子系统中所配置。
  • JBoss EAP 7.1 及更高版本仍允许您设置 max-size 属性来控制传递阈值。
  • 您不应该在 EJB 缓存配置中配置驱除或过期。

    • 您应该通过在 ejb3 子系统中使用 passivation-store 的 max- 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. EJB 服务器配置更改

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

重要

如果您使用 JBoss 服务器迁移工具更新服务器配置,ejb 3 子系统应正确配置,而且部署 EJB 应用时您不应看到任何问题。有关如何配置和运行工具的详情,请参考 使用 JBoss 服务器迁移工具

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.9. 消息传递服务器配置变化

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

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

EAP_HOME/modules/system/layer s/base/ 中的 org.jboss.as.mess aging 模块扩展已被 org.wildfly.extension.messaging-activemq 扩展模块取代。

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

管理模型

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

表 4.3. 映射消息传递属性

HornetQ 名称ActiveMQ 名称 

hornetq-server

server

hornetq-serverType

serverType

连接器

连接器

discovery-group-name

discovery-group

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

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

/subsystem=messaging:migrate

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

/subsystem=messaging:describe-migration

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

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

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

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

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

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

有关正向和向后兼容性的更多信息,请参阅为 JBoss EAP 配置消息传递中的向后和提升 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/configuring_messaging/#messaging_forward_and_backward_compatiblity 兼容性

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

forward-when-no-sumers Attribute 的行为变化

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 配置消息传递 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/configuring_messaging/#cluster_connection_attributes 中的群集连接属性

消息传递子系统 XML 配置

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

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

4.9.2. 迁移消息传递数据

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

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

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

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

重要

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

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

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

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

以下是 HornetQ 导出程序所需的 语法

$ 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 安装目录,再以 管理员模式 启动服务器。

    $ 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 操作:

重要

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

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

    重要

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

  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 安装应用红帽 JBoss 企业应用平台 7.0 更新 05 或较新的累积修补程序,以避免读取大量消息时已知问题。如需更多信息,请参阅 JBEAP-4407 - 在读取导入日志中的大型消息时,使用 IndexOutOfBoundsException 崩溃

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

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

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

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

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

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

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

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

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

  3. 确保 JBoss EAP 6.4 服务器上定义了包含 JMS 消息的 InQueue JMS 队列。
  4. 确保 消息传递 子系统配置包含 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. JMS 网桥配置需要 org.hornetq 模块来连接上一发行版中的 HornetQ 服务器。JBoss EAP 7.x 中不存在此模块及其直接依赖项,因此您必须从上一发行版中复制以下模块:

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

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

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

    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. 创建和部署 JMS 网桥,它将读取来自 JBoss EAP 6.4 服务器上配置的 InQueue JMS 队列的消息,并将它们传输到 JBoss EAP 7.x 服务器上配置的 MigizeMessagesQueue

    /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 配置安全性,您还必须将 JMS 网桥配置 <source> 元素 配置为包含 source-context,以指定在创建连接时要用于 JNDI 查找的正确用户名和密码。
迁移消息传递数据
  1. 验证您为以下配置提供的信息正确无误。

    • 任何队列和主题名称。
    • 用于 JNDI 查找的 java.naming.provider.url
  2. 确保已将目标 JMS 目标部署到 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 Directory NameJBoss EAP 7.x Directory Name

messagingbindings/

activemq/bindings/

messagingjournal/

activemq/journal/

messaginglargemessages/

activemq/largemessages/

messagingpaging/

activemq/paging/

注意

如果没有 大型消息, 或者未禁用分页,则可能会不存在 消息传递大型消息/和消息传递/ 目录。

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. 迁移 JMS Destinations

在 JBoss EAP 6 中,JMS 目的地队列已在 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 中,JMS 目的地队列在 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 中的消息传递拦截器已发生了重大变化,将 HornetQ 替换为 JMS 消息传递提供程序 ActiveMQ Artemis。

之前的 JBoss EAP 版本中包含的 HornetQ 消息传递 子系统要求您安装 HornetQ 拦截器,方法是将它们添加到 JAR 中,然后修改 HornetQ 模块.xml 文件。

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

示例:拦截器配置

<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 传输。由于 ActiveMQ Artemis 取代了 HornetQ 作为 JBoss EAP 7 中的内置消息传递提供程序,因此该配置不再可用。您必须替换 servlet 配置来改用新的内置消息传递 HTTP 连接器和 HTTP 接收器。

4.9.6. 配置通用 JMS 资源适配器

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

4.9.7. 消息传递配置更改

在 JBoss EAP 7.0 中,如果您在 未指定 check- for-live-server 属性的情况下配置了 replication- master 策略,其默认值为 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 序列化行为变化

JMS 1.1 和 JMS 2.0.0 之间更改了 javax.jms.JMSExceptionserialVersionUID。这意味着,如果 JMSException 或其子 类的实例使用 JMS 1.1 进行序列化,它就无法使用 JMS 2.0.0 进行反序列化。反之亦然。如果 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

这个问题已在 JMS 2.0.1 维护版本中解决。

下表详细介绍了 JBoss EAP 的每个发行版本的 JMS 实施。

表 4.4. 每个 JBoss EAP 版本的 JMS 实施

JBoss EAP 版本JMS 实施JMS 版本

6.4

HornetQ

JMS 1.1

7.0

Apache ActiveMQ Artemis

JMS 2.0.0

7.1 及更新的版本

Apache ActiveMQ Artemis

JMS 2.0.1 或更高版本

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

  • 如果您使用 JBoss EAP 6.4 客户端发送包含 JMSException 的消息,将消息传递数据迁移到 JBoss EAP 7.0,然后尝试使用 JBoss EAP 7.0 客户端对该消息进行反序列化,则取消序列化将失败,它将引发异常。这是因为 JMS 1.1 中的 serialVersionUID 与 JMS 2.0.0 中的 不兼容
  • 如果您使用 JBoss EAP 7.0 客户端发送包含 JMSException 的消息,将您的消息传递数据迁移到 JBoss EAP 7.1 或更高版本,然后尝试使用 JBoss EAP 7.1 或更高版本以降序该消息,则反序列化将失败,它将引发异常。这是因为 JMS 2.0.0 中的 serialVersionUID 与 JMS 2.0.1 或更高版本中的 serialVersionUID 不兼容

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

重要

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

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

4.10. JMX 管理更改

JBoss EAP 6 中的 HornetQ 组件提供了自己的 JMX 管理;但是,不建议使用,现在已弃用且不再受支持。如果您依赖 JBoss EAP 6 中的此功能,您必须迁移管理工具,以使用 JBoss EAP 管理 CLI 或 JBoss EAP 7 提供的 JMX 管理工具。

您还必须升级客户端库,以使用 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 Artemis 所需的同等代码示例。

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 JMX object name points to the new JMX 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 扩展模块取代。

服务器 配置文件中的 Theurn: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,您会收到迁移警告。本表中未提及的其他 on/off 属性(如 <security support-ssl="on|off"> )仍受支持,并将成功迁移。唯一的区别在于,它们的值将从 on/off 改为 true/false

表 4.6. 要 Turn Off 或 Remove 的属性

元素设置为 Off 的属性

<orb>

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

<interop>

(除 sun 外的所有内容

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

<poa>

  • 监控
  • queue-wait

4.12. 迁移线程子系统配置

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

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

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

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

在 JBoss EAP 6 中,您通过引用线程子系统中定义的 执行 器,为 Web 子系统的连接器和侦听器配置了 线程 池。在 JBoss EAP 7 中,您现在通过引用在 io 子系统中定义的 工作程序 来配置 undertow 子系统的线程池。如需更多信息,请参阅《JBoss EAP 配置指南 》中的配置 IO 子系统

有关远程 子系统 中线程池配置更改的信息,请参阅本指南中的 删除子系统 配置和 JBoss EAP 配置指南 中的 Endpoint

4.13. 迁移删除子系统配置

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

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

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

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

4.14. Websocket 服务器配置更改

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

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

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

在 JBoss EAP 7 中,您不再需要配置服务器以获取默认的 WebSocket 支持,或者将应用程序配置为使用它。Websocket 是 Java EE 7 规格的一项要求,并且默认配置必要的协议。更复杂的 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 中,如果未提供 Infinispan 缓存,则不会分发缓存。

在 JBoss EAP 7 中,当您选择 HA 配置文件时,SSO 将自动分发。运行 HA 配置文件时,每个主机都有自己的 Infinispan 缓存,它基于 Web 缓存容器的默认缓存。此缓存存储主机的相关会话和 SSO Cookie 信息。JBoss EAP 处理单个缓存信息的传播到所有主机。无法将 Infinispan 缓存专门分配到 JBoss EAP 7 中的 SSO。

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

迁移至 JBoss EAP 7 时 SSO 无需更改应用代码。

4.16. 数据源配置更改

4.16.1. JDBC 数据源驱动程序名称

当您在 JBoss EAP 之前的版本中配置数据源时,为驱动程序名称指定的值取决于 JDBC 驱动程序 JAR 中包含的 META-INF/services/java.sql.Driver 文件中所列的类数。

包含单个类的驱动程序

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

包括多个类的驱动程序

IIN 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_NAME 和 DRIVER_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 安全管理器的情况下运行,您应了解按照策略的定义方式进行了更改,并且可能需要其他配置更改。另请注意,JBoss EAP 7 不支持自定义安全管理器。

有关 Java 安全管理器服务器配置更改的信息,请参阅 如何为 JBoss EAP 配置服务器安全性 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/how_to_configure_server_security/#java-security-manager-migration-considerations 中的从以前的版本移动

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

4.17.1.1. Unreachable LDAP Realms 的 HTTP 状态更改

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

JBoss EAP 7.1 和更高版本中的传统 安全 子系统返回 HTTP 状态代码"500 Internal Error"以更加准确地描述发生了意外状况,导致服务器无法成功处理请求。

4.17.1.2. 启用 LDAP 安全域以从 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 出站连接上引入了一个新的布尔值 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 配置服务器 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/how_to_configure_server_security/#automatic_self_signed_cert_creation 安全性中的自动签署应用证书创建

4.18. 事务子系统更改

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

删除了事务子系统属性

下表列出了从 JBoss EAP 7 中的 transaction 子系统 中删除的 JBoss EAP 6 属性,以及同等的替代属性。

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

路径

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 Subsystem Attributes

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 引入了一个新 的核心管理 子系统,可以进行配置来跟踪对运行中服务器进行的配置更改。这是在 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 CXF、Apache WSS4JApache Santuario 组件升级。

5.1.1. JAX-RPC 支持更改

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

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

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

    <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 文件的存在,该文件包含一个 <service-ref>,该文件引用了 JAX-RPC 映射文件。

5.1.2. Apache CXF Spring Web 服务更改

在之前的 JBoss EAP 版本中,您可以通过将 jbossws-cxf.xml 配置文件与端点部署存档包含 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 替换为 Context Dependency Injection(CDI)。

Apache CXF Interceptors

JBossWS 描述符提供新的配置选项,允许您声明拦截器,而无需修改客户端端点代码。相反,您可以在预定义的客户端和端点配置中声明拦截器,方法是为 cxf.interceptors. in 和 cxf.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

设置连接超时的毫秒数。

cxf.client.receiveTimeout

设置接收超时的毫秒数。

cxf.client.connection

字符串

指定是否使用 Keep-Alive 或 close 连接类型。

cxf.tls-client.disableCNCheck

布尔值

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

5.1.3. WS-安全性变化

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

5.1.4. JBoss 模块结构更改

cxf-apicxf-rt-core JAR 已合并为一个 cxf-core JAR。因此,JBoss EAP 中的 org.apache.cxf 模块现在包含 cxf-core JAR,它提供的类比上一发行版中更多。

5.1.5. 退回 Castle 要求和更改

如果要通过 Galois/Counter Mode(GCM)使用 AES 加密在 XML/WS-Security 中进行对称加密,您需要 BouncyCastle 安全提供商。

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

您可以通过在服务器或 客户端的 jax ws-endpoint-config.xml 部署描述符文件中将 org.jboss.ws.cxf. noLocalBC 属性值设置为 true 来 禁用此行为。

如果要使用不同于 JBoss EAP 附带的版本,您仍然可以将 BouncyCastle 静态安装到 JVM。在这种情况下,静态安装的 BouncyCastle 安全提供程序优先于类路径中存在的提供程序。要避免任何问题,您必须使用 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 的 JAX-WS 2.2 要求

容器必须使用 JAX-WS 2.2 样式构造器(在构造器中包含 WebServiceFeature 类)来构建注入到 Web 服务引用中的客户端。JBoss EAP 6.4 随附 JBossWS 4,隐藏了这一要求。JBoss EAP 7 随附 JBossWS 5,不再隐藏此要求。这意味着,容器注入的服务类必须通过更新现有代码来实施 JAX-WS 2.2 或更高版本,以使用包含一个或多个 Web ServiceFeature 参数的 javax.xml.ws.Service 构造器。

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

5.1.8. IgnoreHttpsHost CN Check Change

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

5.1.9. 服务器幻灯片配置和类加载

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

5.1.10. 弃用 Java Endorsed 标准覆盖机制

Java 终止标准覆盖机制已在 JDK 1.8_40 中弃用,目的是将其删除在 JDK 9 中。这种机制允许开发人员通过将 JAR 放入 JRE 中的认证目录,为所有已部署的应用提供库。

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

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

在之前的 JBoss EAP 发行版中,您可以为 META -INF/ JAR 存档目录中的 EJB Web 服务部署配置 jboss-webservices.xml 部署文件,或者在 WAR 存档目录中的 WEB-INF/ 目录中配置用于 POJO Web 服务部署和 WAR 存档中捆绑的 EJB Web 服务端点的 jboss-webservices.xml 部署文件。

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

5.2. 更新远程 URL 连接器和端口

在 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 迁移操作

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

5.3. 消息传递应用程序变化

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

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

<?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 JMS 部署描述符,您可以将应用转换为使用 Java EE 7 规范的 EE.5.18 节中指定的标准 Java EE 部署描述符,或者您可以更新部署描述符以使用 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. 更新外部 JMS 客户端

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

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

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

如果您计划迁移代码以使用 JMS 2.0 API,请参阅 helloworld-jms 快速入门以了解一个有效的示例。

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-queue s、auto-create-jms-topics 和 auto-delete-jms- topics 属性自动创建和自动删除主题和队列 的功能,在 JBoss EAP 7 中仅部分实施且不可完全配置。这些已弃用的属性仅作为技术预览功能提供且不受支持

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

注意

弃用的属性在 JBoss EAP 7.3 中不再配置此功能,不起作用。不支持替换属性。它们仅以尽力进行迁移的方式提供。

弃用属性替换属性

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

有关这些替换属性的更多信息,请参阅配置消息传递 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/configuring_messaging/#address_setting_attributes 中的地址设置属性

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

从 JBoss EAP 7.2 开始,如果客户端应用直接依赖于 Artemis 客户端 JAR,例如 artemis-jms-client、artemis-commons、artemis-core-clientartemis-selector,那么您必须在 wildfly-client-propertiespom.xml 文件中添加以下依赖项。

<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.3 包含 RESTEasy 3.9.0,这是 JSR 370 中定义的 JAX-RS 2.1 实施,适用于 RESTful Web 服务(JAX-RS 2.1)规范的 Java(TM)API。Jakarta 对 RESTful Web 服务的对等功能在 Jakarta RESTful Web Services 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 已弃用的类

拦截器和消息类

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 兼容拦截器功能所取代。相关的接口在 ja xrs-api 模块的 javax.ws.rs.ext 软件包中定义。

注意

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

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

如需有关新替换 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 中移除或保护。例如,add BuiltInMessageBodyReader()addBuiltInMessageBodyWriter()方法 已被删除,并且 addMessageBodyReader()addMessageBodyWriter()方法 已被保护。

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

其他类从 RESTEasy 3 中删除

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

5.4.3. 其他 RESTEasy 更改

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

@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 用于取消托管的 SnakeYAML 库中存在安全问题,因此不支持使用它,而且必须在应用中明确启用它。有关如何在应用中启用 YAML 提供程序和添加 Maven 依赖项的信息,请参阅为 JBoss EAP 开发 Web 服务应用中的 YAML 提供程序

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

自 JBoss EAP 7.1 起,resteasy.add.charset 参数默认设置为 true。如果您不希望 RESTEasy 将 restarset =UTF-8 添加到返回的 content-type 标头中,当资源方法返回 text/* 或 application/xml* 介质类型而无需显式 charset 时,您可以将 resteasy.add.charset 参数设置为 false

如需有关文本媒体类型和字符集的更多信息,请参阅为 JBoss EAP 开发 Web 服务应用中的 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/developing_web_services_applications/#text_media_types_charsets 文本介质类型和字符集

SerializableProvider

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

将请求与资源方法匹配

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

在 RESTEasy 2 中,即使存在另一个具有相同 URI 的子资源,子资源定位器也能成功执行。根据规范,此行为不正确。

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

以下示例包含子资源 方法上的模糊 @Path 注释和子资源定位器:注意两个端点( anotherResource 和 anotherResource Locator) 的 URI 都相同。这两个端点之间的区别在于,另一个Resource 方法与 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 版本中使用的资源方法匹配算法中发现了一个错误。Final 会导致 RESTEasy 在响应请求时返回太多资源方法。

匹配算法有三个阶段:

  1. 使用请求路径选择可能的资源类。
  2. 使用请求路径选择可能的资源方法。
  3. 使用 HTTP 动词和介质类型(即将推出)选择最终资源方法。

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

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

如果您将 JBoss EAP 服务器从 7.1.0 更新至 7.1.1,并且您想要保留旧行为并将所有潜在资源方法传递给第 3 步,请将 resteasy.loose.step2.request.matching 选项 设置为 true

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

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

5.4.4. RESTEasy SPI 更改

SPI 例外

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

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

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

InjectorFactory 和 Registry

InjectorFactoryRegistry SPI 已改变。如果您使用 RESTEasy(如记录和支持),则不会成为问题。

5.4.5. Jackson 提供程序更改

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 服务应用中切换默认 Jackson 提供程序

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 提供程序更改

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 开发指南中 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/development_guide/#add_an_explicit_module_dependency_to_a_deployment 为部署添加解释模块依赖项

5.4.8. MicroProfile Rest 客户端代码中所需的更改

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.5. CDI 应用程序更改

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

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

Bean 归档

必须将已启用 Bean 类的 Bean 类部署在 bean 存档中,以确保它们被 CDI 扫描以查找和处理 bean 类。

在 CDI 1.0 中,如果某一存档在 META-INF/ 目录中包含用于应用客户端、EJB 或库 JAR 的 beans.xml 文件,或者 WEB-INF/ 目录中包含 beans.xml 文件,则定义为 式 Bean 存档。

CDI 1.1 引入了隐式 Bean 存档,即包含一个或多个 bean 定义注解或一个或多个会话 Bean 类的存档。CDI 会扫描隐式 Bean 存档,并在类型发现过程中仅发现带 bean 定义注解的类。如需更多信息,请参阅 JSR 365 中的 Type 和 Bean Discovery、Java 2.0 的上下文和依赖注入。Jakarta 同等的 bean 定义注解在 Jakarta Context Dependency Injection 2.0 规范中定义。

Bean 存档具有 所有 带注解 或无 Bean 发现 模式。包含 beans.xml 文件(不含任何版本)的 bean 存档具有 所有 版本的默认 Bean 发现模式。包含版本 1.1 或更高版本的 beans.xml 文件的 bean 存档必须指定 bean-discovery-mode 属性。属性的默认值被 标注

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

  • 它包含 beans.xml 文件,bean-discovery-modenone
  • 它包含没有 beans.xml 文件的 CDI 扩展名。

在以下情况下,存档是一个显式 Bean 归档:

  • 归档中包含 beans.xml 文件,版本号为 1.1 或更高版本,并且是 bean-discovery-mode
  • 归档中包含 beans.xml 文件,无版本号。
  • 存档包含一个空的 beans.xml 文件。

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

  • 归档包含一个或多个 bean 类,其中包含 Bean 定义注释,或者一个或多个会话 Bean,即使它不包含 beans.xml 文件。
  • 归档中包含 beans.xml 文件,其 bean-discovery-mode 标注 为。

CDI 1.2 限制为以下定义注解

  • @ApplicationScoped@SessionScoped@ConversationScoped@RequestScoped 注释
  • 所有其他普通范围类型
  • @interceptor@Decorator 注释
  • 所有 stereotype 注释,它们标有 @Stereotype 的注释
  • @depion scope 注解

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

解释对话解析

CDI 1.2 中更改了对话上下文生命周期,以防止与 Servlet 规范冲突,如 CDI 规范 Isue 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 Cookie,您可能需要更新应用代码以提供所需的行为。

5.7. 迁移 Explicit 模块依赖项

在之前的 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 Interceptors 时,您需要生成 Jandex 索引并将其包含在新的 JAR 文件中,然后在 MANIFEST.MFjboss-deployment-structure.xml 部署描述符文件中设置标记。

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

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

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

示例: jboss-deployment-structure.xml 文件中的注解标记

<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 和 JPA 迁移更改

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 3,而无需大量努力,将不会在 JBoss EAP 中使用。如果您无法迁移到 Hibernate ORM 5,您必须为 Hibernate ORM 3 JAR 定义自定义 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 项目,因此 hibernate-infinispan 模块从该发行版本中丢弃。

通过 Hibernate ORM 4.x 编写的应用程序仍然可以使用 Hibernate ORM 4.x。您必须为 Hibernate ORM 4.x JAR 定义自定义 JBoss 模块,并从您的应用程序中排除 Hibernate ORM 5 类。但是,强烈建议您重写应用程序代码以使用 Hibernate ORM 5。有关迁移到 Hibernate ORM 5 的详情,请参考迁移到 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 的 JPA 模式生成 支持.
  • 从 SPI 中删除 JDBC 顾虑以促进 Hibernate OGM 的真正替代品,这是为 NoSQL 数据存储提供 Java Persistence(JPA)支持的持久引擎。

模式管理工具更改只能是直接使用以下任一类的应用程序的迁移问题:

  • 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, String[]) 调用来确定每个 javax.persistence.Entity 是否具有映射的数据库表。这是默认策略,它使用 hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=grouped 属性设置。此策略可能需要提供 hibernate.default_schema 和/或 hibernate.default_catalog

要使用旧策略( 针对每个 javax.persistence.Entity 执行 java.sql.DatabaseMetaData#getTables_metadata_ String, String[]) 调用,请使用 hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=individually 属性设置。

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

JBoss EAP 7.3 包括 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 已被弃用。
  • Session无状态SessionSessionFactory 类层次结构进行了重构,以删除已弃用的类,并更好地与 JPA Metamodel API 保持一致。
  • org. hibernate.persister 和 org .hibernate.tuple 软件包中的 SPI 已改变。任何使用这些 SPI 的自定义类都需要审核和更新。
  • LimitHandler 更改引入了一个新的 hibernate.legacy_limit_handler 设置,默认设置为 false,旨在允许您启用旧的 Hibernate 4.3 限制处理程序行为。这会影响有限的方言列表。
  • 引进了检索数据库表的新策略,提高了 SchemaMigratorSchemaValidator 的性能。
  • 此发行版本更改了使用 PostgreSQL81Dialect 及其子类时注释了 @LobString字符[] 和 Character[] 属性的 CLOB 值。
  • @TableGenerator@SequenceGenerator 名称的范围已从全局更改为 local。

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

Hibernate ORM 5.3 功能

Hibernate ORM 5.3 添加了对 JPA 2.2 规范的支持。这个版本包含与这个规范相符的更改以及其他改进。下表列出了其中一些更改:

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

    • 在 HQL/JPQL 查询中移除对 JDBC 样式参数声明的支持.
    • JPA 位置参数的行为与指定参数更为相似。
    • 本地查询中的 JDBC 样式参数声明使用基于一个参数而非零参数绑定来与 JPA 保持一致。您可以通过将 hibernate.query.sql.jdbc_style_params_base 属性设置为 true 来 恢复到基于零的绑定。
  • 为遵循 JPA 规范,由 @TableGenerator 存储的值存储的序列值是最近生成的值。在以前的版本中,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 统计系统。
  • 某些方法临时添加到 org.hibernate.Query 类中,以便更轻松地将原生应用从 Hibernate ORM 5.1 迁移到 5.3,并维护 Hibernate 5.1 分页行为。这些方法已被弃用,并且可以随 Hibernate 的未来版本一起移植,应用应更新为使用 JPA 方法。
  • 将 Infinispan 用作 Hibernate 2nd 缓存提供程序的支持已移到 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 中找到。
  • 此发行版本中统一了 JPA 和 Hibernate 事件监听程序的本地实施。因此,JpaIntegrator 类已经过时。扩展 org.hibernate.jpa.event.JpaIntegrator 的类必须修改,必须更改这些类来实施 org.hibernate.integrator.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 的本地引导、打包或转换 HibernateException 构建的 SessionFactory 的异常处理。此行为的唯一例外是在操作特定于 Hibernate 时,如 Session.save()Session.saveOrUpdate()。

在 Hibernate 5.3.3 中,添加了 hibernate.native_exception_handling_51_ compliance 属性。此属性指示使用 Hibernate 的原生 bootstrapping 构建的 SessionFactory 的异常处理是否应与 Hibernate ORM 5.1 中的原生异常处理行为相同。如果设置为 true,则HibernateException 不会按照 JPA 规范包装或转换。对于使用 JPA bootstrapping 构建的 SessionFactory,此设置将被忽略。

5.8.5.2. 兼容性转换

JBoss EAP 7.3 包括了一个兼容性转换器,该转换器解决了不再与 Hibernate ORM 5.1 兼容的 Hibernate ORM 5.3 API 方法。转换器是一种临时测量方法,允许使用 Hibernate ORM 5.1 构建的应用在 JBoss EAP 7.3 中展示与 Hibernate 5.3 相同的行为。这是一个临时解决方案,您应该用推荐的 JPA 方法调用替换这些方法调用。

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

  • 您可以通过将 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 搜索 5.5 基于 Apache Lucene 5.3.1 构建。如果您使用任何原生 Lucene API,请务必与这个版本一致。Hibernate Search 5.5 API 打包并隐藏了版本 3 和版本 5 之间进行的许多 Lucene API 更改的复杂性;但是,一些类现已弃用、重命名或重新打包。本节论述了这些更改会如何影响应用程序代码。

Hibernate 搜索映射更改

嵌入式关系的 id 字段索引

在使用 @IndexedEmbedded 注释来包含相关实体的字段时,相关实体的 id 不再包含在内。您可以使用 @Indexed Embedded 注释的 includeEmbeddedObjectId 属性来启用 id 包含

示例: @IndexedEmbedded Annotation

@IndexedEmbedded(includeEmbeddedObjectId=true)

编号和日期索引格式变化

数字和日期现在默认作为数字字段索引。int、longfloat ual及其 对应的 wrapper 类的属性不再被索引为字符串。相反,它们现在使用 Lucene 的相应数字编码进行索引。id 字段是一个规则的例外。即使它们由数字类型表示,默认情况下它们仍然会作为字符串关键字进行索引。@NumericField 的使用现已过时,除非您要为数字编码指定自定义精确度。您可以通过显式指定字符串编码字段桥接来保留旧的基于字符串的索引格式。对于整数,这是 org.hibernate.search.bridge.builtin.IntegerBridge。检查 org.hibernate.search.bridge.builtin 软件包,以查找其他公开可用的字段网桥。

dateCalendar 不再作为字符串索引。相反,实例编码为长值,代表 1970 年 1 月 1 日的毫秒数,即 00:00:00。您可以使用新的 EncodingType 枚举来切换索引格式。例如:

示例: @DateBridge@CalendarBridge Annotation

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

数字和日期的编码变化非常重要,可能会对应用程序行为产生重大影响。如果您的查询以之前字符串编码的字段为目标,但现在以数字编码,则必须更新查询。数字字段必须使用 NumericRangeQuery 进行搜索。您还必须确保通过_cot 为目标的所有字段都经过字符串编码。如果您使用 Search 查询 DSL,则会自动为您创建正确的查询。

其他 Hibernate 搜索更改

  • 排序选项有所改进,对于排序选项,字段编码会错误地指定,从而导致运行时异常。如果事先知道排序中使用的字段,Lucene 还提供了更高性能的排序。Hibernate Search 5.5 提供新的 @SortableField 注释及其多值配套 @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
  • JMS 控制器 API 已经改变。删除了对 Hibernate ORM 的 JMS 后端依赖关系,以便它可以在其他非ORM 环境中使用。因此,org.hibernate.search.backend.impl.jms.AbstractJMSHibernateSearchController 的实现器必须调整为新签名。此类是内部类,建议将它用作示例,而不是进行扩展。
  • org.hibernate.search.spi.ServiceProvider SPI 被重构。如果您与旧服务合同集成,请参阅 ServiceManager、Service Startable 和 Stoppable Hibernate Search 5.5 Javadoc 了解有关新合同的详细信息。
  • 如果您已保留 Lucene 3.x 生成并且尚未使用 Hibernate Search 5.0 或更高版本重新构建的索引,您将获得 IndexFormatTooOldException。建议您使用 massive indexer 重新构建索引。如果您无法做到这一点,请尝试使用 Lucene 的 IndexUpgrader。如果默认行为发生更改,您必须仔细更新 Hibernate Search 映射。如需更多信息,请参阅 Apache Lucene 迁移指南
  • Apache Lucene 在 JBoss EAP 7 中已从 3.6 升级到 5.3。如果您的代码直接导入 Lucene 代码,请参阅 Apache Lucene 迁移指南以了解更改的详情。其他信息也可在 Lucene 更改日志中找到
  • 使用 @Field(indexNullAs=) 对索引中的空标记值进行编码时,标记的类型必须与同一字段中索引的所有其他值兼容。例如,之前可以使用字符串"null"为数字字段编码空值。这已不再被允许。相反,您必须选择一个代表 null 值的数字,如 -1
  • 对面市引擎进行了显著改进。大多数更改不会影响 API。个值得注意的例外是,您必须现在给计划用于遇到 @Facet 或 @Facet s 注释的任何字段添加注解。

Hibernate Search Renamed 和 Repackaged 类

以下是已重新打包或重命名的 Hibernate Search 类的列表。

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

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 - 重新命名和重新打包的类

查询解析器被移到新模块,从 org.apache.lucene.queryParser.QueryParser.QueryParser 改为 org.apache.lucene.queryparser.classic.QueryParser

许多 Lucene 分析器被重构,导致打包更改。请参阅 Apache Lucene 文档来查找替换软件包

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

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

Hibernate Search 弃用 API

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

Hibernate 搜索已弃用接口
Interface描述

org.hibernate.search.store.IndexShardingStrategy

自 Hibernate Search 4.4 弃用.可能会在搜索 5 中删除。改为使用 ShardIdentifierProvider

org.hibernate.search.store.Workspace

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

Hibernate 搜索已弃用的类
class描述

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 Search 已弃用的枚举
enum描述

org.hibernate.search.annotations.FieldCacheType

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

Hibernate Search 已弃用注解
注解描述

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)

Use FuzzyContext.withEditDistanceUpTo(int).

Hibernate Search 已弃用的 Constructors
构造器描述

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

使用 NumericFieldMapping.NumericFieldMapping(String, RolesDescriptor, EntityDescriptor, SearchMapping) 代替。

影响高级集成商的更改

本节论述了不属于公共 API 一部分的更改。它们不应影响平均开发人员,因为这些构件应仅由扩展 Hibernate Search 框架的集成商访问。

5.10. 将实体 Bean 迁移到 JPA

对 EJB 实体 Bean 的支持在 Java EE 7 中是可选的,在 JBoss EAP 7 中不受支持。这意味着,在迁移到 JBoss EAP 7 时,容器管理的持久性(CMP)和 bean 管理的持久性(BMP)实体必须重写为使用 Java Persistence API(JPA)实体。

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

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

以下是 JPA 实体类的示例:

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>

有关 JPA 实体的工作示例,请参见 JBoss EAP 7 附带的 bmt 、cmthibernate5 快速入门。

5.11. JPA Persistence 属性变化

JBoss EAP 7.0 中引入的 JPA Persistence 属性变化

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

jboss.as.jpa.deferdetach 属性控制非 JTA 事务线程中使用的事务范围的持久性上下文是在每次实体 管理器 调用后分离加载的实体,还是等到持久性上下文关闭(例如,会话 bean 调用结束时)。属性值默认为 false,表示每次调用 EntityManager 后将分离或清除实体。这是 JPA 规范中定义的正确默认行为。如果属性值设为 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 中引入的 JPA Persistence 属性变化

在 JBoss EAP 7.0 中,未同步的持久性上下文检查并不像在以下区域中那样严格:

  • 同步容器管理的持久性上下文允许使用与 JTA 事务关联的未同步扩展持久性上下文。相反,它应该抛出 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。它允许应用将与 JTA 事务关联的未同步持久性上下文视为同步的持久性上下文。

5.12. 迁移 EJB 客户端代码

5.12.1. JBoss EAP 7 中的 EJB 客户端变化

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

如果您使用 迁移操作迁移 服务器配置,则会保留旧的设置,您无需进行下面详述的更改。但是,如果您使用新的 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 中的 EJB 客户端库,并且希望连接到 JBoss EAP 7 服务器,那么该服务器必须配置为在端口 8080 之外的端口上公开 远程 连接器。然后,客户端必须使用新配置的连接器进行连接。
  • 使用 JBoss EAP 7 中的 EJB 客户端库并想连接到 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 中引入的其他 EJB 客户端变化

JBoss EAP 7.0 随 JBoss EJB 客户端 2.1.4 附带,而 JBoss EAP 7.1 和更高版本附带了 JBoss EJB Client 4.0.x,其中含有对 API 的许多更改。

  • org.ejb.client.EJBClientInvocationContext 类已添加了下列新方法:

    方法类型描述

    isBlockingCaller()

    布尔值

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

    isClientAsync()

    布尔值

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

    isIdempotent()

    布尔值

    确定该方法是否标记为幂等,这意味着可以多次调用该方法且无额外影响。

    setBlockingCaller(boolean)

    void

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

    setLocator(EJBLocator<T>)

    <T> void

    设置调用目标的定位器。

  • org.ejb.client.EJBLocator 类添加了下列新方法:

    方法类型描述

    asStateful()

    StatefulEJBLocator<T>

    将此定位器返回为有状态定位器(如果是一个定位器)。

    asStateless()

    StatelessEJBLocator<T>

    将此定位器返回为无状态定位器(如果是一个定位器)。

    isEntity()

    布尔值

    确定这是实体定位器。

    isHome()

    布尔值

    确定这是主定位器。

    isStateful()

    布尔值

    确定这是有状态的定位器。

    isStateless()

    布尔值

    确定这是无状态定位器。

    withNewAffinity(Affinity)

    abstract EJBLocator<T>

    创建此定位器的副本,但使用新的给定关联性。

  • 引入了一个新的 org.ejb.client.EJBClientPermission 类,它是 java.security.Permission 的子类,用于控制对特权 EJB 操作的访问权限。

    • 它提供下列构造器:

      • EJBClientPermission(String name)
      • EJBClientPermission(String name, String actions)
    • 它提供下列方法:

      方法类型描述

      equals(EJBClientPermission obj)

      布尔值

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

      等于(Object obj)

      布尔值

      检查两个 权限 对象是否相等。

      等于(Permission obj)

      布尔值

      检查两个 权限 对象是否相等。

      getActions()

      字符串

      以字符串形式返回操作。

      hashcode()

      int

      返回此 Permission 对象的哈希代码值。

      表示(EJBClientPermission 权限)

      布尔值

      检查指定权限的操作是否被 EJBClientPermission 对象的操作 所暗示

      表示(权限权限)

      布尔值

      检查指定权限的操作是否被此权限 对象 的操作 所暗示

  • 引入了一个新的 org.ejb.client.EJBMethodLocator 类,用于查找特定的 EJB 方法。

    • 它提供以下构造器:

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

      方法类型描述

      等于(EJBMethodLocator 其他)

      布尔值

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

      等于(Object other)

      布尔值

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

      forMethod(Method method)

      static EJBMethodLocator

      获取给定猜测方法的方法定位器。

      getMethodName()

      字符串

      获取方法名称。

      getParameterCount()

      int

      获取参数数。

      getParameterTypeName(int index)

      字符串

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

      hashCode()

      int

      获取哈希代码。

  • 在失败的情况下,增加了一个新的 org.jboss.ejb.client.EJBReceiverInvocationContext.ResultProducer.Failed 类。

    • 它提供以下构造器:

      • 失败(Exception 原因)
    • 它提供下列方法:

      方法类型描述

      discardResult()

      void

      丢弃结果,表明它不会被使用。

      getResult()

      对象

      获取结果.

  • 引入了一个新的 org.jboss.ejb.client.EJBReceiverInvocationContext.ResultProducer.Immediate 类以获取即时结果。

    • 它提供以下构造器:

      • 失败(Exception 原因)
    • 它提供下列方法:

      方法类型描述

      discardResult()

      void

      丢弃结果,表明它不会被使用。

      getResult()

      对象

      获取结果.

  • URI 关联性规范引入了一个新的 org.jboss.ejb.client.URIAffinity 类,它是 org.jboss.ejb.client.Affinity 的子类。

    • 它使用 Affinity.forUri(URI) 创建。
    • 它提供下列方法:

      方法类型描述

      等于(相关其他)

      布尔值

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

      等于(Object other)

      布尔值

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

      等于(URIAffinity other)

      布尔值

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

      getURI()

      URI

      获取关联的 URI。

      hashCode()

      int

      获取哈希代码。

      toString()

      字符串

      返回对象的字符串表示。

  • org.jboss.ejb.client.EJBMetaDataImpl 类已弃用了以下方法:

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

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

在 JBoss EAP 7.2 中 org.apache.santuario.xmlsec 模块的升级从 2.0.8 升级到 2.1.1 会导致在 PicketLinkSTS 中重新定向到 PicketLinkSTS 的回归。问题本身作为以下运行时异常来显示:

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 回 车返回的实例,以及 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 回车返回和 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 类以编程方式为 Java EJB 客户端创建新的 InitialContext

示例: jboss-ejb-client.properties 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>

有关如何使用 wildfly-config.xml 文件为 Elytron 客户端配置客户端 身份验证的详情,请参考 如何在如何配置 JBoss EAP 身份管理时使用 Elytron 客户端 配置 客户端身份验证。

有关可以使用 wildfly-config.xml 文件实现的客户端配置类型的更多信息,请参阅 JBoss EAP 开发指南 中的使用 wildfly-config.xml 文件进行客户端配置

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 部署应用,您现在必须使用另一种方法来部署应用。JBoss EAP 管理 CLI 部署命令 提供了一种标准的方式,可将存档部署到单机服务器或受管域中的服务器组。如需有关管理 CLI 的更多信息,请参阅管理 CLI 指南

5.15. 迁移自定义应用程序 Valves

您必须手动迁移 jboss-web.xml XML 文件中定义的自定义 valves 或任何 valve。这包括扩展 org.apache.catalina.valves.ValveBase 类并配置在 jboss-web.xml 描述符文件的 <valve> 元素 中创建的 valves。

重要

jboss-web.xml 文件中定义的自定义 valves 和 valves 必须被对应的 Undertow 内置处理程序重写或替换。有关将 valves 映射到 Undertow 处理程序的信息,请参阅迁移 JBoss Web Valves

必须使用 Undertow 内置身份验证机制手动替换身份验证 valves。

迁移在部署中配置的 Valves

在 JBoss EAP 6 中,您可以通过在 jboss-web.xml Web 应用描述符文件中进行配置,在应用级别上定义自定义 valves。在 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 开发指南中的 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/development_guide/#creating_custom_handler 创建自定义处理程序

迁移自定义身份验证器 Valves

有关如何迁移验证器 valves 的详情,请参考本指南中的迁移验证器 Valves

5.16. 安全应用更改

将 JBoss Web 与 Undertow 替换需要更改 JBoss EAP 7 中的安全配置。

5.16.1. 迁移验证器 Valves

如果您在 JBoss EAP 6.4 中创建了扩展 AuthenticatorBase 的自定义身份验证器 valve,则必须手动将其替换为 JBoss EAP 7 中的自定义 HTTP 身份验证实施。HTTP 身份验证机制在 elytron 子系统中创建,然后注册到 undertow 子系统。有关如何实施自定义 HTTP 身份验证机制的详情,请参阅 JBoss EAP 开发指南中的自定义 HTTP 机制

5.16.3. 其他安全应用更改

有关使用 Kerberos 进行 SSO 配置差异的信息,请参阅配置旧版本 JBoss EAP 中的区别 ,了解如何为 JBoss EAP 设置 SSO

5.17. JBoss 日志更改

如果您的应用使用 JBoss Logging,请注意 org.jboss.logging 软件包中的注解现已在 JBoss EAP 7 中弃用。它们已移到 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. JavaServer Faces (JSF) Code Changes

取消了对 JSF 1.2 的支持

JBoss EAP 6.4 允许您通过创建 jboss-deployment-structure.xml 文件,继续将 JSF 1.2 用于应用程序部署。

JBoss EAP 7.3 包含 JSF 2.3,并且不再支持 JSF 1.2 API。如果您的应用程序使用 JSF 1.2,您必须重写为使用 JSF 2.3。

5.19. 模块类加载更改

在 JBoss EAP 7 中,当多个模块包含相同的类或软件包时,类加载行为发生了变化。

假设 MODULE_AMODULE_B 有两个模块相互依赖,并且包含一些相同的软件包。在 JBoss EAP 6 中,从依赖项加载的类或软件包优先于 module.xml 文件 resource-root 中指定的类或软件包。这意味着 MODULE_A 看到 MODULE_BMODULE_B 的软件包 这个行为令人困惑,并可能导致冲突。JBoss EAP 7 中已更改此行为。现在,由 module.xml 文件中的 resource-root 指定的类或软件包优先于依赖项指定的类或软件包。这意味着 MODULE_A 看到 MODULE_A 和 MODULE _B 的软件包可以看到 MODULE_B 的软件包。这可防止冲突,并提供更合适的行为。

如果您定义的自定义模块包含 resource-root 库 或软件包,这些模块包含模块依赖项中重复的类,您可能会看到 ClassCastException、LinkageError、类加载错误,或者迁移到 JBoss EAP 7 时的行为更改。要解决这些问题,您必须配置 module.xml 文件,以确保只使用一个类版本。这可以通过以下任一方法实现:

  • 您可以避免指定在模块依赖项中重复类的 resource-root
  • 您可以使用导入和 导出 元素的 include exclude 子元素来控制 module.xml 文件中的类加载。以下是排除类在指定软件包中的导出元素:

    <exports>
      <exclude path="com/mycompany/duplicateclassespath/"/>
    </exports>

如果您希望保留现有的行为,您必须使用 filter 元素过滤 module.xml 文件中依赖的 resource-root 中的依赖项软件包。这使您可以保留现有的行为,而无需在 JBoss EAP 6 下看到的奇偶环路。以下是过滤指定软件包 中的类的 root 资源示例。

<resource-root path="mycompany.jar">
  <filter>
    <exclude path="com/mycompany/duplicateclassespath"/>
  </filter>
</resource-root>

如需有关模块和类加载的更多信息,请参阅 JBoss EAP 开发指南中的 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/development_guide/#class_loading_and_modules 类加载和模块

5.20. 应用程序集群更改

5.20.1. 新集群功能概述

下表介绍了将应用从 JBoss EAP 6 迁移到 JBoss EAP 7 时要注意的一些新的集群功能。

  • JBoss EAP 7 引入了新的公共 API,用于构建可显著简化流程的单例服务。有关单例服务的信息,请参阅 JBoss EAP 开发指南中的 HA 单例服务
  • 单例部署可以配置为一次仅在集群中的一个节点上部署和启动。如需更多信息,请参阅 JBoss EAP 开发指南中的 HA 单例部署
  • 现在,您可以定义集群单例 MDB。如需更多信息,请参阅为 JBoss EAP 开发 EJB 应用程序中的集群单例 MDB
  • JBoss EAP 7 包括 Undertow mod_cluster 实施。这提供了不需要 httpd Web 服务器的纯 Java 负载平衡解决方案。如需更多信息,请参阅《JBoss EAP 配置指南 》中的将 JBoss EAP 配置为前端负载平衡器

本节的其余部分将介绍集群更改如何影响应用到 JBoss EAP 7 的迁移。

5.20.2. Web 会话集群更改

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> 的使用。

您可以通过按名称引用会话管理配置文件或提供特定于部署的会话管理配置来覆盖默认的可分布式会话管理行为。如需更多信息,请参阅覆盖默认分布式会话管理行为

下表介绍了如何为 jboss-web.xml 文件中已经过时的元素实现相似的行为。

配置元素更改描述

<max-active-sessions/>

在以前的版本中,如果导致活跃会话的数量超过 <max-active-sessions/> 指定的值,会话创建会失败。

在新实现中,<max-active-sessions/> 用于启用会话引用。如果会话创建将导致活跃会话数超过 <max-active-sessions/>,则会话管理器已知的最旧的会话将传递,以便为新会话腾出空间。

<passivation-config/>

JBoss EAP 7 中不再使用此配置元素及其子元素。

<use-session-passivation/>

在以前的版本中,使用这个属性启用了 passivation。

在新的实现中,通过为 <max-active-sessions/> 指定非负值来启用 passivation

<passivation-min-idle-time/>

在以前的版本中,会话需要在最短时间内处于活跃状态,然后才能成为进行激进的候选者。这可能会导致会话创建失败,即使启用了 passivation 也是如此。

新实施不支持此逻辑,因此避免了这个服务(DoS)漏洞。

<passivation-max-idle-time/>

在以前的版本中,会话将在闲置特定时间后进行传递。

新的实施仅支持松散激进。它不支持预先传递。只有在需要以符合 <max-active-sessions/> 要求时才传递会话。

<replication-config/>

distributable-web 子系统弃用了这个元素。如需更多信息,请参阅分布式 Web 会话配置的 distribut-web 子系统和 覆盖默认分布式会话管理行为

<replication-trigger/>

在以前的版本中,此元素用于决定何时触发会话复制。新的实施将此配置选项替换为单个强大的策略。如需更多信息,请参阅 JBoss EAP 开发指南中 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/development_guide/#immutable_session_attributes 的不可变会话属性

<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/>

在以前的版本中,此属性指定的值定义触发会话事件的策略。

在新的实施中,此行为是规范驱动的,无法配置。

这种新的实施还支持直写缓存存储以及仅传递缓存存储。通常,直写缓存存储与无效缓存结合使用。JBoss EAP 6 中的 Web 会话群集实施在用于无效缓存时无法正确运行。

5.20.3. 覆盖默认的可分布式会话管理行为

您可以使用以下方法之一覆盖默认的 distributable 会话管理行为:

  • 根据名称引用会话管理配置集
  • 提供特定于部署的会话管理配置
引用现有会话管理配置文件
  • 要使用现有的分布式会话管理配置文件,请在应用的 /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>
使用特定于部署的会话管理配置集

如果只有一个 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)启用群集行为:

  • 您可以在会话 bean 中添加 org.jboss.ejb3.annotation.Clustered 注解。

    @Stateful
    @Clustered
    public class MyBean implements MySessionInt {
    
       public void myMethod() {
          //
       }
    }
  • 您可以将 <clustered> 元素添加到 jboss-ejb3.xml 文件中。

    <c:clustering>
      <ejb-name>DDBasedClusteredSFSB</ejb-name>
      <c:clustered>true</c:clustered>
    </c:clustering>

JBoss EAP 7 不再需要您启用群集行为。默认情况下,如果服务器是使用 HA 配置文件启动的,则 SFSB 的状态将自动复制。

您可以使用以下方法之一禁用此默认行为。

  • 您可以使用 @Stateful(passivationCapable=false) 禁用单个有状态会话 Bean 的默认行为,这是 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 和 GroupCommunicationService、GroupMembershipNotifierGroupRpcDispatcher 中的 HAPartition

如需更多信息,请参阅 JBoss EAP 开发指南中的集群 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/development_guide/#public_API_for_clustering-services 服务公共 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 原生版本与过去有所不同。些现在随附新的红帽 JBoss 核心服务产品,这是许多红帽 JBoss 中间件产品常用的补充软件。新产品支持更快速地分发更新和更加一致的更新体验。JBoss Core Services 产品可在红帽客户门户上的不同位置下载。

  • 下表列出了版本之间交付方法的差异。

    软件包JBoss EAP 6JBoss EAP 7

    AIO 消息传递原生

    通过单独的"原生实用程序"下载随产品一起交付

    包括在 JBoss EAP 分发中.无需额外下载。

    Apache HTTP 服务器

    在单独的"Apache HTTP 服务器"下载中随产品一起交付

    随新的 JBoss 核心服务产品一起交付

    mod_cluster, mod_jk, isapi, and nsapi connectors

    通过单独的"Webserver Connector Natives"下载随产品一起交付

    随新的 JBoss 核心服务产品一起交付

    JSVC

    通过单独的"原生实用程序"下载随产品一起交付

    随新的 JBoss 核心服务产品一起交付

    OpenSSL

    通过单独的"原生实用程序"下载随产品一起交付

    随新的 JBoss 核心服务产品一起交付

    tcnatives

    在单独的"原生组件"下载中随产品一起交付

    JBoss EAP 7 中已取消此设置

  • 您还应注意以下更改:

    • 不再支持 mod_cluster 和 mod_jk 连接器,通过红帽企业 Linux RPM 频道与 Apache HTTP 服务器一起使用。如果您从 Red Hat Enterprise Linux RPM 频道运行 Apache HTTP 服务器并需要为 JBoss EAP 7 服务器配置负载平衡,您可以执行以下操作之一:

      • 使用 JBoss 核心服务提供的 Apache HTTP 服务器。
      • 您可以将 JBoss EAP 7 配置为充当前端负载平衡器。如需更多信息,请参阅《JBoss EAP 配置指南 》中的将 JBoss EAP 配置为前端负载平衡器
      • 您可以在受支持和认证的机器上部署 Apache HTTP 服务器,然后在该机器上运行负载均衡器。有关支持的配置列表,请参阅 JBoss EAP 7 配置指南中的 HTTP 连接器概述
  • 您可以在 Apache HTTP 服务器安装指南中找到有关 JBoss 核心服务的更多信息

6.2. Amazon EC2 上部署的更改

对 JBoss EAP 7 中的 Amazon 计算机镜像(AMI)进行了一些更改。本节简要总结了一些更改。

  • 在 Amazon EC2 中启动非集群和群集 JBoss EAP 实例和域的方式发生了显著变化。
  • JBoss EAP 6 将 User Data: 字段用于 JBoss EAP 配置。解析 User Data: 字段中配置并在实例启动时自动启动服务器的 AMI 脚本已从 JBoss EAP 7 中删除。
  • 红帽 JBoss 运营网络代理已在 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-A 和 application- B 的应用,该模块共享由 data-sharing 模块管理的数据。

当您部署此应用程序时,您必须首先部署 共享数据共享 模块,然后部署依赖于它的模块。部署顺序在父 pom.xml 文件的 <modules> 元素 中指定。在 JBoss EAP 6.4 到 JBoss EAP 7.3 中也是如此。

在 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

这个新的 undeploy 行为更为正确,并确保您不会处于不稳定的部署状态。

6.4. JBoss EAP 脚本的更改

由于密码策略更改,JBoss EAP 7 中的 add-user 脚本行为已更改。JBoss EAP 6 具有严格的密码策略。因此,add -user 脚本会拒绝无法满足最低要求的弱密码。在 JBoss EAP 7 中,接受弱密码并发出警告。如需更多信息,请参阅 JBoss EAP 配置指南中的设置 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/configuration_guide/#add_user_password_restrictions 附加用户实用程序密码限制

6.5. 删除 OSGi 支持

在 JBoss EAP 6.0 GA 首次发布时,JBoss OSGi 作为技术预览功能包含在 OSGi 规范的实施中。随着 JBoss EAP 6.1.0 的发布,JBoss OSGi 从技术预览版降级为不受支持。

在 JBoss EAP 6.1.0 中,单机服务器的 configadmin and osgi 扩展模块和子系统配置已移至单独的 EAP_HOME/standalone/configuration/standalone-osgi.xml 配置文件。由于您不应该迁移此不受支持的配置文件,删除 JBoss OSGi 支持不会影响单机服务器配置的迁移。如果您将任何其他独立配置文件修改为 configure osgi 或 configadmin,则必须删除这些配置。

对于受管域,sosgi 扩展和子系统配置已从 JBoss EAP 6.1.0 发行版中的 EAP_HOME/domain/configuration/domain.xml 文件中移除。但是,configadmin 模块扩展和子系统配置仍保留在 EAP_HOME/domain/configuration/domain.xml 文件中。JBoss EAP 7 不再支持此配置,必须删除。

6.6. 对 Java 平台模块系统名称的更改

使用 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 更改

更新用户定义的 SOAP 处理程序,以在迁移至 JBoss EAP 7.3 时遵守 SAAJ 1.4 规范。

由于 JBoss EAP 7.3 附带 SAAJ 1.4,因此为 JBoss EAP 之前版本编写的 SOAP 处理程序(SAAJ 1.3 附带)可能无法正常工作,因为 SAAJ 1.4 和 1.3 规范的差异。有关 SAAJ 1.4 的详情,请参考带有附件的 SOAP

在更新 SOAP 处理程序时,可通过设置系统属性 -Djboss.saaj.api.version=1.3,在 JBoss EAP 7.3 中使用 SAAJ 1.3。更新 SOAP 处理程序后,删除系统属性来恢复默认功能。

6.8. Jakarta EE 的 Maven Artifact 更改

部分 javax Maven 构件已被 JBoss EAP 7.3 的 jakarta Maven 构件取代。

为 JBoss EAP 7.3 构建项目时,您必须使用新的 jakarta Maven 工件更新项目依赖项。不更新项目依赖项将导致构建在为 JBoss EAP 7.3 构建项目时失败。有关管理项目依赖项的信息,请参阅开发指南中的管理项目 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/development_guide/#manage_project_dependencies 依赖项

下表列出了在 JBoss EAP 7.3 中替换的 javax 工件和 jakarta 构件:

表 6.2. javax 工件和 jakarta 工件替换它们

javax artifactJakarta artifact

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 Mail 兼容性的信息,请参阅 Eclipse 维护的兼容性说明

第 7 章 迁移到 Elytron

7.1. Elytron 概述

JBoss EAP 7.1 引入了 Elytron,它提供了一个统一的框架,可以管理和配置单机服务器和受管域的访问权限。它还可用于为部署到 JBoss EAP 服务器的应用配置安全访问。

重要

基于 PicketBox 的 Elytron 和传统安全子系统的架构截然不同。Elytron 曾尝试创建一个解决方案,允许您在当前运行的同一安全环境中运行;然而,这并不表示每个 PicketBox 配置选项在 Elytron 中都有等同的配置选项。

如果您无法在文档中找到信息以帮助您使用旧版安全实施时获得类似功能,则可以通过以下方法之一找到帮助:

使用基于 PicketBox 的传统 安全 子系统的 JBoss EAP 7.0 服务器配置和部署应该无需更改 JBoss EAP 7.1 及之后的版本即可运行。Picketbox 继续支持安全域,允许应用继续使用现有的登录模块。安全域供管理层用于安全性,也被 Elytron 取代和模拟。这样,您可以在 elytron 和旧 安全 子系统中定义身份验证,并并行使用它们。有关如何配置应用以使用 Elytron 和传统安全性的更多信息,请参阅配置 Web 应用以使用 Elytron 或传统安全性以进行身份验证,了解如何为 JBoss EAP 配置身份管理

尽管仍然支持 PicketBox 身份验证,但当您准备好迁移应用程序时,建议您切换到 Elytron。使用 Elytron 安全性的一个优点是它为服务器和您的应用提供了一致的安全解决方案。有关如何将 PicketBox 身份验证和授权迁移到使用 Elytron 的详情,请参考本指南中的迁移身份验证配置

有关 elytron 子系统中提供的新资源的概述,请参阅 JBoss EAP 安全架构 指南 中的 Elytron 子系统 中的资源。

重要

请注意,如果您在部署中同时选择同时使用旧 的安全 子系统和 Elytron,则不支持使用不同安全架构在部署之间调用。

有关并行使用这些子系统的更多信息,请参阅如何在 Parallel 中使用 Elytron 和 Legacy Security Subsystems ,以了解如何为 JBoss EAP 配置身份管理

7.2. 迁移安全 Vault 和属性

7.2.1. 将 Vault 迁移到安全凭证存储

用于在 JBoss EAP 7.0 中的传统 安全 子系统中存储纯文本字符串加密的 vault 与 JBoss EAP 7.1 或更高版本中的 Elytron 不兼容,后者使用新设计的凭据存储来存储字符串。凭据将安全加密凭据存储在 JBoss EAP 配置文件外的存储文件中。您可以使用 Elytron 提供的实现,或者您可以使用凭证存储 API 和 SPI 自定义配置。每个 JBoss EAP 服务器都可以包含多个凭据存储。

注意

如果您之前使用 vault 表达式对非敏感数据进行参数化,建议使用 Elytron 安全属性替换数据

如果您继续使用旧 的安全 子系统,则无需修改或更新密码库数据。但是,如果您计划迁移应用以使用 Elytron,您必须将现有的密码库转换为凭据存储,以便 elytron 子系统可以处理它们。 如需有关凭据存储的更多信息,请参阅如何为 JBoss EAP 配置服务器安全性的凭据存储

使用 WildFly Elytron 工具迁移 Vault 数据

JBoss EAP 附带的 WildFly Elytron 工具提供了一个 vault 命令,可帮助您将 vault 内容迁移到凭据存储中。您可以通过运行位于 EAP_HOME/bin 目录中的 elytron-tool 脚本来执行工具。

$ 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 Tool 无法处理安全库数据文件的第一个版本。
  • 您可以使用屏蔽的格式输入 --keystore-password 参数,如下例所示以迁移单个密码库或明文所示。
  • 提供的 --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 转换为凭证存储,并指向批量转换描述符文件。

本节中的示例使用以下批量转换描述符文件:

示例: quay-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迭代属性外,所有选项均为必填

要执行批量转换并生成格式化管理 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.name 和 encoding. algorithm 安全属性在传统 安全子系统中定义为 安全 属性,如下方 所示:

示例:安全子系统中定义的 安全 属性

<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 子系统中定义相同的安全属性,可使用以下命令设置 elytron 子系统的 security-properties 属性:

/subsystem=elytron:write-attribute(name=security-properties, value={ group.name = "engineering-group", encoding.algorithm = "BASE64" })

这会在服务器配置文件中的 elytron 子系统中配置以下安全漏洞

<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 安全域,并使用 UsersRolesLoginModule 从 example -users.propertiesexample-roles.properties 文件中加载用户信息。这些示例还假定安全性域在传统 安全 子系统中通过下列管理 CLI 命令定义:

示例:基于 PicketBox Properties 的配置命令

/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 安全域扩展到 Elytron 来部分迁移

您可以将 PicketBox 安全域公开为 Elytron 安全域,以便它可以连接到 Elytron 配置中;但是,这样做会创建依赖于旧 安全性 子系统的依赖。如果您仅迁移基于属性的身份验证,建议您 将应用完全迁移到 Elytron,以避免对旧 安全 子系统造成不必要的依赖。但是,当无法完全迁移应用程序以使用 Elytron 时,部分迁移可能是一个中间解决方案。

按照以下步骤,将现有的 PicketBox 安全域配置添加为 Elytron 安全域。

  1. 添加到传统 security 子系统内 Elytron 安全域的映射。

    /subsystem=security/elytron-realm=application-security:add(legacy-jaas-config=application-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 service-Elytron 集成中,为保护 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。此流程假设您从本节介绍中所述的传统配置开始,但没有 ??? 迁移到部分迁移的解决方案。完成此过程后,传统 安全性 子系统中存在的任何安全域定义都将完全独立于 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 service-Elytron 集成中,为保护 Web 服务端点而指定的安全域名称,Elytron 安全域名必须相同。

  4. 您必须重新加载服务器或重新部署应用,才能使新应用安全域映射生效。

现在,身份验证已配置为等同于 PicketBox 配置,但 Elytron 组件现在只用于身份验证。

7.3.1.2. 将基于传统属性的配置迁移到 Elytron

本节论述了如何将传统安全域从属性文件加载用户、密码和组信息到 Elytron。这种类型的传统安全域通常用于保护管理接口或远程连接器的安全。

这些示例假定使用以下管理 CLI 命令定义传统安全域:

示例:传统安全域命令

/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 身份验证的远程连接器,并移除与传统安全域的关联。

    /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)

    这会在服务器配置文件 的远程子系统中产生以下配置

    <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 命令迁移到基于文件系统的安全域

这部分论述了如何使用 elytron.sh 工具的文件系统域将基于属性的安全域迁移到 Elytron.sh 工具的基于文件系统的

基于文件系统的域是基于文件系统的身份存储,供 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

      示例:单一用户属性文件迁移

      $./bin/elytron-tool.sh filesystem-realm --users-file example-users.properties --roles-file example-roles.properties --output-location realms/example

      这将创建文件系统域文件和包含管理 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

      描述符文件中的空行用于分隔每个用户属性文件的操作。

      以下示例将使用描述符文件将含有关联 roles-properties 文件的两个 user-properties 文件转换为 filesystem-realm

      示例:批量迁移

      $./bin/elytron-tool.sh filesystem-realm --bulk-convert example-descriptor-file

      这将创建包含管理 CLI 命令 的文件系统域 文件和脚本。脚本存储在描述符文件的 output-location 属性中指定的目录中。

  2. 将文件系统安全域添加到 Elytron。

    迁移文件后,使用 E lytron 工具生成的 CLI 命令,将新的安全域和安全域添加到 e lytron 子系统。

    示例:添加 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 的"基于 Migrate Properties 的验证和授权 "部分所提供的大部分信息,特别是有关如何定义安全域和身份验证工厂以及如何将它们映射为身份验证使用的信息。本节不重复这些指令,因此请务必通读该部分,然后再继续。

以下示例假定组或角色信息直接从 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 Server Group Entries

    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 属性获取。

  • 使用以下管理 CLI 命令定义与 LDAP 服务器的连接和相关安全域:

    示例: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 属性映射到身份角色。

现在,从 LDAP 加载的信息可以作为属性与身份关联。这些属性可以映射到角色,但它们也可以加载并用于其他用途。新创建的安全域可以在安全域中使用,其方式与本指南基于 Migrate Properties 的验证和授权一节中所述

7.3.4. 将数据库身份验证配置迁移到 Elytron

本节论述了如何将基于 JDBC 数据源的 PicketBox 身份验证迁移到 Elytron。此处应用标题为 Elytron 的"基于 Migrate Properties 的验证和授权 "部分所提供的大部分信息,特别是有关如何定义安全域和身份验证工厂以及如何将它们映射为身份验证使用的信息。本节不重复这些指令,因此请务必通读该部分,然后再继续。

以下示例假定用户身份验证数据存储在使用类似以下示例语法创建的数据库中。

示例:创建数据库用户表的语法

CREATE TABLE User (
    id BIGINT NOT NULL,
    username VARCHAR(255),
    password VARCHAR(255),
    role ENUM('admin', 'manager', 'user'),
    PRIMARY KEY (id),
    UNIQUE (username)
)

出于身份验证目的,用户名与用户名列中存储的数据匹配 密码应当以十六进制编码的 MD5 哈希形式存储在 密码 列中,用于授权目的的用户角色存储在 角色 列中。

PicketBox 安全域配置为使用 JBDC 数据源从数据库表中检索数据,然后使用它来验证用户名和密码,以及分配角色。假定使用下列管理 CLI 命令配置 PicketBox 安全域:

示例:PicketBox Database LoginModule 配置命令

/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 } } ] )

这会在旧 安全 子系统中产生以下 login-module 配置:

示例:PicketBox LoginModule 配置

<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-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})

示例:使用安全域的 Pair 配置

<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 的身份验证和授权小节中
迁移 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 配置的步骤与 Migrate 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. 将复合存储迁移到 Elytron

本节论述了如何将使用多个身份存储的 PicketBox 或旧安全域配置迁移到 Elytron。使用 PicketBox 或传统安全域时,可以定义一个配置,其中将对一个身份存储进行身份验证,而用于授权的信息则从不同的存储加载。迁移到 Elytron 时,这可以通过利用聚合安全域来实现。

以下示例使用 example-users.properties 属性文件执行用户身份验证,然后查询 LDAP 以加载组和角色信息。

注意

显示的配置基于以下部分中的示例,它们提供了额外的背景信息:

Picketbox Composite 存储配置

在这种情况下的 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>

如需了解如何在 e lytron 子系统中配置聚合安全域来完成此操作,请参阅 Elytron Aggregate Security Realm Configuration

传统安全域复合存储配置

此场景的传统安全域配置通过以下管理 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>

如需了解如何在 e lytron 子系统中配置聚合安全域来完成此操作,请参阅 Elytron Aggregate Security Realm Configuration

Elytron Aggregate Security Realm 配置

此场景的等效的 Elytron 配置使用以下管理 CLI 命令进行配置。

示例:Elytron 配置命令

/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 子系统 中,已定义了聚合域,用于指定用于身份验证的安全域以及用于授权决策的安全域。

7.3.7. 将使用 的安全域迁移到 Elytron

使用 PicketBox 时,可以定义安全域并为其访问启用内存中缓存。这允许您访问内存中的身份数据,并避免额外的直接访问身份存储。可以通过 Elytron 实现类似的配置。这部分论述了如何使用 Elytron 配置安全域缓存。

Picketbox 缓存的安全域配置

以下命令显示如何配置启用缓存的 PicketBox 安全域。

示例:PicketBox 缓存的安全域命令

/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 缓存的安全域配置

<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 时,您还可以指定 infinispan 的缓存 类型,但 Elytron 不支持此类型。

Elytron 缓存安全域配置

按照以下步骤创建类似的配置,该配置可在使用 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 域。

    示例:Elytron Security Domain and Authentication Factory Configuration Commands

    /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 缓存的安全域配置

<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. 将 JACC Security 迁移到 Elytron

默认情况下,JBoss EAP 使用传统 安全 子系统来配置容器(JACC)策略提供商和工厂的 Java 授权合同。默认配置映射到 PicketBox 中的实施。

elytron 子系统根据 JACC 规范提供内置策略提供程序。在将服务器配置为允许 Elytron 管理 JACC 配置和其他策略之前,您必须首先使用以下管理 CLI 命令在旧 安全 子系统中禁用 JACC:

/subsystem=security:write-attribute(name=initialize-jacc, value=false)

如果不这样做,可能会导致服务器日志中出现以下错误: MSC000004: Failure 在服务 org.wildfly.security.policy: java.lang.StackOverflowError.

有关如何启用 JACC 并在 elytron 子系统中定义 JACC 策略提供程序的信息,请参阅 JBoss EAP 开发指南 中的 elytron Subsystem 启用 JACC

7.4. 迁移应用程序客户端

7.4.1. 将命名客户端配置迁移到 Elytron

本节论述了如何使用 org.jboss.naming.remote.client.InitialContext 类迁移执行远程 JNDI 查找的客户端应用,该类由 org.jboss.naming.remote.client.InitialContextFactory 类支持。

以下示例假定 InitialContextFactory 类是通过指定用户凭据的属性及其连接的命名提供商的 URL 来创建的。

示例:之前版本中使用的 InitialContext Code

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. 使用配置文件方法迁移命名客户端

按照以下步骤,使用配置方法将您的命名客户端迁移到 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 Code

    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. 使用编程方法迁移命名客户端

使用此方法时,您可以提供用于直接在应用程序代码中建立与命名供应商的连接的用户凭据。

示例:使用编程方法代码

// 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. 将 EJB 客户端迁移到 Elytron

此迁移示例假定客户端应用已配置为使用 jboss-ejb-client.properties 文件调用部署到远程服务器的 EJB。此文件位于客户端应用 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

客户端查找 EJB 并使用类似以下示例的代码调用其中一个方法。

示例:调用远程 EJB 的客户端代码

// 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 EJB 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. 使用配置文件方法迁移 EJB 客户端

按照以下步骤,使用配置方法将您的命名客户端迁移到 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 Code

    // 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 EJB 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. 使用编程方法迁移 EJB 客户端

使用这种方法,您可以提供必要的信息,直接在应用代码中连接到远程服务器。

示例:使用编程方法代码

// 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 EJB
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 EJB 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 中配置了以下密钥存储

示例:使用安全域密钥存储进行 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 子系统中创建 密钥 存储,以指定密钥存储的位置以及加密时使用的密码。此命令假定密钥存储是使用 keytool 命令生成的,其类型为 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 的身份验证强制要求,请删除 本地属性 元素。

可以通过 两种方式使用传统的信任存储

传统 信任存储 仅包含 CA

按照以下步骤配置服务器,以防止没有有效证书和私钥的用户使用 Elytron 访问服务器。

  1. elytron 子系统中创建 密钥 存储,以指定密钥存储的位置以及加密时使用的密码。此命令假定密钥存储是使用 keytool 命令生成的,其类型为 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 子系统中创建 密钥 存储,以指定信任存储的位置以及加密时使用的密码。此命令假定密钥存储是使用 keytool 命令生成的,其类型为 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,以指定之前创建的 truststore 的密钥存储。

    /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>
域和域

为了允许使用预定义的 Elytron ManagementDomain 安全域和 ManagementRealm 安全 域,用户存储在标准属性文件中。

<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>

安全域在两种情形中使用:

  • 证书身份验证失败时,安全域用于密码回退案例。
  • 为密码和证书完成授权后,域提供单个用户的角色。

因此,对于任何客户端证书,安全域中都必须存在用户。

主体解码器

使用证书身份验证并且安全域接受用户名来解析身份时,必须有定义的方式从客户端证书获取 用户名

在这种情况下,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 for Applications 继续添加规则,以帮助您直接从 JBoss EAP 5 迁移到 JBoss EAP 7。您可以使用这些工具分析您的应用,并生成迁移至 JBoss EAP 7 所需更改的详细报告。如需更多信息,请参阅使用 Migration Toolkit for Applications Analyze 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 中所做的最重大更改的精简列表。

  • 实施在模块化服务容器基础上构建的新架构
  • 经过认证的 Java 企业版 6 规格实施
  • 引入了域管理、新部署配置和新文件目录结构和脚本
  • 在新的可移植 JNDI 命名空间上标准化

如需了解该版本中所做更改的详细列表,请参阅 JBoss EAP 6 迁移指南中的 JBoss EAP 6 中的新功能和差异

JBoss EAP 7 构建于与 JBoss EAP 6 相同的模块化结构上,包含相同的域管理、部署配置、文件目录结构和脚本。它还使用相同的标准化 JNDI 命名空间。但是,JBoss EAP 7 引入了下列更改:

  • 添加了对 Java Enterprise Edition 7 规格的支持
  • 将 Web 服务器替换为 Undertow
  • 将 JacORB IIOP 实施替换为 OpenJDK ORB 的下游分支
  • 包含 Apache ActiveMQ Artemis 作为新的消息传递提供程序
  • 删除 cmpjaxr线程 子系统
  • 删除对 EJB 实体 bean 的支持

有关更完整的更改列表,请参阅查看 JBoss EAP 7 中的新功能

8.3. 查看迁移指南中的内容

查看每个发行版本的迁移指南的整个内容,以了解添加或弃用的功能,并了解为该版本运行现有应用程序所需的服务器配置和应用更改。

由于 JBoss EAP 6 和 JBoss EAP 7 之间未更改底层架构,JBoss EAP 6迁移指南中记录的许多更改仍适用例如,大多数应用要求的更改下记录的更改与 JBoss EAP 6 中进行的底层架构更改相关,这些更改仍适用于此版本。对新的模块化类加载系统的更改非常显著,会影响几乎所有 JBoss EAP 5 应用的打包和依赖关系。您的应用程序架构和组件上的 Changes 依赖关系下列出的许多更改仍有效。但是,由于 JBoss EAP 7 取代了 Web 服务器、ORB 和消息传递提供程序,删除了 cmp线程jaxr 子系统,并删除了对 EJB 实体 Bean 的支持,您必须参考本指南来了解与这些组件区域相关的任何更改。在开始之前,请特别注意本指南中详述的服务器配置更改和应用 迁移更改

8.4. JBoss EAP 5 组件升级参考

使用下表查找有关如何将特定功能或组件从 JBoss EAP 5 迁移到 JBoss EAP 7.3 的信息。

JBoss EAP 5
功能或组件
更改概述和
查找迁移信息

应用程序打包和类加载

在 JBoss EAP 6 中,之前分层类加载结构被基于 JBoss 模块的模块化架构取代。应用打包也因为新的模块化类加载结构而改变。JBoss EAP 7 中仍然使用此架构。有关新的模块化架构的信息,请参见 JBoss EAP 7.3 开发指南中的以下章节

有关如何为新模块化架构更新和重新打包应用的详情,请参考 JBoss EAP 6 迁移指南中的以下章节

应用程序配置文件

由于 JBoss EAP 6 中的更改以使用模块化类加载,您可能需要创建或修改一个或多个应用配置文件,以添加依赖项或防止自动加载依赖项。这在 JBoss EAP 7 中没有改变。详情请查看 JBoss EAP 6 迁移指南中的以下章节

缓存和 Infinispan

JBoss 缓存被 Infinispan 取代,仅供服务器在 JBoss EAP 6 中使用。如需有关如何在应用程序代码中替换 JBoss 缓存的信息,请参见 JBoss EAP 6 迁移指南中的以下章节

本指南的以下小节中记录了 JBoss EAP 7 的 Infinispan 缓存策略和配置更改。

数据源和资源适配器

JBoss EAP 6 将数据源和资源适配器配置整合到一个文件中,JBoss EAP 7 中也是如此。如需更多信息,请参见 JBoss EAP 6 迁移指南中的以下章节

目录结构、脚本和部署配置

在 JBoss EAP 6 中,目录结构、脚本和部署配置已更改。这些更改在 JBoss EAP 7 中仍然有效。如需更多信息,请参见 JBoss EAP 6 迁移指南中的以下章节

EJB

Java EE 7 规范使 EJB 2.x 及更早的功能为可选,因此强烈建议您重新编写应用代码以使用 EJB 3.x 规范和 JPA。有关运行 EJB 2.x 所需的弃用功能和更改的信息,请参见 JBoss EAP 6 迁移指南中的以下章节

在 JBoss EAP 6 中,服务器配置文件的 ejb3 子系统中配置有状态 EJB 缓存和无状态会话 Bean 池大小。jboss-ejb3.xml 部署 描述符取代了 jboss.xml 部署 描述符文件。有关这些更改的更多信息,请参见 JBoss EAP 6 迁移指南中的以下章节

JBoss EAP 7 中的默认远程连接器和端口已更改。有关此变化和服务器配置更改的更多信息,请参阅本指南中的以下部分。

JBoss EAP 7 不支持 EJB 实体 bean。有关如何将实体 Bean 迁移到 JPA 的详情,请参考本指南的以下章节。

Hibernate 和 JPA

在 JBoss EAP 6 中,Hibernate 从版本 3 更新至版本 4。此版本的 JBoss EAP 还实施了 JPA 2.0 规范,并对 JPA 持久性属性进行了更改。有关如何为这些更改修改应用的详情,请参考 JBoss EAP 6 迁移指南中的以下章节

JBoss EAP 7.3 实施 JPA 2.2,包括 Hibernate 5.3。它还包括 Hibernate Search 版本 5.10。其他更改包括删除对 EJB 实体 Bean 的支持,以及对 JPA 持久性属性的其他更新。有关这些更改如何影响应用程序的详情,请查看本指南中的以下部分。

注意

不支持使用与 JBoss EAP 附带的不同版本的 Hibernate。JBoss EAP 随附的版本是唯一经过测试的 Hibernate 版本,是提供缺陷补丁的唯一版本。

JAX-RS 和 RESTEasy

JBoss EAP 6 捆绑了 RESTEasy 2,它会自动配置 RESTEasy,需要对应用程序配置进行更改。如需更多信息,请参见 JBoss EAP 6 迁移指南中的以下章节

JBoss EAP 7 包括 RESTEasy 3,许多课程已被弃用。Jackson 的版本从 1.9.9 版变为 2.6.3 或更高版本。有关这些更改的详情,请查看本指南的以下部分。

JBoss AOP

JBoss AOP(面向规格的编程)已在 JBoss EAP 6 中移除。有关如何使用 JBoss AOP 重构应用的详情,请参考 JBoss EAP 6 迁移指南中的以下章节

JGroups 和集群

您启用群集和指定 JBoss EAP 6 中更改的绑定地址的方式.如需更多信息,请参见 JBoss EAP 6 迁移指南中的以下章节

在 JBoss EAP 7 中,JGroups 现在默认为使用专用网络接口而不是公共网络接口,并在 jgroups 子系统中引入 <channel> 元素。JBoss EAP 7 还包含 Undertow mod_cluster 实施,引入了用于构建单例服务的新 API 和其他新的集群功能。这些更改记录在本指南的以下小节中。

JNDI

JBoss EAP 6 实施了新的标准化全局 JNDI 命名空间和一系列相关命名空间,它们映射到 Java EE 应用的不同范围。如需有关使用新 JNDI 命名空间规则所需的应用更改的信息,请参见 JBoss EAP 6 迁移指南中的以下章节

JSF

JBoss EAP 6.4 包含 JSF 1.2 和 JSF 2.1,允许您配置应用以使用较旧版本。这在 JBoss EAP 7.3 中不再可能,现在包括 JSF 2.3。如需更多信息,请参阅本指南中的以下部分。

日志记录

JBoss EAP 6 引入了新的 JBoss 日志框架,仍在 JBoss EAP 7 中使用。使用第三方日志记录框架的应用可能会受到模块化类加载更改的影响。参阅 JBoss EAP 6 迁移指南中的以下章节,以了解有关这些更改的信息。

在 JBoss EAP 7 中,org.jboss.logging 软件包中的注解现已弃用,这将影响源代码和 Maven GAVs(groupId:artifactId:version)。所有日志消息的前缀也已更改。有关这些更改的详情,请查看本指南中的以下部分。

消息传递和 JMS

在 JBoss EAP 6 中,HornetQ 取代了 JBoss Messaging 作为默认的 JMS 实施。在 JBoss EAP 7 中,ActiveMQ Artemis 取代了 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.3 配置指南中的以下小节来应用您当前的 ORB 配置更改。

远程调用

JBoss EAP 6 中引入了一个新的 EJB 客户端 API 用于远程调用;但是,如果您不希望重新编写应用代码以使用新的 API,您可以修改现有代码以使用 ejb:BEAN_REFERENCE 远程访问 EJB。如需更多信息,请参见 JBoss EAP 6 迁移指南中的以下章节

在 JBoss EAP 7 中,默认的连接器和默认远程连接端口已更改。如需更多信息,请参阅本指南中的以下部分。

Seam 2.x

尽管 JBoss EAP 6 中不再提供对 Seam 2.2 应用程序的官方支持,但仍然可以配置 JSF 1.2 和 Hibernate 3 的依赖关系,以允许 Seam 2.2 应用程序在该版本上运行。JBoss EAP 7.3 现已包括 JSF 2.3 和 Hibernate 5.3,由于红帽 JBoss Web 框架工具包生命周期已结束,不支持 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 集成更改的详情,请查看本指南中的以下章节:

事务

JBoss EAP 6 整合了事务配置,并将其移入服务器配置文件。其他更新包括对 JTA 节点标识符设置的更改以及如何启用 JTS。详情请查看 JBoss EAP 6 迁移指南中的以下章节

JBoss EAP 7 中的 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 子系统运行 迁移描述迁移 操作时可能会看到的一些警告:

注意

如果您在迁移操作的输出中看到"Can not migrate"或"Can not migrate "条目,这表示服务器配置迁移成功完成,但无法自动迁移所有元素和属性。您必须遵循"migration-warnings"提供的建议来修改这些配置。

Warning 消息它是什么,如何修复它

当服务器处于 管理模式时,可以执行 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,came t,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 子系统次要版本属性设置为 ${iiop-giop-minor-version},并且 standalone.conf 文件中的系统属性配置为 -Diiop-giop-minor-version=1。在 迁移 操作后,管理员必须将系统属性值更改为 1.1,以确保正确配置了新子系统。

无法迁移:已经定义了新的 iiop-openjdk 子系统

该消息包含说明内容。

A.2. 消息传递子系统迁移操作警告

迁移 操作无法处理所有资源和属性。下表列出了您在运行 messaging 子系统的迁移或 描述 迁移 操作时可能会看到的一些警告。

注意

如果您在迁移操作的输出中看到"Can not migrate"或"Can not migrate "条目,这表示服务器配置迁移成功完成,但无法自动迁移所有元素和属性。您必须遵循"migration-warnings"提供的建议来修改这些配置。

Warning 消息它是什么,如何修复它

无法执行 迁移 操作:服务器必须只处于 管理员模式

迁移 操作需要以 admin-only 模式启动服务器,具体方法是将 --start-mode=admin-only 添加到 server start 命令中:

$ EAP_HOME/bin/standalone.sh --start-mode=admin-only

无法从资源 X 迁移属性 local-bind-address。改为使用 socket-binding 属性来配置此 广播组

该消息包含说明及其修复方法。

无法从资源 X 迁移属性 local-bind-port。改为使用 socket-binding 属性来配置此 广播组

该消息包含说明及其修复方法。

无法从资源 X 迁移属性 group-address。改为使用 socket-binding 属性来配置此 广播组

该消息包含说明及其修复方法。

无法从资源 X 迁移属性 group-port。改为使用 socket-binding 属性来配置此 广播组

broadcast-group 资源不再接受 local-bind-addresslocal-bind-portgroup-addressgroup-port 属性。它仅接受 socket-binding 属性。警告是资源 X 具有不支持的属性的通知。您必须手动设置资源的 socket-binding 属性,并确保它与定义的 socket-binding 资源对应。

迁移期间丢弃提供 X 的类。要在新的 messaging-activemq 子系统中使用它们,您必须扩展基于 Artemis 的 拦截器

在 JBoss EAP 7 中,消息传递拦截器支持有很大不同。迁移期间丢弃在先前版本的子系统中配置的拦截器。如需更多信息,请参阅Migrate Messaging Interceptors

无法迁移 X 的 HA 配置。其 共享存储和 备份 属性包含表达式,因此无法明确地确定如何为 messaging -activemq 服务器创建对应的 ha-policy

这意味着 hornetq-server X共享存储或 备份 属性包含一个表达式,如 ${xxx},迁移操作无法将其解析为具体表达式。该值将被丢弃,并且 messaging- activemq 的 ha- 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。它使用与 Artemis in-vm 连接器不兼容的 HornetQ in-vm 连接器

传统的 HornetQ 远程 connection-factory 资源迁移到 legacy-connection-factory 资源,以允许 JBoss EAP 6 客户端连接到 JBoss EAP 7。但是,只有在 connection-factory 使用远程连接器时才创建 legacy -connection -factory 资源。使用 in-vm 的任何 connection- factory 都不会迁移 ,因为 in-vm 客户端基于 JBoss EAP 7,而非 JBoss EAP 6。此警告是通知 in-vm connection-factory 没有迁移。

无法从资源 Y 迁移属性 X.属性使用表达式,该表达式可以根据系统属性以不同的方式解析。迁移后,必须用实际值而非表达式重新添加此属性。

当迁移过程中无法将属性 X 解析为具体值时会出现这个警告。该值将被丢弃,并且必须手动迁移 属性。在以下情况下会出现这种情况:

  • cluster-connection forward-when-no-consumers:

    此布尔值属性已被 message-load-balancing-type 属性取代,该属性值为 OFF、STRICTON_DEMAND

  • broadcast-groupdiscovery-groupjgroups-stackjgroups-channel 属性

    它们引用其他资源,JBoss EAP 7 不再接受这些表达式。

无法从资源 Y 迁移属性 X.新的 messaging-activemq 子系统不支持此属性。

新的 messaging-activemq 子系统不再支持一些属性,只被丢弃:

  • HornetQ-serverfailback-delay
  • HTTP-connectoruse-nio 属性
  • http-acceptoruse-nio 属性
  • remote-connectoruse-nio 属性
  • remote-acceptoruse-nio 属性

无法从资源 X 中迁移属性 failback-delay。Artemis 检测故障恢复确定性,不再需要指定发生故障恢复的延迟。

该消息包含说明内容。

替换已弃用的广播组或 discovery-group Attributes

如果您建议将已弃用的 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."
    ]}
}

迁移 操作会在新的 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 子系统运行 迁移或 描述迁移 操作时可能会看到的一些警告:

注意

如果您在迁移操作的输出中看到"Can not migrate"或"Can not migrate "条目,这表示服务器配置迁移成功完成,但无法自动迁移所有元素和属性。您必须遵循"migration-warnings"提供的建议来修改这些配置。

Warning 消息它是什么,如何修复它

仅允许在 admin 模式中迁移操作

迁移 操作需要以 admin-only 模式启动服务器,具体方法是在 server start 命令中添加参数 --admin-only

$ EAP_HOME/bin/standalone.sh --admin-only

无法迁移资源 X

此资源在之前的 JBoss EAP 发行版中表现出的行为并未迁移。管理员必须验证 JBoss EAP 7 中的新 undertow 子系统是否能够正确运行而无需该行为,或者确定是否必须手动迁移该行为。

无法从资源 Y 迁移属性 X.

此资源属性在之前的 JBoss EAP 发行版中表现出的行为并未迁移。管理员必须验证 JBoss EAP 7 中的新 undertow 子系统是否能够正确运行而无需该行为,或者确定是否必须手动迁移该行为。

如需未迁移的属性列表,请参阅 Web Subsystem Migration Operation Attribute Warnings

无法迁移 SSL 连接器,因为没有定义 SSL 配置

该消息包含说明内容。

无法将 verify-client 属性 X 迁移到 Undertow 等效

该消息包含说明内容。

无法迁移 verify-client expression X

该消息包含说明内容。

无法迁移 valve X

此 valve 在 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

无法将属性 X 从 valve Y迁出

此 valve 属性在 JBoss EAP 的上一个发行版中表现出的行为并未迁移。管理员必须验证 JBoss EAP 7 中的新 undertow 子系统是否能够正确运行而无需该行为,或者确定是否必须手动迁移该行为。以下 valve 属性可能会发生此警告:

  • org.apache.catalina.valves.AccessLogValve

    • resolveHosts
    • fileDateFormat
    • renameOnRotate
    • 编码
    • locale
    • requestAttributesEnabled
    • Blocked
  • org.apache.catalina.valves.ExtendedAccessLogValve

    • resolveHosts
    • fileDateFormat
    • renameOnRotate
    • 编码
    • locale
    • requestAttributesEnabled
    • Blocked
  • org.apache.catalina.valves.RemoteIpValve

    • httpServerPort
    • httpsServerPort
    • remoteIpHeader

      如果对其进行定义但未设置为"x-forwarded-for"

    • protocolHeader

      如果将其定义为"x-forwarded-proto",则将其设置为"x-forwarded-proto"

Web 子系统迁移操作属性警告

迁移 操作无法处理所有 JBoss Web 属性。有关如何手动迁移未处理的属性的详情,请参考下表。

Web SSL 连接器属性

以下属性在 JBoss EAP 6 中用于配置 SSL 连接器:JBoss EAP 7 不支持 OpenSSL 原生库,因此没有对应的设置。

属性描述Undertow Equient

ca-revocation-url

包含撤销列表的文件或 URL。

Undertow 中没有等效项。

certificate-file

使用 OpenSSL 加密时,包含服务器证书的文件路径。

Undertow 中没有等效项。

ssl-protocol

SSL 协议字符串.

Undertow 中没有等效项。

verify-depth

在决定客户端没有有效证书前检查的中间证书签发者的最大数量。

Undertow 中没有等效项。

Web 静态资源属性

以下 static-resources 元素属性用于描述如何由 DefaultServlet 或 Webdavlet 处理静态资源。这些属性没有等效项,因为 Undertow 不支持 WebDAV。如需更多信息,请参阅 https://issues.jboss.org/browse/JBEAP-1036

属性描述Undertow Equient

disabled

启用默认的 Servlet 映射。

Undertow 中没有等同的设置。

file-encoding

在读取静态文件时要使用的文件编码。

Undertow 中没有等同的设置。

max-depth

PROPFIND 的最大递归数.

这是 WebDAV 设置,Undertow 不支持 WebDAV。

只读

允许写入 HTTP 方法(PUT、DELETE)。

这是 WebDAV 设置,Undertow 不支持 WebDAV。

Secret

WebDAV 锁定操作的机密。

这是 WebDAV 设置,Undertow 不支持 WebDAV。

sendfile

对于大于指定字节大小的文件,如果可能,启用 sendfile。

这在 Undertow 中设置为合理的默认值,且不可配置。

webdav

启用 WebDAV 功能。

Undertow 不支持 WebDAV。

Web SSO 资源属性

SSO 的处理方式与上一发行版不同,JBoss EAP 7 中没有等同的属性设置。

JBoss Web Attribute描述Undertow Equient

cache-container

用于集群 SSO 的缓存容器的名称。

Undertow 中不再需要此设置。这在分布式集群环境中默认有效。

cache-name

用于集群 SSO 的缓存名称。

Undertow 中不再需要此设置。这在分布式集群环境中默认有效。

重新身份验证

每个请求是否应该导致重新身份验证。

Undertow 中没有等效的设置,其行为与 JBoss EAP 6 中的 reauthenticate=true 设置类似。虽然 reauthenticate=false 可能会提高性能,但也可能导致安全问题。

Web 访问日志属性
JBoss Web Attribute描述Undertow Equient

resolve-hosts

是否启用解析主机以用于访问日志记录.

使用连接器上的 设置来完成相同的行为。

Web Connector 属性
JBoss Web Attribute描述Undertow Equient

执行器

应用来处理这个连接器的线程的执行器的名称。

您现在引用了在 io 子系统中定义的 worker。

如需更多信息,请参阅迁移线程子系统配置

proxy-binding

用于定义发送重定向时使用的主机和端口的套接字绑定。

没有直接等效的.

有关可用配置选项,请参阅 JBoss EAP 配置指南 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/configuration_guide/#https_listener_attributes 中的 https-listener 属性

redirect-port

用于重定向至安全连接器的端口。

此属性已在 JBoss EAP 6 中弃用,并替换为 redirect-binding。Undertow 在 http -listener 元素上提供 redirect- socket 属性,它取代 redirect-binding

如需更多信息,请参阅 JBoss EAP 配置指南 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/configuration_guide/#https_listener_attributes 中的 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 启用 String 缓存。如果没有指定值,则使用默认值 false

没有对等的配置

org.apache.tomcat.util.buf.StringCache.char.enabled

如果为 true,则为 CharChunk 启用 String 缓存。如果没有指定值,则使用默认值 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

必须通过实施 custom io.undertow.servlet.ServletExtension 以 编程方式启用。然后,使用扩展来调用 the io.undertow.servlet.api.DeploymentInfo 结构实例上的 setSendCustomReasonPhraseOnError(true )。

org.apache.tomcat.util.http.Parameters.MAX_COUNT

在 post 正文中可以解析的最大参数数。如果超过,解析将使用 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。( 用于 JIO 连接器的512 X Runtime.getRuntime().availableProcessors( ))

管理 CLI 命令:

/subsystem=io/worker=default:write-attribute(name=task-max-threads, value=VALUE)

org.apache.coyote.http11.Http11Protocol.MAX_HEADER_SIZE

HTTP 标头的最大大小,以字节为单位。如果超过,解析将使用 a 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

不接收压缩内容的用户代理正则表达式.默认值为空。

使用管理 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

指定在激活缓存前必须调用 到String() 的次数。默认值为 100000

没有对等的配置

表 A.2. 映射 EL 系统属性

JBoss EAP 6 系统属性

描述

等同于 JBoss EAP 7

org.apache.el.parser.COERCE_TO_ZERO

根据表达式语言(EL)2.0 规范,如果为 true,则当将表达式到非原语数据类型时,空字符串("")和 null 将变为零。如果没有指定值,则使用默认值 true

没有对应的配置。根据 EL 3.0 规范,对于非原语数据类型,空字符串和空字符串不会合并为零。

表 A.3. 映射 JSP 系统属性

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_BUFFER_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 对象,则每个请求都会创建新的 facade 对象。如果没有指定值,则使用默认值 false

没有对等的配置

org.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH

如果这是 true,则允许使用 '\' 字符作为路径分隔符。如果没有指定值,则使用默认值 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 或 if org.apache.catalina.STRICT_SERVLET_COMPLIANCE 为 true,打包程序将收集单个 servlet 的 JSR-77 统计信息。如果没有指定值,则使用默认值 false。此映射安全系统属性的 Jakarta 等效于 Jakarta Management 1.1 规范中。

没有对等的配置

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 版本之间的客户端和服务器 EJB 以及消息传递组件的兼容性和互操作性。

EJB 调整 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 服务器

使用 JNDI 进行 EJB 远程

您不应遇到以下任何配置的问题。

  • 从 JBoss EAP 6 客户端连接到 JBoss EAP 7 服务器
  • 从 JBoss EAP 7 客户端连接到 JBoss EAP 6 服务器

JBoss EAP 6 提供对 EJB 3.1 规范的支持,并引入了标准化的全局 JNDI 命名空间(仍在 JBoss EAP 7 中使用)。由于 JNDI 命名空间名称中的更改,以下配置不兼容:

  • 从 JBoss EAP 5 客户端连接到 JBoss EAP 7 或 JBoss EAP 6 服务器
  • 从 JBoss EAP 7 或 JBoss EAP 6 客户端连接到 JBoss EAP 5 服务器

有关标准化 JNDI 命名空间更改的更多信息,请参阅 JBoss EAP 6 迁移指南中的 JNDI 更改

EJB remoting Using @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,而不是通用 JMS API,则可以进行连接。但是,必须使用随 JBoss EAP 7 提供的 JBoss EAP 传统 JNDI 命名扩展来解决 JNDI 查找。

  • 从 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,而不是通用 JMS API,则可以进行连接。但是,必须使用随 JBoss EAP 7 提供的 JBoss EAP 传统 JNDI 命名扩展来解决 JNDI 查找。

  • 从 JBoss EAP 5 客户端连接到 JBoss EAP 7 服务器

由于协议兼容性问题,JBoss EAP 7 内置消息传递无法连接到 JBoss EAP 5 附带的 HornetQ 2.2.x。因此,以下配置不兼容。

  • 从 JBoss EAP 7 客户端连接到 JBoss EAP 5 服务器

JMS 网桥

您不应遇到以下任何配置的问题。

  • 从 JBoss EAP 5 客户端连接到 JBoss EAP 7 服务器
  • 从 JBoss EAP 6 客户端连接到 JBoss EAP 7 服务器
  • 从 JBoss EAP 7 客户端连接到 JBoss EAP 6 服务器
  • 从 JBoss EAP 7 客户端连接到 JBoss EAP 5 服务器





修订了 2022 年 2 月 16 日 16:44:24 +1000