Red Hat JBoss Enterprise Application Platform 7（JBoss EAP 7）是一个构建在开放标准上并和 Java EE 7 规格兼容的中间件平台。它集成了 WildFly Application Server 10 和高可用性的群集、消息系统以及其他技术。

JBoss EAP 使用了模块化结构，允许在有需要时才启用服务，从而提高了启动速度。

管理控制台和管理命令行界面（Command-line Interface，CLI）使您不需要再编辑 XML 配置文件并增添了使用脚本和自动化任务的能力。

JBoss EAP 提供了两种操作模式：独立服务器和受管域。独立服务器操作模式代表 JBoss EAP 作为单个服务器实例运行。受管域模式则允许通过单个控制点管理多个 JBoss EAP 实例。

此外，JBoss EAP 包含了 API 和开放框架以用于快速开发安全和可扩充的 Java EE 应用程序。

The purpose of this guide is to document the changes that are required to successfully run and deploy Red Hat JBoss Enterprise Application Platform 6 applications on Red Hat JBoss Enterprise Application Platform 7. It provides information about the new features available in this release, the deprecated and unsupported features, and any application and server configuration updates that might be required to prevent changes in application behavior.

It also provides information about tools that can help with the migration, such as Windup, which simplifies migration of Java applications, and the JBoss Server Migration Tool, which updates the server configuration.

Once the application is successfully deployed and running, plans can be made to upgrade individual components to use the new functions and features of JBoss EAP 7.

If you plan to migrate your JBoss EAP 5 applications directly to JBoss EAP 7, see Migrating from Older Releases of JBoss EAP.

在本文档里，我们使用变量 EAP_HOME 来表示 JBoss EAP 的安装位置。请用实际的安装位置替换这个变量。

In JBoss EAP 7, an effort was made to provide backward compatibility for JBoss EAP 6 applications. However, if your application uses features that were deprecated or functionality that was removed from JBoss EAP 7, you might need to make changes to your application code.

In addition, a number of things have changed in this release that might impact deployment of JBoss EAP 7 applications. It is recommended that you do some research and planning before you attempt to migrate your application.

一旦您了解了这些功能的变化、开发内容及可以协助您迁移的工具，您就可以开始评估应用程序和服务器配置来确定在 JBoss EAP 7 里运行所需的修改。

Java EE7 包含了许多使得在私有和公共云上开发和运行功能丰富的应用程序更容易的改进。它合并了新的功能及最新的标准，如 HTML5、WebSocket、JSON、Batch 和 Concurrency Utilities。更新还包含了 JPA 2.1、JAX-RS 2.0、Servlet 3.1、Expression Language 3.0、JMS 2.0. JSF 2.2、EJB 3.2、CDI 1.2 和 Bean Validation 1.1。

您可以在 Oracle 的网站找到关于 Java EE 的更多信息，其中包括教程：Java EE at a Glance。

与之前的版本相比，JBoss EAP 7 包含了显著的升级和改进。

For a complete list of new features, see New Features and Enhancements in the JBoss EAP 7 Release Notes.

Before you migrate your application, be aware that some features that were available in previous releases of JBoss EAP might be deprecated or no longer supported.

由于维护成本高、社区不感兴趣以及更好的替代方案的出现，我们取消了对一些技术的支持。下面是对不再支持的功能的概述。

For a comprehensive list of deprecated and unsupported features, see Unsupported and Deprecated Functionality in the JBoss EAP 7 Release Notes.

Be sure to review the JBoss EAP Getting Started Guide. It contains the following important information:

Each application and server configuration is unique and you must thoroughly understand the components and architecture of the existing application and server platform before you attempt the migration. Your migration plan should include a detailed roadmap for testing and roll out to production that takes into account the following information.

在您迁移应用程序前，您应该意识到下列一些潜在的问题。

在您开始前请确保也备份当前服务器配置和应用程序。

To install JBoss EAP 7 using RPMs, see the JBoss EAP Installation Guide.

The migration advice in this guide also applies to migrating RPM installations of JBoss EAP, but you might need to alter some steps (such as how to start JBoss EAP) to suit an RPM installation compared to a ZIP or installer installation.

If you run JBoss EAP 6 as a service, be sure to review Configuring JBoss EAP to Run as a Service in the JBoss EAP Installation Guide for updated configuration instructions for JBoss EAP 7.

Windup 是 Red Hat JBoss Migration Toolkit 的一部分，它是一个可扩展和定制的基于规则的工具，它有助于简化 Java 应用程序的迁移。它分析要迁移的应用程序使用的 API、技术和架构，并提供详细的迁移报告。这些报告提供了下列信息。

在迁移至 JBoss EAP 7 之前，您可以用 Windup 来分析 JBoss EAP 6 应用程序的代码和架构。Windup 在 XML 描述符里设置从 JBoss EAP 6 迁移到 JBoss EAP 7 的规则以及当迁移至 JBoss EAP 7 时需要替换配置的专有应用程序代码和参数。

For more information about how to use Windup to analyze your JBoss EAP 6 applications, see the Windup User Guide.

目前正开发的 JBoss Server Migration Tool 将是更新您的配置以包含 JBoss EAP 7 里新的功能和设置且保持现有配置的首选方法。

JBoss Server Migration Tool 读取现有的 JBoss EAP 6 服务器配置文件并添加配置至新的子系统、用新的功能更新现有的子系统配置并删除过时的子系统配置。

JBoss Server Migration Tool 的最新预发布版本可以在 https://github.com/wildfly/wildfly-server-migration/releases 下载。这个版本支持从 JBoss EAP 6.4 独立服务器迁移至 JBoss EAP 7.0。关于运行这个工具的常用信息，请参考 《JBoss Server Migration Tool 用户指南》。

要将你的服务器配置从 JBoss EAP 6 到 JBoss EAP 7，您可以使用 JBoss Server Migration Tool 或用管理 CLI 的 migrate 操作进行手动迁移。

JBoss Server Migration Tool

目前正开发的 JBoss Server Migration Tool 将是更新您的配置以包含 JBoss EAP 7 里新的功能和设置且保持现有配置的首选方法。

管理 CLI 的 migrate 操作

您可以使用管理 CLI 的 migrate 操作来更新 JBoss EAP 6 服务器配置文件里的 jacorb、messaging 和 web 子系统，允许它们运行在新版本上，但请注意其结果并非完整的 JBoss EAP 7 配置。例如：

关于使用 migrate 操作来迁移服务器配置的更多信息，请参考管理 CLI 的 migration 操作。

您可以使用管理 CLI 来更新您的 JBoss EAP 6 服务器配置文件以运行在 JBoss EAP 7 上。管理 CLI 提供了 migrate 操作来自动更新之前版本的 jacorb、messaging 和 web 子系统到新配置里。在进行迁移前，您也可以对 jacorb、messaging 和 web 子系统执行 describe-migration 操作来复核配置的改动。目前没有 cmp、jaxr 或 threads 的替代选项，您必须从服务器配置里删除它们。

Start the Server and the Management CLI

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

Migrate the JacORB, Messaging, and Web Subsystems

日志消息用报告该消息的子系统的项目代码作为前缀。JBoss EAP 7 已修改了所有日志消息的前缀。

For a complete list of the new log message project code prefixes used in JBoss EAP 7, see Project Codes Used in JBoss EAP in the JBoss EAP Development Guide.

If you use the management CLI migrate operation to upgrade your existing configuration, you might see exceptions in the server log when you deploy your EJB applications.

DuplicateServiceException

The following DuplicateServiceException is caused by caching changes in JBoss EAP 7.

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

You must reconfigure the cache to resolve this error.

在 JBoss EAP 7 里，ActiveMQ Artemis 作为 JMS 支持提供者替代了 HornetQ。本节描述了如何迁移配置和相关的消息数据。

/subsystem=messaging:migrate

/subsystem=messaging:describe-migration

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

java -jar -mp MODULE_PATH org.hornetq.exporter MESSAGING_BINDINGS_DIRECTORY MESSAGING_JOURNAL_DIRECTORY MESSAGING_PAGING_DIRECTORY MESSAGING_LARGE_MESSAGES_DIRECTORY > OUTPUT_DATA.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>

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

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

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

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.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>

The HornetQ component in JBoss EAP 6 provided its own JMX management; however, it was not recommended and is now deprecated and no longer supported. If you relied on this feature in JBoss EAP 6, you must migrate your management tooling to use either the JBoss EAP management CLI or the JMX management provided with JBoss EAP 7.

You must also upgrade your client libraries to use the jboss-client.jar that ships with JBoss EAP 7.

The following is an example of HornetQ JMX management code that was used in JBoss EAP 6.

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:9999");

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

The following is an example of the equivalent code needed for ActiveMQ Artemis in JBoss EAP 7.

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

Notice that the method names and parameters have changed in the new implementation. You can find the new method names in the JConsole by following these steps.

在 JBoss EAP 7 里 JacORB 实现已用 OpenJDK ORB 的一个下游分支代替。

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

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

下面是 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:1.0">
    <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>

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

下面的 on/off 属性不再被支持，在运行管理 CLI migrate 操作迁移时也不会被迁移。如果它们被设置为 on，您将看到迁移警告。这个表里提及的其他 on/off 属性（如 <security support-ssl="on|off">）仍被支持且可以成功迁移。唯一的区别是它们的值将从 on/off 改为 true/false。

JBoss EAP 6 服务器配置包含了一个 threads 子系统，它用来管理服务器里不同子系统的线程池。

JBoss EAP 7 里不再有 threads 子系统，相反，每个子系统都负责管理自己的线程池。

For information about how to configure thread pools for the infinispan subsystem, see Configure Infinispan Thread Pools in the JBoss EAP Configuration Guide.

For information about how to configure thread pools for the jgroups subsystem, see Configure JGroups Thread Pools in the JBoss EAP Configuration Guide.

In JBoss EAP 6, you configured thread pools for connectors and listeners for the web subsystem by referencing an executor that was defined in the threads subsystem. In JBoss EAP 7, you now configure thread pools for the undertow subsystem by referencing a worker that is defined in the io subsystem. For more information, see Configuring the IO Subsystem in the JBoss EAP Configuration Guide.

For information about about changes to thread pool configuration in the remoting subsystem, see Migrate the Remoting Subsystem Configuration in this guide, and Configuring the Endpoint in the JBoss EAP Configuration Guide.

在 JBoss EAP 6 里，您通过设置 worker-* 属性为 remoting 子系统配置线程池。而 JBoss EAP 7 不再在 remoting 子系统里配置工作节点线程池，如果您试图修改现有的配置，你会看到下面的信息。

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

在 JBoss EAP 7 里，工作节点线程池被引用 io 子系统里定义的 worker 的端点配置所替代。

For information about how to configure the endpoint, see Configuring the Endpoint in the JBoss EAP Configuration Guide.

要在 JBoss EAP 里使用 WebSocket，您需要通过下面的命令行为 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-websockets> 元素并设置其为 true。

在 JBoss EAP 7 里，您不再需要配置服务器默认支持 WebSocket 或配置应用程序使用它。WebSocket 是 Java EE 7 规格所要求的，也是默认配置的必需协议。多数复杂的 WebSocket 配置都是在 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"
   }
}

JBoss EAP 附带的 quickstarts 里也有关于 WebSocket 的代码示例。

The infinispan subsystem still provides distributed caching support for HA services in the form of Infinispan caches in JBoss EAP 7; however the caching and distribution of authentication information is handled differently than in previous releases.

在 JBoss EAP 6 里，如果 Infinispan 缓存没有提供单点登录（SSO），那么这个缓存不能是分布式的。

而在 JBoss EAP 7 里，当您选择 HA 配置集时，SSO 是自动分布的。当用 HA 配置集运行时，每台主机都有自己的基于 Web 缓存容器默认缓存的 Infinispan 缓存。这个缓存存储相关的会话和主机的 SSO cookie 信息。JBoss EAP 处理单独的缓存信息向所有主机的传播。 在 JBoss EAP 7 里无法专门分配某个 Infinispan 缓存给 SSO。

在 JBoss EAP 7 里，SSO 是在服务器配置的 undertow 子系统里进行配置的。

SSO 迁移到 JBoss EAP 7 时不需要修改代码。

For information about Java Security Manager server configuration changes, see Considerations Moving from Previous Versions in How To Configure Server Security for JBoss EAP.

JBoss EAP 6 的 transactions 子系统里的一些事务管理者配置属性在 JBoss EAP 7 里进行了修改。

Removed Transactions Subsystem Attributes

下表列出了JBoss EAP 7 里删除的 JBoss EAP 6 transactions 子系统属性及其替代属性。

已舍弃的 Transactions 子系统属性

The following attributes that were available in the transactions subsystem in JBoss EAP 6 are deprecated in JBoss EAP 7. The deprecated attributes might be removed in a future release of the product. The following table lists the equivalent replacement attributes.

JBoss EAP 7 已修改了 mod_cluster 里的静态代理列表的配置。

在 JBoss EAP 6 里，您会配置 proxy-list 属性，它是一个用逗号隔开的格式为 hostname:port 的 HTTPS 代理地址列表。

JBoss EAP 7 里已舍弃了 proxy-list 属性。它被作为转出套接字绑定名称列表的 proxies 属性替代。

This change impacts how you define a static proxy list, for example, when disabling advertising for mod_cluster. For information about how to disable advertising for mod_cluster, see Disable Advertising for mod_cluster in the JBoss EAP Configuration Guide.

For more information about mod_cluster attributes, see ModCluster Subsystem Attributes in the JBoss EAP Configuration Guide.

JBossWS 5 为 JBoss EAP 7 Web Services 带来了新的功能和性能改进，这主要是通过升级 Apache CXF、Apache WSS4J 和 Apache Santuario 完成的。

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

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

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);
...

在 JBoss EAP 7 里，默认的连接器已从 remote 改为 http-remoting，且默认的远程连接端口已从 4447 改为 8080。默认配置的 JNDI 供应商 URL 已从 remote://localhost:4447 改为 http-remoting://localhost:8080。

If you use the JBoss EAP 7 migrate operation to update your configuration, you do not need to modify the remote connector, remote port, or JNDI provider URLs because the migration operation preserves the JBoss EAP 6 remoting connector and 4447 port configuration settings in the subsystem configuration. For more information about the migrate operation, see Management CLI Migration Operation.

如果您没有使用 migrate 操作而用新的 JBoss EAP 7 默认配置来运行，你必须修改远程连接、远程端口以及 JNDI 供应商 URL 来使用上述新的设置。

之前的 JBoss EAP 版本捆绑了实现 JAX-RS 1.x 的 RESTEasy 2。JBoss EAP 7 附带实现 JAX-RS 2.0（由 JSR 339: JAX-RS 2.0: The Java API for RESTful Web Services 规格定义）的 RESTEasy 3。关于用于 RESTful Web Service 的 Java API 的更多信息，请参考 JAX-RS 2.0 API 规格。

JBoss EAP 7 里包含的 Jackson 版本已有改变。之前的 JBoss EAP 包含的是 Jackson 1.9.9，而 JBoss EAP 7 现在包含 Jackson 2.6.3 或更高的版本。

This section describes how these changes might impact applications that use RESTEasy or JAX-RS.

<?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 7 includes support for CDI 1.2. As a result, applications written using CDI 1.0 might see some changes in behavior when migrated to JBoss EAP 7. This section summarizes only a few of those changes.

您可以在下列引用里找到关于 Weld 和 CDI 1.2 的更多信息：

Bean 归档

已启用的 bean 的 Bean 类必须部署在 bean 归档里以确保被 CDI 扫描并发现和处理 bean 类。

在 CDI 1.0 里，对于应用程序客户、EJB 或库 JAR，如果归档的 META-INF/ 目录包含了 beans.xml，或者是 WAR 的 WEB-INF/ 目录包含了 beans.xml 文件，这个就被定义为显性的 bean 归档。

CDI 1.1 引入了隐性的 bean 归档，也就是包含一个或多个带有 bean 定义注解 bean 类或者会话 bean 的归档。隐性的 bean 归档会被 CDI 扫描，在类型发现过程中，只有带有 bean 定义注解的类会被发现。详情请参考Java EE 平台的上下文和依赖关系注入里的类型和 Bean 的发现。

Bean 归档具有 all、annotated 或 none 发现模式。包含不带版本的 beans.xml 文件的 bean 归档的默认发现模式是 all。包含 1.1 或更高版本的 beans.xml 文件的 bean 归档必须指定 bean-discovery-mode 属性。这个属性的默认值是 annotated。

在下列情况下归档不是 Bean 归档：

在下列情况下归档是显性的 Bean 归档：

在下列情况下归档是隐性的 Bean 归档：

CDI 1.2 将 bean 定义注解限制为：

关于 Bean 归档的更多信息，请参考Java EE 平台的上下文和依赖关系注入里的 Bean 归档。

会话解析（Conversation Resolution）的说明

会话上下文生命周期已被修改以防止和 CDI Specification Issue CDI-411 里描述的 Servlet 规格冲突。会话作用域在所有 Servlet 请求期间都时是活动的，它不应该阻止其他 Serlet 或 Servlet 过滤器设置请求主体或字符编码。

Observer 解析

CDI 1.2 已部分地重写了事件解析（Event resolution）。在 CDI 1.0 里，如果一个 observer 方法具有所有的事件限定符，事件将被递送给它。在 CDI 1.2 里，如果一个 observer 方法没有事件限定符或只有一个子集，事件将被递送给它。

之前 JBoss EAP 版本里引入模块化类加载系统和 JBoss Modules 允许对应用程序可用的类进行细颗粒度的控制。这个功能允许您用应用程序的 MANIFEST.MF 或 jboss-deployment-structure.xml 部署描述符文件配置显性的模块依赖关系。

如果您在应用程序里定义了显性的模块依赖关系，您应该意识到 JBoss EAP 7 里下列的变化。

复查依赖关系的可用性

JBoss EAP 里包含的模块已经改动。当您迁移应用程序至 JBoss EAP 7 时，请复查您的 MANIFEST.MF 和 jboss-deployment-structure.xml 文件以确保它们没有引用本版本已删除的模块。

要求注解扫描的依赖关系

在之前 JBoss EAP 版本里，如果依赖关系包含了在注解扫描时需要处理的注解，如声明 EJB 拦截器时，您会被要求在新的 JAR 文件里生成和包括 Jandex 索引并在 MANIFEST.MF 或 jboss-deployment-structure.xml 部署描述符文件里设置一个标记。

JBoss EAP 7 现在为静态模块提供了注解索引的运行时自动生成，所以您不再需要手动生成它们。然而，您仍需要添加 annotations 标记到应用程序的 MANIFEST.MF 或 jboss-deployment-structure.xml 文件（如下所示）。

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

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

JBoss EAP 7 附带的 Hibernate Search 版本已被修改。之前版本的 JBoss EAP 附带 Hibernate Search 4.6.x，而 JBoss EAP 7 附带 Hibernate Search 5.5.x。

Hibernate Search 5.5 is built upon Apache Lucene 5.3.1. If you use any native Lucene APIs, be sure to align with this version. The Hibernate Search 5.5 API wraps and hides the complexity of many of the Lucene API changes made between version 3 and version 5, however, some classes are now deprecated, renamed, or repackaged. This section describes how these changes might impact your application code.

Hibernate Search Mapping 的修改

内嵌关系的 ID 字段的索引

当使用 @IndexedEmbedded 注解来包含相关实体的字段时，相关实体的 id 字段不再被包含。您可以用 @IndexedEmbedded 注解的 includeEmbeddedObjectId 属性启用对 id 的包含。

@IndexedEmbedded(includeEmbeddedObjectId=true)

数字和日期索引格式的修改

数字和日期现在默认用数值型字段作为索引。int、long、float、double类型的属性及对应的 Wrapper 类都不再用字符串进行索引了。它们现在改为使用 Lucene 的数字编码来索引。id 字段是这个规则的一个例外。即使它们用数字类型来表达，它们的索引默认仍使用字符串键值。@NumericField 现在已废弃，除非您希望为数字编码定制精度。您可以通过制定一个字符串编码的字段桥（field bridge）来保留旧的基于字符串的索引格式。对于整型，它就是 org.hibernate.search.bridge.builtin.IntegerBridge。关于其他可用的公用字段桥，请参考org.hibernate.search.bridge.builtin软件包。

Date 和 Calendar 不再以字符串为索引。它们改为用长整型来代表自 1970 年 1 月1 日 00:00:00 GMT 以来的毫秒数。您可以用新的EncodingType 枚举来切换索引格式。例如：

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

数字和日期的编码修改是很重要的，这对应用程序的行为有重大影响。如果以字段为目标的查询之前是用字符串编码，而现在是数字编码，您就必须更新这个查询。数字型的字段必须用 NumericRangeQuery 进行搜索。您也必须确保所有按目标分类的字段都是用字符串编码的。如果您使用 Search 查询 DSL，正确的查询应该会自动创建。

其他的 Hibernate Search 修改

Hibernate Search 重命名和重打包的类

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

Lucene - 重命名和重打包的类

查询解析器已移至新的模块，所在软件包从 org.apache.lucene.queryParser.QueryParser 改为 org.apache.lucene.queryparser.classic.QueryParser。

许多 Lucene 分析器都已重构，导致软件包的变动。要寻找替代的软件包，请查看 Apache Lucene 文档。

某些 Apache Solr 工具类，如 TokenizerFactory 或 TokenFilterFactory，都已移至 Apache Lucence。如果您的应用程序使用了这些工具或自定义的分析器，您必须找到 Apache Lucene 里新的软件包名称。

更多的信息请参考《Apache Lucene 迁移指南》。

Hibernate Search 已舍弃的 API

关于 Hibernate Search 已舍弃的接口、类、枚举、注解类型、方法、构造器和枚举常量的完整列表，请参考 Hibernate Search 已舍弃的 API 文档。

Hibernate Search 已舍弃的接口

Hibernate Search 已舍弃的类

Hibernate Search 已舍弃的枚举

Hibernate Search 已舍弃的注解

Hibernate Search 已舍弃的方法

Hibernate Search 已舍弃的构造器

影响高级集成器的修改

本节描述了非公用 API 的修改。它们不应该影响普通开发人员，因为这些工件只应该由继承 Hibernate Search 框架的集成者访问。

Java EE 7 对 EJB Entity Bean 的支持是可选的，它们不再受到支持。这意味着迁移到 JBoss EAP 7 时，您必须重写 CMP（container-managed persistence）和 BMP（bean-managed persistence）来使用 Java Persistence API (JPA) 实体。

在以前的 JBoss EAP 版本里，Entity Bean 是通过应用程序代码继承 javax.ejb.EntityBean 类并实现所需方法来创建的。它们然后在 ejb-jar.xml 文件里进行配置，CMP Entity Bean 用包含值为 Container 的 <persistence-type> 子元素的 <entity> 元素来指定。BMP entity bean 用包含值为 Bean 的子元素 <persistence-type> 的 <entity> 元素来指定。

在 JBoss EAP 7 里，您必须用 Java Persistence API (JPA) 实体替换任何 CMP 和 BMP Entity Bean。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、cmt 和 hibernate5 Quickstarts 例程。

我们添加了新的持久性属性 jboss.as.jpa.deferdetach 来提供对之前版本的 JBoss EAP 里的持久性行为的支持。

jboss.as.jpa.deferdetach 属性控制每次 EntityManager 调用后非 JTA 事务线程里使用的事务作用域的持久化上下文是否分离加载的实体，或者等待至持久化上下文关闭。例如，当 Session Bean 调用结束时。这个属性值默认是 false，表示实体在每次 EntityManager 调用后被分离或清除。这是 JPA 规格里定义的正确的默认行为。如果属性被设置为 true，实体在持久化上下文关闭前不会被分离。

在 JBoss EAP 5 里，持久化的行为就像将 jboss.as.jpa.deferdetach 属性设置为 true 一样。要在迁移至 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 修改了默认的远程连接器和端口。关于这种改动的细节，请参考更新远程 URL 连接器和端口。

如果您使用了 migrate 操作来迁移服务器配置，旧的设置将被保留，您不需要修改下面的细节。然而，如果您用新的 JBoss EAP 7 默认配置运行，您必须进行下列修改。

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

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

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

java.naming.factory.initial=org.jboss.naming.remote.client.InitialContextFactory
java.naming.provider.url=http-remoting://localhost:8080

The Java EE Application Deployment specification (JSR-88) was intended to define a standard contract to enable tools from multiple providers to configure and deploy applications on any Java EE platform product. The contract required Java EE Product Providers to implement the DeploymentManager and other javax.enterprise.deploy.spi interfaces to be accessed by the Tool Providers. In case of JBoss EAP 6, a deployment plan is identified by an XML descriptor named deployment-plan.xml that is bundled in a ZIP or JAR archive.

我们已很少采用这个规格，因为多数应用服务器产品提供了自己更“功能丰富”的部署方案。出于这个原因，Java EE 7 取消了对 JSR-88 的支持，所以 JBoss EAP 7 也不再支持。

If you used JSR-88 to deploy your application, you must now use another method to deploy the application. The JBoss EAP management CLI deploy command provides a standard way to deploy archives to standalone servers or to server groups in a managed domain. For more information about the management CLI, see the Management CLI Guide.

您必须手动迁移自定义阀或任何在 jboss-web.xml XML 文件里定义的阀。这包含通过继承 org.apache.catalina.valves.ValveBase 类创建以及在 jboss-web.xml 描述符文件的 <valve> 元素里配置的阀。

迁移部署里配置的阀

在 JBoss EAP 6，您可以在 jboss-web.xml 描述符文件里进行配置来定义应用程序级别的自定义阀。而在 JBoss EAP 7 里，您可以用 Undertow 处理程序来实现。

下面是 JBoss EAP 6 里的 jboss-web.xml 文件配置的阀的示例。

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

For more information about how to create and configure custom handlers in JBoss EAP, see Creating Custom Handlers in the JBoss EAP Development Guide.

迁移自定义验证器阀

关于如何迁移验证器阀的信息，请参考安全性应用程序的修改。

用 Undertow 替代 JBoss Web 要求修改 JBoss EAP 7 的安全性配置。

如果您的应用程序使用了 JBoss Logging，请注意 JBoss EAP 7 已舍弃在 org.jboss.logging 软件包里进行注解。它们被移至 org.jboss.logging.annotations 软件包，所以您必须更新源码来导入新的软件包。

这些注解也已移至单独的 Maven groupId:artifactId:version (GAV) ID，所以您需要在 pom.xml 文件里为 org.jboss.logging:jboss-logging-annotations 添加一个新的依赖关系。

下表列出已舍弃的注解类和对应的接替者。

取消对 JSF 1.2 的支持

JBoss EAP 6 允许您通过创建 jboss-deployment-structure.xml 文件继续使用 JSF 1.2。

JBoss EAP 7 包含 JSF 2.2 且不再支持 JSF 1.2 API。如果您的应用程序使用 JSF 1.2，您必须重写代码以使用 JSF 2.2。

JSF 2.1 和 JSF 2.2 间的兼容性问题

JSF 2.1 和 JSF 2.2 API 不是完全兼容的。FACELET_CONTEXT_KEY 常量从 com.sun.faces.facelets.FACELET_CONTEXT 改成了 javax.faces.FACELET_CONTEXT。编译器内联这个值，根据某个版本编译的代码将无法在其他版本里使用。

用 JSF 2.1 API 编译的包含和下面例子相似的代码的应用程序，如果在使用 JSF 2.2 API 的 JBoss EAP 7 里运行会导致 NullPointerException。要修复这个问题，您必须用 JSF 2.2 API 重新编译应用程序。

Object obj = FacesContext.getCurrentInstance().getAttributes().get(FaceletContext.FACELET_CONTEXT_KEY);

详情请参考 JAVASERVERFACES_SPEC_PUBLIC-1257。

在 JBoss EAP 7 里，多个模块包含相同的类或软件包时的类加载行为已修改。

假设有两个模块 MODULE_A 和 MODULE_B，彼此依赖并包含一些相同的软件包。在 JBoss EAP 6 里，从依赖关系加载的类或软件包优先于 module.xml 文件的 resource-root 元素里指定的。这意味着 MODULE_A 可以看到 MODULE_B 的软件包而 MODULE_B 可以看到 MODULE_A 的软件包。这种行为让人困惑且可能导致冲突。而 JBoss EAP 7 已修改了这种行为。现在 module.xml 文件的 resource-root 元素指定的类或软件包优先于依赖关系所指定的。这意味着 MODULE_A 只可以看到 MODULE_A 的软件包而 MODULE_B 可以看到 MODULE_B 的软件包。这防止了冲突并提供了更合适的行为。

If you have defined custom modules that include resource-root libraries or packages that contain classes that are duplicated in their module dependencies, you might see ClassCastException, LinkageError, class loading errors, or other changes in behavior when you migrate to JBoss EAP 7. To resolve these issues, you must configure your module.xml file to ensure only one version of a class is used. This can be accomplished by using either of the following approaches.

如果您希望保留现有的行为，你必须通过 filter 元素在过滤 module.xml 文件里 resource-root 的依赖关系软件包。这允许您保留现有的行为而不会看到 JBoss EAP 6 里看到的奇怪的循环。下面是通过 root-resource 过滤指定软件包里的类的例子。

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

For more information about modules and class loading, see Class Loading and Modules in the JBoss EAP Development Guide.

这个版本里 JBoss EAP 7 Natives 的提供与之前不同，其中一些现在附带新的 Red Hat JBoss Core Services 产品，这是许多 Red Hat JBoss 中间件产品常用的一套补充软件。新产品提供了更快的更新分发和更一致的更新体验。JBoss Core Services 产品可以在 Red Hat 客户门户网站的不同位置来下载。

A number of changes have been made to the Amazon Machine Images (AMI) in JBoss EAP 7. This section briefly summarizes some of those changes.

For details on deploying JBoss EAP 7 on Amazon EC2, see Deploying Red Hat JBoss Enterprise Application Platform on Amazon EC2.

The add-user script behavior has changed in JBoss EAP 7 due to a change in password policy. JBoss EAP 6 had a strict password policy. As a result, the add-user script rejected weak passwords that did not satisfy the minimum requirements. In JBoss EAP 7, weak passwords are accepted and a warning is issued. For more information, see Setting Add-User Utility Password Restrictions in the JBoss EAP Configuration Guide.

When JBoss EAP 6.0 GA was first released, JBoss OSGi, an implementation of the OSGi specification, was included as a Technology Preview feature. With the release of JBoss EAP 6.1.0, JBoss OSGi was demoted from Technology Preview to Unsupported.

In JBoss EAP 6.1.0, the configadmin and osgi extension modules and subsystem configuration for a standalone server were moved to a separate EAP_HOME/standalone/configuration/standalone-osgi.xml configuration file. Because you should not migrate this unsupported configuration file, the removal of JBoss OSGi support should not impact the migration of a standalone server configuration. If you modified any of the other standalone configuration files to configure osgi or configadmin, those configurations must be removed.

For a managed domain, the osgi extension and subsystem configuration were removed from the EAP_HOME/domain/configuration/domain.xml file in the JBoss EAP 6.1.0 release. However, the configadmin module extension and subsystem configuration remain in the EAP_HOME/domain/configuration/domain.xml file. This configuration is no longer supported in JBoss EAP 7 and must be removed.

This guide focuses on the changes that are required to successfully run and deploy JBoss EAP 6 applications on JBoss EAP 7. If you plan to migrate your applications directly from JBoss EAP 5 to JBoss EAP 7, there are a number of resources available to help you plan and execute your migration. We suggest you take the following approach.

Before you plan your migration, you should be aware of the changes that were made to JBoss EAP 6 and JBoss EAP 7.

The JBoss EAP 6 Migration Guide covers changes that were made between JBoss EAP 5 and JBoss EAP 6. The following is a condensed list of the most significant changes made in JBoss EAP 6.

See Review What’s New and Different in JBoss EAP 6 in the JBoss EAP 6 Migration Guide for a detailed list of changes made in that release.

JBoss EAP 7 is built on the same modular structure as JBoss EAP 6 and includes the same domain management, deployment configuration, file directory structure, and scripts. It also still uses the same standardized JNDI namespaces. However, JBoss EAP 7 introduces the following changes.

For a more complete list of changes, see Review What’s New in JBoss EAP 7

Review the entire contents of the Migration Guide for each release to become aware of the features that were added or deprecated, and to understand the server configuration and the application changes required to run existing applications for that release.

Because the underlying architecture was not changed between JBoss EAP 6 and JBoss EAP 7, many of the changes documented in the JBoss EAP 6 Migration Guide still apply. For example, changes documented under Changes Required by Most Applications are related to the underlying architectural changes made in JBoss EAP 6, which still apply to this release. The change to the new modular class loading system is significant and impacts the packaging and dependencies of almost every JBoss EAP 5 application. Many of the changes listed under Changes Dependent on Your Application Architecture and Components are also still valid. However, because JBoss EAP 7 replaced the web server, ORB, and messaging provider, removed the cmp, threads, and jaxr subsystems, and removed support for EJB entity beans, you must consult this guide for any changes related to those component areas. Pay particular attention to the Server Configuration Changes and Application Migration Changes detailed in this guide before you begin.

Use the following table to find information about how to migrate a particular feature or component from JBoss EAP 5 to JBoss EAP 7.