Configuring the Netty Runtime

Configuring the Netty Runtime

Overview

This section is for configuring the Netty runtime used for the CXF standalone model. The Netty runtime is used by HTTP servers and HTTP clients using a decoupled endpoint. The Netty runtime's thread pool, connector and timeouts can be configured. You can also set a number of the security settings for an HTTP service provider through the Netty runtime.

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 Betty configuration elements you will need to add the lines shown below to the beans element of your endpoint's configuration file. In addition, you will need to add the configuration elements' namespace to the xsi:schemaLocation attribute.

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

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

Element	Description
httpn:engine	Specifies the configuration for a particular Netty runtime instance.
httpn:identifiedTLSServerParameters	Specifies a reusable set of properties for securing an HTTP server. 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.

The `engine` element

The httpn:engine element is used to configure specific instances of the Netty runtime. It has a single attribute, port, that specifies the number of the port being managed by the Netty instance.

You can specify a value of 0 for the port attribute. Any threading properties specified in an httpn:engine element with its port attribute set to 0 are used as the configuration for all Netty listeners that are not explicitly configured.

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

The child elements used to provide the configuration properties are described below.

Element	Description
httpn:tlsServerParameters	Specifies a set of properties for configuring the security used for the specific Netty instance. See the TLS Configuration page for more information.
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.
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	If the value is true , the Netty Engine will set up a session manager for the Netty server engine to maintain the sessions. The default value of it is false.
httpn:reuseAddress	The the value is true, the Netty Engine connector's socket will enable the SO_REUSEADDR flage. The default value of it is true.

Configuring the thread pool

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

Specifying the size of thread pool using a identifiedThreadingParameters element in the engine-factory element. You then refer to the element using a threadingParametersRef element.
Specify the size of the of thread pool directly using a threadingParameters element.
The threadingParameters has one attribute to specify the size of a thread pool. The attribute is described below.
The httpn:identifiedThreadingParameters element has a single child threadingParameters element

Attribute	Description
threadPoolSize	Specifies the number of threads available to the Netty instance for processing requests.

HTTP/2 support

If HttpServerEngineSupport#ENABLE_HTTP2 bus property is set, Netty engine will enable the HTTP/2 support as well: HTTP/2 over cleartext (h2c) if TLS is not configured, regular HTTP/2 otherwise. It requires additional dependencies to be bundled by the application.

<dependency>
    <groupId>io.netty</groupId>
    <artifactId>netty-codec-http2</artifactId>
    <version>${netty.version}</version>
</dependency>

Please be aware that if you configure HTTP/2 + TLS, CXF right now only supports JDK SSL provider.

Example: https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/basic_http2_netty

Example

The example below shows a configuration fragment that configures a Netty instance on port number 9001.

<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:httpn="http://cxf.apache.org/transports/http-netty-server/configuration"
    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-netty-server/configuration 
        http://cxf.apache.org/schemas/configuration/http-netty-server.xsd 
        http://www.springframework.org/schema/beans 
        http://www.springframework.org/schema/beans/spring-beans.xsd">
    <httpn:engine-factory bus="cxf">
        <httpn:engine port="9001">
            <httpn:tlsServerParameters>
                <sec:keyManagers keyPassword="skpass">
                    <sec:keyStore file="src/main/config/serviceKeystore.jks" password="sspass" type="JKS"/>
                </sec:keyManagers>
                <sec:trustManagers>
                    <sec:keyStore file="src/main/config/serviceKeystore.jks" password="sspass" type="JKS"/>
                </sec:trustManagers>
            </httpn:tlsServerParameters>
        </httpn:engine>
    </httpn:engine-factory>
</beans>