12.4. 配置 Undertow 运行时

概述

Undertow 运行时由 HTTP 服务提供商和 HTTP 用户使用，使用分离的端点。可以配置运行时的线程池，您也可以通过 Undertow 运行时为 HTTP 服务提供商设置多个安全设置。

Maven 依赖项

如果使用 Apache Maven 作为构建系统，您可以通过在项目的 pom.xml 文件中包含以下依赖项，将 Undertow 运行时添加到项目中： 

<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-rt-transports-http-undertow</artifactId>
    <version>${cxf-version}</version>
</dependency>

命名空间

用于配置 Undertow 运行时的元素在命名空间 http://cxf.apache.org/transports/http-undertow/configuration 中定义。要使用 Undertow 配置元素，您必须将 例 12.14 “Undertow 运行时配置命名空间” 中显示的行添加到端点配置文件的 beans 元素中。在本例中，命名空间被分配了前缀 httpu。另外，您必须将配置元素的命名空间添加到 xsi:schemaLocation 属性中。

例 12.14. Undertow 运行时配置命名空间

<beans ...
       xmlns:httpu="http://cxf.apache.org/transports/http-undertow/configuration"
       ...
       xsi:schemaLocation="...
                           http://cxf.apache.org/transports/http-undertow/configuration
                              http://cxf.apache.org/schemas/configuration/http-undertow.xsd
                          ...">

engine-factory 元素

httpu:engine-factory 元素是用于配置应用使用的 Undertow 运行时的 root 元素。它有一个必需属性 bus，其值是管理所配置的 Undertow 实例的 总线 名称。

注意

该值通常是 cxf，这是默认 总线实例的名称。

http:engine-factory 元素有三个子对象，其中包含用于配置由 Undertow 运行时工厂实例化的 HTTP 端口的信息。子项在 表 12.7 “配置 Undertow 运行时工厂的元素” 中进行了描述。

表 12.7. 配置 Undertow 运行时工厂的元素

元素描述

httpu:engine

指定特定 Undertow 运行时实例的配置。请参阅 “engine 元素”一节。

httpu:identifiedTLSServerParameters

指定用于保护 HTTP 服务提供商的可重复使用的属性集合。它有一个属性 id，用于指定可以引用属性集的唯一标识符。

httpu:identifiedThreadingParameters

指定用于控制 Undertow 实例的线程池的可重复使用的属性集合。它有一个属性 id，用于指定可以引用属性集的唯一标识符。

请参阅 “配置线程池”一节。

engine 元素

httpu:engine 元素用于配置 Undertow 运行时的特定实例。它有两个属性 host，它指定了带有嵌入式 undertow 和 port 的全局 IP 地址，用于指定由 Undertow 实例管理的端口数。

注意

您可以为 port 属性指定 0 值。httpu:engine 元素中指定的任何线程属性，其 port 属性设置为 0，作为未明确配置的所有 Undertow 侦听程序的配置。

每个 httpu:engine 元素可以有两个子级：一个用于配置安全属性，另一个用于配置 Undertow 实例的线程池。对于每种配置，您可以直接提供配置信息，或者您可以提供对父 httpu:engine-factory 元素中定义的一组配置属性的引用。

表 12.8 “用于配置 Undertow 运行时实例的元素” 中描述了用来提供配置属性的子元素。

表 12.8. 用于配置 Undertow 运行时实例的元素

元素描述

httpu:tlsServerParameters

指定一组属性，用于配置用于特定 Undertow 实例的安全性。

httpu:tlsServerParametersRef

指的是由 identifiedTLSServerParameters 元素定义的一组安全属性。id 属性提供引用的 TLSServerParameters 元素的 id。

httpu:threadingParameters

指定特定 Undertow 实例使用的线程池的大小。请参阅 “配置线程池”一节。

httpu:threadingParametersRef

指的是由 识别ThreadingParameters 元素定义的一组属性。id 属性提供引用的 ThreadingParameters 元素的 id。

配置线程池

您可以通过以下任一方式配置 Undertow 实例线程池的大小：

  • 使用 engine-factory 元素 中标识的ThreadingParameters 元素来指定线程池的大小。然后，您可以使用 threadingParametersRef 元素引用元素。
  • 使用 threadingParameters 元素直接指定线程池的大小。

threadingParameters 有两个属性，用于指定线程池的大小。这些属性在 表 12.9 “用于配置 Undertow 线程池的属性” 中进行了描述。

注意

httpu:identifiedThreadingParameters 元素有一个子 threadingParameters 元素。

表 12.9. 用于配置 Undertow 线程池的属性

属性描述

workerIOThreads

指定为 worker 创建的 I/O 线程数量。如果没有指定，则会选择 dafult 值。默认值为每个 CPU 内核一个 I/O 线程。

minThreads

指定 Undertow 实例可用于处理请求的最少线程数量。

maxThreads

指定 Undertow 实例可用于处理请求的最大线程数。

示例

例 12.15 “配置 Undertow 实例” 显示在端口号 9001 上配置 Undertow 实例的配置片段。

例 12.15. 配置 Undertow 实例

<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:sec="http://cxf.apache.org/configuration/security"
  xmlns:http="http://cxf.apache.org/transports/http/configuration"
  xmlns:httpu="http://cxf.apache.org/transports/http-undertow/configuration"
  xmlns:jaxws="http://java.sun.com/xml/ns/jaxws"
  xsi:schemaLocation="http://cxf.apache.org/configuration/security
  		      http://cxf.apache.org/schemas/configuration/security.xsd
            http://cxf.apache.org/transports/http/configuration
            http://cxf.apache.org/schemas/configuration/http-conf.xsd
            http://cxf.apache.org/transports/http-undertow/configuration
            http://cxf.apache.org/schemas/configuration/http-undertow.xsd
            http://www.springframework.org/schema/beans
            http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">
  ...

  <httpu:engine-factory bus="cxf">
    <httpu:identifiedTLSServerParameters id="secure">
      <sec:keyManagers keyPassword="password">
        <sec:keyStore type="JKS" password="password"
                      file="certs/cherry.jks"/>
      </sec:keyManagers>
    </httpu:identifiedTLSServerParameters>

    <httpu:engine port="9001">
      <httpu:tlsServerParametersRef id="secure" />
      <httpu:threadingParameters minThreads="5"
                                 maxThreads="15" />
    </httpu:engine>
  </httpu:engine-factory>
 </beans>

限制并发请求和队列大小

您可以配置 Request Limiting Handler，该处理程序将为并发连接请求的最大数量和 Undertow 服务器实例可以处理的队列大小设置限制。此配置示例如下所示 例 12.16 “限制连接请求和队列大小”

表 12.10. 用于配置 Request Limiting Handler 的属性

属性描述

maximumConcurrentRequests

指定 Undertow 实例可以处理的并发请求数。如果请求数超过这个限制，请求将排队。

queueSize

指定可由 Undertow 实例排队进行处理的请求总数。如果请求数超过这个限制，请求将被拒绝。

例 12.16. 限制连接请求和队列大小

<httpu:engine-factory>
     <httpu:engine port="8282">
         <httpu:handlers>
             <bean class="org.jboss.fuse.quickstarts.cxf.soap.CxfRequestLimitingHandler">
                 <property name="maximumConcurrentRequests" value="1" />
                 <property name="queueSize" value="1"/>
             </bean>
         </httpu:handlers>
     </httpu:engine>
</httpu:engine-factory>