第 5 章 应用程序迁移的修改

基于 XML 的 RPC（JAX-RPC）的 Java API 在 Java EE 6 已被舍弃，在 Java EE 7 里是可选的。在 JBoss EAP 7 里它不再可用也不被支持。使用 JAX-RPC 的应用程序必须迁移以使用目前 Java EE 的标准 Web Service 框架 JAX-WS。

JAX-RPC Web Service 可以用下列途径确认：

在以前的 JBoss EAP 版本里，您可以通过在端点部署归档里包含 jbossws-cxf.xml 配置文件来自定义 JBossWS 和 Apache CXF 集成。其中已一个例子是为 Apache CXF 总线上的 Web Service 客户和服务器端点配置连接器链。这个集成要求在 JBoss EAP 服务器里部署 Spring。

JBoss EAP 7 不再支持 Spring 集成。任何包含 jbossws-cxf.xml 描述符配置文件的应用程序必须进行修改，替换该文件里定义的自定义配置。虽然您仍可以直接访问 Apache CXF API，请注意应用程序将会是不可迁移的。

我们建议的方法是尽量用新的 JBossWS 描述符配置选项替换 Spring 自定义配置。基于 JBossWS 描述符的方法提供了类似的功能而无需修改客户端点代码。在某些情况下，您可以用 Context Dependency Injection (CDI) 替代 Spring。

Apache CXF 拦截器

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 里，HTTP 传输配置是通过 org.apache.cxf.transport.http.HTTPConduit 属性实现的。JBoss WS 集成允许在程序里使用 Apache CXF API 修改 Conduit。

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-api 和 cxf-rt-core JAR 已合并到一个 cxf-core JAR。因此，JBoss EAP 里的 org.apache.cxf 模块现在包含了 cxf-core JAR 并较之以前的版本开放了更多的类。

如果您想对 XML/WS-Security 里的对称加密使用 AES 加密和 Galois/Counter Mode (GCM)，您需要 BouncyCastle 安全提供者。

JBoss EAP 7 附带了 org.bouncycastle 模块，JBossWS 现在能够依赖自己的类加载来获取和使用 BouncyCastle 安全提供者。因此不再需要再当前 JMV 里静态地安装 BouncyCastle。对于运行在容器外而要访问安全提供者的应用程序，你可以添加 BouncyCastle 库到 classpath 里。

您可以通过设置 jaxws-endpoint-config.xml（服务器）或 jaxws-client-config.xml （客户）里的 org.jboss.ws.cxf.noLocalBC 属性值为 true 来禁用这个行为。

如果您不想使用 JBoss EAP 附带的版本，您仍可以将 BouncyCastle 静态地安装到 JVM 里。在这种情况下，静态安装的 BouncyCastle 将优先于 classpth 的安全提供者。要避免这种情况，您必须使用 BouncyCastle 1.49、1.51 或更高的版本。

容器里运行的客户的默认总线选择策略已从 THREAD_BUS 改为 TCCL_BUS。对于在容器外运行的客户，默认的策略仍是 THREAD_BUS。您可以用下列方法来恢复之前版本里的设置。

容器必须使用JAX-WS 2.2 风格的构造器，它使用 WebServiceFeature 类来构建注入到 Web service 引用里的客户。这意味着用户提供的服务类（由容器注入）必须实现 JAX-WS 2.2 或更高规格。

在以前的版本里，通过设置系统属性 org.jboss.security.ignoreHttpsHost 为 true，您可以禁用对证书里服务器的公共名称（Common Name，CN） 的 HTTPS URL 主机名检查。这个系统属性名称已被 cxf.tls-client.disableCNCheck 所替代。

As a consequence of enabling injections into service endpoint and service client handlers, it is no longer possible to automatically load handler classes from the org.jboss.as.webservices.server.integration JBoss module. If your application depends on a given predefined configuration, you might need to explicitly define new module dependencies for your deployment. For more information, see Migrate Explicit Module Dependencies

JDK 1.8_40 已舍弃 Java Endorsed Standards Override Mechanism 而 JDK 9 将删除它。这个机制允许开发人员将 JAR 放入 JRE 里支持的目录，从而使这些库为所有部署的应用程序所用。

如果您的应用程序使用了 Apache CXF 的 JBossWS 实现，JBoss EAP 7 会确保以正确的顺序添加所需的依赖关系，所以您不会受这些改动的影响。如果您的应用程序直接访问 Apache CXF，作为应用程序部署的一部分，在 JBossWS 依赖关系之后您现在必须提供 Apache CXF 依赖关系。

在以前的 JBoss EAP 版本里，您可以为 JAR 归档的 META-INF/ 里的 EJB Web Service 部署或 WEB-INF/ 里的 POJO Web Service 部署及 WAR 归档捆绑的 EJB Web Service 端点配置 jboss-webservices.xml 部署描述符文件。

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

JBoss EAP 7 舍弃了用命名模式 -jms.xml 标识的私有 JMS 资源部署描述符文件。下面是一个 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 7 部署描述符，或者升级部署描述符来使用 JBoss EAP 7 里的 messaging-activemq 子系统。

如果您选择更新描述符，您需要进行下列修改。

修改后的文件应该类似于下面的例子。

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

关于和消息相同相关的服务器配置修改，请参考 Messaging Server Configuration Changes。

JBoss EAP 7 仍支持 JMS 1.1 API，所以您不需要修改您的代码。

JBoss EAP 7 修改了默认的远程连接器和端口。关于这种改动的细节，请参考更新远程 URL 连接器和端口。

如果您用 migrate 操作移您的服务器配置，旧的设置将被保留，您不需要更新 PROVIDER_URL。然而，如果您用新的 JBoss EAP 7 的默认配置来运行，您必须在客户代码里修改 PROVIDER_URL 并使用新的 http-remoting://localhost:8080 设置。更多信息请参考迁移远程命名客户代码。

如果您计划将您的代码迁移至 JMS 2.0 API，请参考 helloworld-jms quickstart 里的用法。

JBoss EAP 6 包含 org.hornetq 模块，它允许您在代码里使用 HornetQ API。

JBoss EAP 7 里 Apache ActiveMQ Artemis 替代了 HornetQ，所以您必须迁移任何使用 HornetQ API 的代码，使其使用 Apache ActiveMQ Artemis API。这个 API 库包含在 org.apache.activemq.artemis 模块里。

ActiveMQ Artemis 是 HornetQ 的演化版本，所以许多概念仍然适用。

Interceptor 和 MessageBody 类

JSR 311: JAX-RS: The Java™ API for RESTful Web Services did not include an interceptor framework, so RESTEasy 2 provided one. JSR 339: JAX-RS 2.0: The Java API for RESTful Web Services introduced an official interceptor and filter framework, so the interceptor framework included in RESTEasy 2 is now deprecated, and is replaced by the JAX-RS 2.0 compliant interceptor facility in RESTEasy 3.x. The relevant interfaces are defined in the javax.ws.rs.ext package of the jaxrs-api module.

For more information about interceptors, see RESTEasy Interceptors in Developing Web Services Applications for JBoss EAP.

关于新的替代 API 的更多信息，请参考 RESTEasy JAX-RS 3.0.13.Final API 或更新的版本。

Client API

resteasy-jaxrs 里的 RESTEasy 客户框架已被兼容 JAX-RS 2.0 的 resteasy-client 模块替代。因此，某些 RESTEasy Client API 类和方法已被舍弃。

StringConverter

RESTEasy 3.x 已舍弃了 org.jboss.resteasy.spi.StringConverter 类。这个功能可以用 JAX-RS 2.0 jax.ws.rs.ext.ParamConverterProvider 类替代。

ResteasyProviderFactory 的 Add 系列方法

在 RESTEasy 3.0 里，大部分 org.jboss.resteasy.spi.ResteasyProviderFactory add() 方法已被删除或权限变为 protected。例如，addBuiltInMessageBodyReader{} 和 addBuiltInMessageBodyWriter() 方法已被删除而 addMessageBodyReader() 和 addMessageBodyWriter() 方法的权限已变成 protected。

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

RESTEasy 3 里删除的其他类

指定 JAX-RS 方法的响应应该在服务器上缓存的 @org.jboss.resteasy.annotations.cache.ServerCached 注解，已从 RESTEasy 3 删除且必须从应用程序代码里删除。

SignedInput 和 SignedOuput

安全过滤器

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

客户端过滤器

当您使用之前版本的 RESTEasy client API 时，新的 JAX-RS 2.0 客户端过滤器不会被绑定和运行。

对异步 HTTP 的支持

Because the JAX-RS 2.0 specification adds asynchronous HTTP support using the @Suspended annotation and the AsynResponse interface, the RESTEasy proprietary API for asynchronous HTTP has been deprecated and might be removed as soon as RESTEasy 3.1. The asynchronous Tomcat and asynchronous JBoss Web modules have also been removed from the server installation. If you are not using the Servlet 3.0 container or higher, asynchronous HTTP server-side processing will be simulated and run synchronously in same request thread.

服务器端的缓存

服务器端的缓存设置已经改变，更多信息请参考 RESTEasy Documentation 。

SPI 异常

我们已舍弃所有的 SPI 失败异常，不再在内部使用它们。它们已被对应的JAX-RS 2.0 异常所替代。

InjectorFactory 和 Registry

InjectorFactory 和 Registry SPI 已有改动。如果您按照文档和支持来使用 RESTEasy，这不应该成为问题。

JBoss EAP 7 里包含的 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。

To switch your application to use the default provider that was included in the previous release of JBoss EAP, see Switching the Default Jackson Provider in Developing Web Services Applications for JBoss EAP.

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

JBoss EAP 7 已舍弃了 RESTEasy Jettison JSON 提供者，默认不再将其添加到部署里。我们鼓励您切换至我们推荐的 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>

For more information about how to define explicit dependencies, see Add an Explicit Module Dependency to a Deployment in the JBoss EAP Development Guide.

The integration classes that made it easier to use Hibernate ORM 3 in the previous release were removed from JBoss EAP 7. If your application still uses Hibernate ORM 3 libraries, it is strongly recommended that you migrate your application to use Hibernate ORM 5 as Hibernate ORM 3 will no longer work in JBoss EAP without a lot of effort. If you can not migrate to Hibernate ORM 5, you must define a custom JBoss Module for the Hibernate ORM 3 JARs and exclude the Hibernate ORM 5 classes from your application.

If your application needs second-level cache enabled, you should migrate to Hibernate ORM 5, which is integrated with Infinispan 8.x.

Applications written with Hibernate ORM 4.x can still use Hibernate ORM 4.x. You must define a custom JBoss module for the Hibernate ORM 4.x JARs and exclude the Hibernate ORM 5 classes from your application. However, it is strongly recommended that you rewrite your application code to use Hibernate ORM 5. For information about migrating to Hibernate ORM 5, see Migrating to Hibernate ORM 5.

If your application contains a persistence.xml file or the code uses the @PersistenceContext or @PersistenceUnit annotations, JBoss EAP 7 detects this during deployment and assumes the application uses JPA. It implicitly adds the Hibernate ORM 5 libraries plus a few other dependencies to your application class path and defaults to using these libraries.

This section highlights the changes you need to make when migrating from Hibernate ORM version 4.3 to version 5. For more information about the changes implemented between Hibernate ORM 4 and Hibernate ORM 5, see the Hibernate ORM 5.0 Migration Guide.

Removed and Deprecated Classes

The following deprecated classes were removed from Hibernate ORM 5.

Other Changes to Classes and Packages

Type Handling

Transaction Management

Other Hibernate ORM 5 Changes

在 jboss-ejb-client.properties 文件里将远程连接端口值从 4447 改为 8080。

下面是之前和当前版本里的 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

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

如果您使用新的 JBoss EAP 7 配置运行，默认的连接器已从 remote 改为 http-remoting。这次改动影响了使用某个版本里的库并连接不同版本的服务器的客户。

如果您用新的默认 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.jboss.naming.remote.client.InitialContextFactory
java.naming.provider.url=http-remoting://localhost:8080

验证器阀（Authenticator Valve）必须用 Undertow 内置的验证机制手动替代。关于如何迁移验证器阀的信息，请阅读下面的章节。

For information about the changes required for SSO with SAML v2 configuration, see Changes from Previous Versions of JBoss EAP in How to Set Up SSO with SAML v2 for JBoss EAP.

For information about the differences in SSO configuration with Kerberos, see Differences from Configuring Previous Versions JBoss EAP in How to Set Up SSO with Kerberos for JBoss EAP.

下面描述了从 JBoss EAP 6 迁移至 JBoss EAP 7 时要注意的新的群集功能。

The remainder of this section describes how clustering changes might impact the migration of your applications to JBoss EAP 7.

JBoss EAP 7 引入了新的 Web 会话群集实现。它替代了之前和旧的 JBoss Web 子系统紧耦合的实现。

新的 Web 会话群集实现影响了如何在 jboss-web.xml 描述符文件里配置应用程序。下面是这个文件里保留的群集配置元素。

<jboss-web>
  ...
  <max-active-sessions>...</max-active-sessions>
  ...
  <replication-config>
    <replication-granularity>...</replication-granularity>
    <cache-name>...</cache-name>
  </replication-config>
  ...
</jboss-web>

下表描述了如何实现和 jboss-web.xml 里现已舍弃的元素类似的行为。

This new implementation also supports write-through cache stores as well as passivation-only cache stores. Typically, a write-through cache store is used in conjunction with an invalidation cache. The web session clustering implementation in JBoss EAP 6 did not operate correctly when used with an invalidation cache.

在 JBoss EAP 6 里，您被要求以下列方式之一启用 stateful session beans (SFSBs) 的群集行为。

JBoss EAP 7 不再要求您启用群集行为。在默认情况下，如果服务器用 HA 配置集启动，SFSB 的状态将自动复制。

您可以用下列方式之一禁用默认的行为。

在 JBoss EAP 6，用于群集服务的 API 位于私有模块且不被支持。

JBoss EAP 7 引入了公用群集 API。新的服务被设计为轻量级的、易于注入的且没有外部依赖关系。

这些服务替代了之前版本里类似的 API，也就是 JBoss EAP 5 的 HAPartition，JBoss EAP 6 里的 GroupCommunicationService、GroupMembershipNotifier 和 GroupRpcDispatcher。

For more information, see Public API for Clustering Services in the JBoss EAP Development Guide.

在 JBoss EAP 6 里，群集范围的 HA 单点登录服务没有可用的公用 API。如果您使用了私有 org.jboss.as.clustering.singleton.* 类，在迁移应用程序至 JBoss EAP 7 时，您必须修改代码以使用新的公用 org.wildfly.clustering.singleton.* 软件包。

For more information about how to implement an HA singleton, see HA Singleton Service in the Development Guide for JBoss EAP.