第 4 章 服务器配置的修改

在 JBoss EAP 7 里 Undertow 替换了 JBoss Web。这意味着旧的 web 子系统配置必须迁移到新的 JBoss EAP 7 的 undertow 子系统配置。

您可以使用管理 CLI 的 migrate 操作将服务器配置文件里的 web 子系统迁移到 undertow。然而，请注意这个操作不能迁移所有的 JBoss Web 子系统配置。如果您看到 "migration-warning" 条目，您必须运行其他的管理 CLI 命令来迁移这些配置到 Undertow。关于管理 CLI 的 migrate 操作的更多信息，请参考 Management CLI Migration Operation。

下面是 JBoss EAP 6 里默认的 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 6 里默认的 undertow 子系统配置示例。

<subsystem xmlns="urn:jboss:domain:undertow:3.1">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="default" socket-binding="http" redirect-socket="https"/>
        <host name="default-host" alias="localhost">
            <location name="/" handler="welcome-content"/>
            <filter-ref name="server-header"/>
            <filter-ref name="x-powered-by-header"/>
        </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>

管理 CLI 的 migrate 操作无法自动迁移重写条件，它们被报告为“migration-warnings”，您必须手动迁移它们。在 JBoss EAP 7 里，您可以用 Undertow Predicates Attributes and Handlers 创建同等的配置。

下面是 JBoss EAP 6 里包含 rewrite 配置的默认 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>

按照 Management CLI Migration Operation 说明启动服务器和管理 CLI，然后用下列命令迁移 web 子系统配置文件。

/subsystem=web:migrate

当您对上述配置运行 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:3.1">
     <buffer-cache name="default"/>
     <server name="default-server">
         <http-listener name="http" socket-binding="http"/>
         <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" ⇒ "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:3.1">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="http" socket-binding="http"/>
        <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>

For more information about how to configure filters and handlers using the management CLI, see Configuring the Web Server in the JBoss EAP 7 Configuration Guide.

In the previous release of JBoss EAP, system properties could be used to modify the default JBoss Web behavior. For information about how to configure the same behavior in Undertow, see JBoss Web System Properties Migration Reference

In JBoss EAP 6, JBoss Web supported the ability to specify additional static files for a web application using the overlay element in the jboss-web.xml file. This feature did not actually overlay existing files, but instead added static files to a deployment outside of the WAR archive.

In the following jboss-web.xml file example, /tmp/mycontents/test.html was returned by the JBoss EAP 6 server when you accessed the URL http://localhost:8080/example/test.html.

<jboss-web>
    <context-root>/example</context-root>
    <overlay>/tmp/mycontents/</overlay>
</jboss-web>

Undertow, which replaces JBoss Web in JBoss EAP 7, does not support the jboss-web.xml file overlay feature.

以前的 JBoss EAP 版本支持阀（Valve）。阀是在 Servlet 过滤器修改请求或执行其他处理前插入到应用程序的请求处理管道的自定义类。

本节描述了如何迁移全局阀。本指南的『Migrate Custom Application Valves』章节涵盖了自定义和验证阀的迁移。

在 JBoss EAP 7 里替换了 JBoss Web 的 Undertow 不支持全局 Valve。然而，通过使用 Undertow 处理程序，您应该能够实现类似的功能。 Undertow 包含了大量的提供常用功能的内嵌处理程序。它也提供创建自定义处理程序的能力，它们可用来替代自定义 Valve 的功能。

如果您的应用程序使用了阀，在迁移至 JBoss EAP 7 时，您必须用合适的 Undertow 处理程序代码替代它们来实现相同功能。

For more information about how to configure handlers, see Configuring Handlers in the JBoss EAP 7 Configuration Guide.

For more information about how to configure filters, see Configuring Filters in the JBoss EAP 7 Configuration Guide.

迁移 JBoss Web 阀

下表列出之前版本的 JBoss EAP 和对应的 Undertow 内置处理程序提供的阀。JBoss Web 阀位于 org.apache.catalina.valves 软件包里。

您可以使用管理 CLI 的 migrate 操作自动迁移满足下列标准的全局阀。

关于管理 CLI 的 migrate 操作的更多信息，请参考 Management CLI Migration Operation。

JDBCAccessLogValve 的手动迁移过程

org.apache.catalina.valves.JDBCAccessLogValve 阀是规则的一个例外，它不能自动迁移到 io.undertow.server.handlers.JDBCLogHandler。请遵循下面的步骤来迁移示例阀。

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

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

因为使用专有的网络接口是我们的推荐做法，在默认情况下，JGroups 使用 JBoss EAP 7 里服务器配置文件的 <interfaces> 部分定义的新的 private 接口。

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

For more information about how to configure JGroups, see Cluster Communication with JGroups in the JBoss EAP Configuration Guide.

In JBoss EAP 6, the default clustered caches for web session replication and EJB replication were replicated ASYNC caches. This has changed in JBoss EAP 7. The default clustered caches are now distributed ASYNC caches. The replicated caches are no longer even configured by default. See Configure the Cache Mode in the JBoss EAP Configuration Guide for information about how to add a replicated cache and make it the default.

这只适用于新的 JBoss EAP 7 默认配置。如果您从 JBoss EAP 6 迁移配置，那 infinispan 子系统的配置将被保留。

JBoss EAP 7 已修改了 ASYNC 缓存策略的行为。

在 JBoss EAP 6 里，ASYNC 缓存的读操作是与锁无关的。虽然它们永不会阻塞，但很容易导致过时数据的脏读（Dirty Read），例如发生失效切换的时候。这是因为它会允许相同用户之后的请求在之前请求还未完成前开始。在使用分布式模式时，这种随意性是不能接受的，群集拓扑结构的修改可能影响到会话关联性且容易导致数据过时。

在 JBoss EAP 7 里，ASYNC 缓存读操作需要锁。既然它们现在会阻塞相同用户的新请求直至之前的复制完成，这可以防止脏读（Dirty Read）。

位于 EAP_HOME/modules/system/layers/base/ 的 org.jboss.as.messaging 模块扩展，已被 EAP_HOME/modules/system/layers/base/ 扩展模块替代。

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

管理模型

多数情况下，我们会尽可能地将元素和属性名称和之前版本保持一致。下表列出了其中一些修改。

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

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

/subsystem=messaging:migrate

Before you execute the migrate operation, you can invoke the describe-migration operation to review the list of management operations that will be performed to migrate from the existing JBoss EAP 6 messaging subsystem configuration to the messaging-activemq subsystem on the JBoss EAP 7 server.

/subsystem=messaging:describe-migration

对于无法自动迁移的资源或属性，migrate 和 describe-migration 也会显示一个migration-warnings 列表。

消息子系统的迁移和向前兼容性

用于 messaging 子系统的 describe-migration 和 migrate 操作提供了额外的配置参数。如果您想配置消息系统以允许旧的 JBoss EAP 6 客户链接 JBoss EAP 7 服务器，您可以像下面这样添加布尔型 add-legacy-entries 参数至 describe-migration 或 migrate 操作。

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

如果布尔型参数add-legacy-entries 被设置为 true，messaging-activemq 子系统将创建 legacy-connection-factory 资源并添加 legacy-entries 至 jms-queue 和 jms-topic 资源。

如果布尔型参数add-legacy-entries 被设置为 false，messaging-activemq 子系统里不会创建旧的资源，且旧的 JMS 客户不能与 JBoss EAP 7 服务器通讯。这是默认值。

For more information about forward and backward compatibility see the Backward and Forward Compatibility in Configuring Messaging for JBoss EAP.

关于管理 CLI migrate 和 describe-migration 操作的更多信息，请参考 Management CLI Migration Operation。

Change in Behavior of forward-when-no-consumers Attribute

The behavior of the forward-when-no-consumers attribute has changed in JBoss EAP 7.

In JBoss EAP 6, when forward-when-no-consumers was set to false and there were no consumers in a cluster, messages were redistributed to all nodes in a cluster.

This behavior has changed in JBoss EAP 7. When forward-when-no-consumers is set to false and there are no consumers in a cluster, messages are not redistributed. Instead, they are kept on the original node to which they were sent.

消息子系统的 XML 配置

XML 配置已根据新的 messaging-activemq 进行了极大的修改以提供和其他 JBoss EAP 子系统更一致的 XML 模式。

It is strongly advised that you do not attempt to modify the JBoss EAP messaging subsystem XML configuration to conform to the new messaging-activemq subsystem. Instead, invoke the legacy subsystem migrate operation. This operation will write the XML configuration of the new messaging-activemq subsystem as a part of its execution.

JBoss EAP 7 里由于 JMS 支持供应商从 HornetQ 变成了 ActiveMQ Artemis，消息数据的格式和位置都发生了变化。

您可以使用下列方式之一来迁移数据：

关于不同版本间消息数据文件夹名称的改动的细节，请参考映射消息文件夹名称。

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)

在以前的 JBoss EAP 版本里，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>

JBoss EAP 7 里消息拦截器已发生了重大改变，JMS 消息提供者由 HornetQ 替换为 ActiveMQ Artemis。

之前版本里的 HornetQ 的 messaging 子系统要求您将 HornetQ 拦截器添加至 JAR 并修改 module.xml 文件来安装 HornetQ 拦截器。

The messaging-activemq subsystem included in JBoss EAP 7 does not require modification of a module.xml file. User interceptor classes, which now implement the Apache ActiveMQ Artemis Interceptor interface, can now be loaded from any server module. You specify the module from which the interceptor should be loaded in the messaging-activemq subsystem of the server configuration file.

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

在 JBoss EAP 6 里，你可以配置一个 Servlet 引擎与 Netty Servlet 传输一起使用。因为在 JBoss EAP 7 里内置的消息供应商由 ActiveMQ Artemis 替代了 HornetQ，这样的配置不再可用。您必须替换 Servlet 配置以使用新的内置消息 HTTP 连接器和 HTTP 接收器。

当您在以前的 JBoss EAP 版本里配置数据源时，为驱动名指定的值取决于 JDBC 驱动 JAR 里包含的 META-INF/services/java.sql.Driver 文件里列出的类的数量。

包含单个类的驱动

如果 META-INF/services/java.sql.Driver 文件只指定了一个类，驱动名将是 JDBC 驱动 JAR 的名称。JBoss EAP 7 没有改变这一点。

包含多个类的驱动

在 JBoss EAP 6 里，如果 META-INF/services/java.sql.Driver 文件列出了多个类，您可以指定哪个类将其名称附加到 JAR 名称，之后是主要和次要版本号。例如：

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

而 JBoss EAP 7 里的命名有所不同，现在您用下列格式指定驱动名称。

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

MySQL 5.1.31 JDBC 驱动是一个包含两个类的例子。其驱动类名是 com.mysql.jdbc.Driver。下面的例子展示了之前版本和当前版本的 JBoss EAP 指定驱动名的不同之处。

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

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