此内容没有您所选择的语言版本。

12.5. Configuring the Netty Runtime

Overview

The Netty runtime is used by HTTP service providers and HTTP consumers using a decoupled endpoint. The runtime's thread pool can be configured, and you can also set a number of the security settings for an HTTP service provider through the Netty runtime.

Maven dependencies

If you use Apache Maven as your build system, you can add the server-side implementation of the Netty runtime (for defining Web service endpoints) to your project by including the following dependency in your project's pom.xml file:

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

You can add the client-side implementation of the Netty runtime (for defining Web service clients) to your project by including the following dependency in your project's pom.xml file:

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

Namespace

The elements used to configure the Netty runtime are defined in the namespace http://cxf.apache.org/transports/http-netty-server/configuration. It is commonly referred to using the prefix httpn. In order to use the Netty configuration elements you must add the lines shown in Example 12.16, “Netty Runtime Configuration Namespace” to the beans element of your endpoint's configuration file. In addition, you must add the configuration elements' namespace to the xsi:schemaLocation attribute.

Example 12.16. Netty Runtime Configuration Namespace

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

The engine-factory element

The httpn:engine-factory element is the root element used to configure the Netty runtime used by an application. It has a single required attribute, bus, whose value is the name of the Bus that manages the Netty instances being configured.

Note

The value is typically cxf, which is the name of the default Bus instance.

The httpn:engine-factory element has three children that contain the information used to configure the HTTP ports instantiated by the Netty runtime factory. The children are described in Table 12.10, “Elements for Configuring a Netty Runtime Factory”.

Table 12.10. Elements for Configuring a Netty Runtime Factory
Element	Description
`httpn:engine`	Specifies the configuration for a particular Netty runtime instance. See the section called “The engine element”.
`httpn:identifiedTLSServerParameters`	Specifies a reusable set of properties for securing an HTTP service provider. It has a single attribute, `id`, that specifies a unique identifier by which the property set can be referred.
`httpn:identifiedThreadingParameters`	Specifies a reusable set of properties for controlling a Netty instance's thread pool. It has a single attribute, `id`, that specifies a unique identifier by which the property set can be referred. See the section called “Configuring the thread pool”.

The engine element

The httpn:engine element is used to configure specific instances of the Netty runtime. Table 12.11, “Attributes for Configuring a Netty Runtime Instance” shows the attributes supported by the httpn:engine element.

Table 12.11. Attributes for Configuring a Netty Runtime Instance
Attribute	Description
`port`	Specifies the port used by the Netty HTTP server instance. You can specify a value of `0` for the port attribute. Any threading properties specified in an engine element with its port attribute set to `0` are used as the configuration for all Netty listeners that are not explicitly configured.
`host`	Specifies the listen address used by the Netty HTTP server instance. The value can be a hostname or an IP address. If not specified, Netty HTTP server will listen on all local addresses.
`readIdleTime`	Specifies the maximum read idle time for a Netty connection. The timer is reset whenever there are any read actions on the underlying stream.
`writeIdleTime`	Specifies the maximum write idle time for a Netty connection. The timer is reset whenever there are any write actions on the underlying stream.
`maxChunkContentSize`	Specifies the maximum aggregated content size for a Netty connection. The default value is 10MB.

A httpn:engine element has one child element for configuring security properties and one child element for configuring the Netty instance's thread pool. For each type of configuration you can either directly provide the configuration information or you can provide a reference to a set of configuration properties defined in the parent httpn:engine-factory element.

The supported child elements of httpn:engine are shown in Table 12.12, “Elements for Configuring a Netty Runtime Instance”.

Table 12.12. Elements for Configuring a Netty Runtime Instance
Element	Description
`httpn:tlsServerParameters`	Specifies a set of properties for configuring the security used for the specific Netty instance.
`httpn:tlsServerParametersRef`	Refers to a set of security properties defined by a `identifiedTLSServerParameters` element. The `id` attribute provides the id of the referred `identifiedTLSServerParameters` element.
`httpn:threadingParameters`	Specifies the size of the thread pool used by the specific Netty instance. See the section called “Configuring the thread pool”.
`httpn:threadingParametersRef`	Refers to a set of properties defined by a `identifiedThreadingParameters` element. The `id` attribute provides the id of the referred `identifiedThreadingParameters` element.
`httpn:sessionSupport`	When `true`, enables support for HTTP sessions. Default is `false`.
`httpn:reuseAddress`	Specifies a boolean value to set the `ReuseAddress` TCP socket option. Default is `false`.

Configuring the thread pool

You can configure the size of a Netty instance's thread pool by either:

Specifying the size of the thread pool using a identifiedThreadingParameters element in the engine-factory element. You then refer to the element using a threadingParametersRef element.
Specifying the size of the of the thread pool directly using a threadingParameters element.

The threadingParameters element has one attribute to specify the size of a thread pool, as described in Table 12.13, “Attributes for Configuring a Netty Thread Pool”.

Note

The httpn:identifiedThreadingParameters element has a single child threadingParameters element.

Table 12.13. Attributes for Configuring a Netty Thread Pool
Attribute	Description
`threadPoolSize`	Specifies the number of threads available to the Netty instance for processing requests.

Example

Example 12.17, “Configuring a Netty Instance” shows a configuration fragment that configures a variety of Netty ports.

Example 12.17. Configuring a Netty Instance

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:beans="http://www.springframework.org/schema/beans"    
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:h="http://cxf.apache.org/transports/http/configuration"
       xmlns:httpn="http://cxf.apache.org/transports/http-netty-server/configuration"
       xmlns:sec="http://cxf.apache.org/configuration/security"
       xsi:schemaLocation="
        http://www.springframework.org/schema/beans 
            http://www.springframework.org/schema/beans/spring-beans.xsd
        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-netty-server/configuration 
            http://cxf.apache.org/schemas/configuration/http-netty-server.xsd"
>
    ...
    <httpn:engine-factory bus="cxf">
       <httpn:identifiedTLSServerParameters id="sample1">
         <httpn:tlsServerParameters jsseProvider="SUN" secureSocketProtocol="TLS">
            <sec:clientAuthentication want="false" required="false"/>
         </httpn:tlsServerParameters>
       </httpn:identifiedTLSServerParameters>
       
       <httpn:identifiedThreadingParameters id="sampleThreading1">
          <httpn:threadingParameters threadPoolSize="120"/>
       </httpn:identifiedThreadingParameters>
       
       <httpn:engine port="9000" readIdleTime="30000" writeIdleTime="90000">
          <httpn:threadingParametersRef id="sampleThreading1"/>          
       </httpn:engine>
       
       <httpn:engine port="0">
          <httpn:threadingParameters threadPoolSize="400"/>
       </httpn:engine>
       
       <httpn:engine port="9001" readIdleTime="40000" maxChunkContentSize="10000">
         <httpn:threadingParameters threadPoolSize="99" />          
         <httpn:sessionSupport>true</httpn:sessionSupport>
       </httpn:engine> 
      
       <httpn:engine port="9002">
         <httpn:tlsServerParameters>
           <sec:clientAuthentication want="true" required="true"/>
         </httpn:tlsServerParameters>
       </httpn:engine>
      
       <httpn:engine port="9003">
          <httpn:tlsServerParametersRef id="sample1"/>
       </httpn:engine>
      
    </httpn:engine-factory>
</beans>