Chapter 12. Using HTTP
Abstract
HTTP is the underlying transport for the Web. It provides a standardized, robust, and flexible platform for communicating between endpoints. Because of these factors it is the assumed transport for most WS-* specifications and is integral to RESTful architectures.
12.1. Adding a Basic HTTP Endpoint
Alternative HTTP runtimes
Apache CXF supports the following alternative HTTP runtime implementations:
- Undertow, which is described in detail in Section 12.4, “Configuring the Undertow Runtime”.
- Netty, which is described in detail in Section 12.5, “Configuring the Netty Runtime”.
Netty HTTP URL
Normally, a HTTP endpoint uses whichever HTTP runtime is included on the classpath (either Undertow or Netty). If both the Undertow runtime and Netty runtime are included on the classpath, however, you need to specify explicitly when you want to use the Netty runtime, because the Undertow runtime will be used by default.
In the case where more than one HTTP runtime is available on the classpath, you can select the Undertow runtime by specifying the endpoint URL to have the following format:
netty://http://RestOfURLPayload types
There are three ways of specifying an HTTP endpoint’s address depending on the payload format you are using.
-
SOAP 1.1 uses the standardized
soap:addresselement. -
SOAP 1.2 uses the
soap12:addresselement. -
All other payload formats use the
http:address element.
From Camel 2.16.0 release, Apache Camel CXF Payload supports stream cache out of box.
SOAP 1.1
When you are sending SOAP 1.1 messages over HTTP you must use the SOAP 1.1 address element to specify the endpoint’s address. It has one attribute, location, that specifies the endpoint’s address as a URL. The SOAP 1.1 address element is defined in the namespace http://schemas.xmlsoap.org/wsdl/soap/.
Example 12.1, “SOAP 1.1 Port Element” shows a port element used to send SOAP 1.1 messages over HTTP.
Example 12.1. SOAP 1.1 Port Element
<definitions ...
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" ...>
...
<service name="SOAP11Service">
<port binding="SOAP11Binding" name="SOAP11Port">
<soap:address location="http://artie.com/index.xml">
</port>
</service>
...
<definitions>SOAP 1.2
When you are sending SOAP 1.2 messages over HTTP you must use the SOAP 1.2 address element to specify the endpoint’s address. It has one attribute, location, that specifies the endpoint’s address as a URL. The SOAP 1.2 address element is defined in the namespace http://schemas.xmlsoap.org/wsdl/soap12/.
Example 12.2, “SOAP 1.2 Port Element” shows a port element used to send SOAP 1.2 messages over HTTP.
Example 12.2. SOAP 1.2 Port Element
<definitions ...
xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" ... >
<service name="SOAP12Service">
<port binding="SOAP12Binding" name="SOAP12Port">
<soap12:address location="http://artie.com/index.xml">
</port>
</service>
...
</definitions>Other messages types
When your messages are mapped to any payload format other than SOAP you must use the HTTP address element to specify the endpoint’s address. It has one attribute, location, that specifies the endpoint’s address as a URL. The HTTP address element is defined in the namespace http://schemas.xmlsoap.org/wsdl/http/.
Example 12.3, “HTTP Port Element” shows a port element used to send an XML message.
Example 12.3. HTTP Port Element
<definitions ...
xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" ... >
<service name="HTTPService">
<port binding="HTTPBinding" name="HTTPPort">
<http:address location="http://artie.com/index.xml">
</port>
</service>
...
</definitions>12.2. Configuring a Consumer
12.2.1. Mechanisms for HTTP Consumer Endpoints
HTTP consumer endpoints can specify a number of HTTP connection attributes including whether the endpoint automatically accepts redirect responses, whether the endpoint can use chunking, whether the endpoint will request a keep-alive, and how the endpoint interacts with proxies. In addition to the HTTP connection properties, an HTTP consumer endpoint can specify how it is secured.
A consumer endpoint can be configured using two mechanisms:
12.2.2. Using Configuration
Namespace
The elements used to configure an HTTP consumer endpoint are defined in the namespace http://cxf.apache.org/transports/http/configuration. It is commonly referred to using the prefix http-conf. In order to use the HTTP configuration elements you must add the lines shown in Example 12.4, “HTTP Consumer 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.4. HTTP Consumer Configuration Namespace
<beans ...
xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"
...
xsi:schemaLocation="...
http://cxf.apache.org/transports/http/configuration
http://cxf.apache.org/schemas/configuration/http-conf.xsd
...">Undertow runtime or Netty runtime
You can use the elements from the http-conf namespace to configure either the Undertow runtime or the Netty runtime.
The conduit element
You configure an HTTP consumer endpoint using the http-conf:conduit element and its children. The http-conf:conduit element takes a single attribute, name, that specifies the WSDL port element corresponding to the endpoint. The value for the name attribute takes the form portQName`.http-conduit`. Example 12.5, “http-conf:conduit Element” shows the http-conf:conduit element that would be used to add configuration for an endpoint that is specified by the WSDL fragment <port binding="widgetSOAPBinding" name="widgetSOAPPort> when the endpoint’s target namespace is http://widgets.widgetvendor.net.
Example 12.5. http-conf:conduit Element
...
<http-conf:conduit name="{http://widgets/widgetvendor.net}widgetSOAPPort.http-conduit">
...
</http-conf:conduit>
...
The http-conf:conduit element has child elements that specify configuration information. They are described in Table 12.1, “Elements Used to Configure an HTTP Consumer Endpoint”.
| Element | Description |
|---|---|
|
| Specifies the HTTP connection properties such as timeouts, keep-alive requests, content types, etc. See the section called “The client element”. |
|
Specifies the parameters for configuring the basic authentication method that the endpoint uses preemptively. The preferred approach is to supply a | |
| Specifies the parameters for configuring basic authentication against outgoing HTTP proxy servers. | |
| Specifies the parameters used to configure SSL/TLS. | |
| Specifies the bean reference or class name of the object that supplies the basic authentication information used by the endpoint, either preemptively or in response to a 401 HTTP challenge. | |
|
Specifies the bean reference or class name of the object that checks the HTTP(S) |
The client element
The http-conf:client element is used to configure the non-security properties of a consumer endpoint’s HTTP connection. Its attributes, described in Table 12.2, “HTTP Consumer Configuration Attributes”, specify the connection’s properties.
| Attribute | Description |
|---|---|
|
Specifies the amount of time, in milliseconds, that the consumer attempts to establish a connection before it times out. The default is
| |
|
Specifies the amount of time, in milliseconds, that the consumer will wait for a response before it times out. The default is
| |
|
Specifies if the consumer will automatically follow a server issued redirection. The default is | |
|
Specifies the maximum number of times a consumer will retransmit a request to satisfy a redirect. The default is | |
|
Specifies whether the consumer will send requests using chunking. The default is Chunking cannot be used if either of the following are true:
In both cases the value of | |
|
Specifies what media types the consumer is prepared to handle. The value is used as the value of the HTTP | |
|
Specifies what language (for example, American English) the consumer prefers for the purpose of receiving a response. The value is used as the value of the HTTP Language tags are regulated by the International Organization for Standards (ISO) and are typically formed by combining a language code, determined by the ISO-639 standard, and country code, determined by the ISO-3166 standard, separated by a hyphen. For example, en-US represents American English. | |
|
Specifies what content encodings the consumer is prepared to handle. Content encoding labels are regulated by the Internet Assigned Numbers Authority (IANA). The value is used as the value of the HTTP | |
|
Specifies the media type of the data being sent in the body of a message. Media types are specified using multipurpose internet mail extensions (MIME) types. The value is used as the value of the HTTP
For web services, this should be set to | |
|
Specifies the Internet host and port number of the resource on which the request is being invoked. The value is used as the value of the HTTP This attribute is typically not required. It is only required by certain DNS scenarios or application designs. For example, it indicates what host the client prefers for clusters (that is, for virtual servers mapping to the same Internet protocol (IP) address). | |
| Specifies whether a particular connection is to be kept open or closed after each request/response dialog. There are two valid values:
| |
| Specifies directives about the behavior that must be adhered to by caches involved in the chain comprising a request from a consumer to a service provider. See Section 12.2.4, “Consumer Cache Control Directives”. | |
| Specifies a static cookie to be sent with all requests. | |
| Specifies information about the browser from which the request originates. In the HTTP specification from the World Wide Web consortium (W3C) this is also known as the user-agent. Some servers optimize based on the client that is sending the request. | |
|
Specifies the URL of the resource that directed the consumer to make requests on a particular service. The value is used as the value of the HTTP This HTTP property is used when a request is the result of a browser user clicking on a hyperlink rather than typing a URL. This can allow the server to optimize processing based upon previous task flow, and to generate lists of back-links to resources for the purposes of logging, optimized caching, tracing of obsolete or mistyped links, and so on. However, it is typically not used in web services applications.
If the | |
| Specifies the URL of a decoupled endpoint for the receipt of responses over a separate provider→consumer connection. For more information on using decoupled endpoints see, Section 12.6, “Using the HTTP Transport in Decoupled Mode”. You must configure both the consumer endpoint and the service provider endpoint to use WS-Addressing for the decoupled endpoint to work. | |
| Specifies the URL of the proxy server through which requests are routed. | |
| Specifies the port number of the proxy server through which requests are routed. | |
| Specifies the type of proxy server used to route requests. Valid values are:
|
Example
Example 12.6, “HTTP Consumer Endpoint Configuration” shows the configuration of an HTTP consumer endpoint that wants to keep its connection to the provider open between requests, that will only retransmit requests once per invocation, and that cannot use chunking streams.
Example 12.6. HTTP Consumer Endpoint Configuration
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"
xsi:schemaLocation="http://cxf.apache.org/transports/http/configuration
http://cxf.apache.org/schemas/configuration/http-conf.xsd
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">
<http-conf:conduit name="{http://apache.org/hello_world_soap_http}SoapPort.http-conduit">
<http-conf:client Connection="Keep-Alive"
MaxRetransmits="1"
AllowChunking="false" />
</http-conf:conduit>
</beans>More information
For more information on HTTP conduits see Chapter 16, Conduits.
12.2.3. Using WSDL
Namespace
The WSDL extension elements used to configure an HTTP consumer endpoint are defined in the namespace http://cxf.apache.org/transports/http/configuration. It is commonly referred to using the prefix http-conf. In order to use the HTTP configuration elements you must add the line shown in Example 12.7, “HTTP Consumer WSDL Element’s Namespace” to the definitions element of your endpoint’s WSDL document.
Example 12.7. HTTP Consumer WSDL Element’s Namespace
<definitions ...
xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"Undertow runtime or Netty runtime
You can use the elements from the http-conf namespace to configure either the Undertow runtime or the Netty runtime.
The client element
The http-conf:client element is used to specify the connection properties of an HTTP consumer in a WSDL document. The http-conf:client element is a child of the WSDL port element. It has the same attributes as the client element used in the configuration file. The attributes are described in Table 12.2, “HTTP Consumer Configuration Attributes”.
Example
Example 12.8, “WSDL to Configure an HTTP Consumer Endpoint” shows a WSDL fragment that configures an HTTP consumer endpoint to specify that it does not interact with caches.
Example 12.8. WSDL to Configure an HTTP Consumer Endpoint
<service ... >
<port ... >
<soap:address ... />
<http-conf:client CacheControl="no-cache" />
</port>
</service>12.2.4. Consumer Cache Control Directives
Table 12.3, “http-conf:client Cache Control Directives” lists the cache control directives supported by an HTTP consumer.
| Directive | Behavior |
|---|---|
| no-cache | Caches cannot use a particular response to satisfy subsequent requests without first revalidating that response with the server. If specific response header fields are specified with this value, the restriction applies only to those header fields within the response. If no response header fields are specified, the restriction applies to the entire response. |
| no-store | Caches must not store either any part of a response or any part of the request that invoked it. |
| max-age | The consumer can accept a response whose age is no greater than the specified time in seconds. |
| max-stale | The consumer can accept a response that has exceeded its expiration time. If a value is assigned to max-stale, it represents the number of seconds beyond the expiration time of a response up to which the consumer can still accept that response. If no value is assigned, the consumer can accept a stale response of any age. |
| min-fresh | The consumer wants a response that is still fresh for at least the specified number of seconds indicated. |
| no-transform | Caches must not modify media type or location of the content in a response between a provider and a consumer. |
| only-if-cached | Caches should return only responses that are currently stored in the cache, and not responses that need to be reloaded or revalidated. |
| cache-extension | Specifies additional extensions to the other cache directives. Extensions can be informational or behavioral. An extended directive is specified in the context of a standard directive, so that applications not understanding the extended directive can adhere to the behavior mandated by the standard directive. |
12.3. Configuring a Service Provider
12.3.1. Mechanisms for a HTTP Service Provider
HTTP service provider endpoints can specify a number of HTTP connection attributes including if it will honor keep alive requests, how it interacts with caches, and how tolerant it is of errors in communicating with a consumer.
A service provider endpoint can be configured using two mechanisms:
12.3.2. Using Configuration
Namespace
The elements used to configure an HTTP provider endpoint are defined in the namespace http://cxf.apache.org/transports/http/configuration. It is commonly referred to using the prefix http-conf. In order to use the HTTP configuration elements you must add the lines shown in Example 12.9, “HTTP Provider 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.9. HTTP Provider Configuration Namespace
<beans ...
xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"
...
xsi:schemaLocation="...
http://cxf.apache.org/transports/http/configuration
http://cxf.apache.org/schemas/configuration/http-conf.xsd
...">Undertow runtime or Netty runtime
You can use the elements from the http-conf namespace to configure either the Undertow runtime or the Netty runtime.
The destination element
You configure an HTTP service provider endpoint using the http-conf:destination element and its children. The http-conf:destination element takes a single attribute, name, that specifies the WSDL port element that corresponds to the endpoint. The value for the name attribute takes the form portQName`.http-destination`. Example 12.10, “http-conf:destination Element” shows the http-conf:destination element that is used to add configuration for an endpoint that is specified by the WSDL fragment <port binding="widgetSOAPBinding" name="widgetSOAPPort> when the endpoint’s target namespace is http://widgets.widgetvendor.net.
Example 12.10. http-conf:destination Element
...
<http-conf:destination name="{http://widgets/widgetvendor.net}widgetSOAPPort.http-destination">
...
</http-conf:destination>
...
The http-conf:destination element has a number of child elements that specify configuration information. They are described in Table 12.4, “Elements Used to Configure an HTTP Service Provider Endpoint”.
| Element | Description |
|---|---|
| Specifies the HTTP connection properties. See the section called “The server element”. | |
| Specifies the parameters that configure the context match strategy for processing HTTP requests. | |
| Specifies whether the parameter order of an HTTP request handled by this destination is fixed. |
The server element
The http-conf:server element is used to configure the properties of a service provider endpoint’s HTTP connection. Its attributes, described in Table 12.5, “HTTP Service Provider Configuration Attributes”, specify the connection’s properties.
| Attribute | Description |
|---|---|
|
Sets the length of time, in milliseconds, the service provider attempts to receive a request before the connection times out. The default is
| |
|
Specifies whether exceptions are to be thrown when an error is encountered on receiving a request. The default is | |
|
Specifies whether exceptions are to be thrown when an error is encountered on sending a response to a consumer. The default is | |
|
Specifies whether the service provider honors requests for a connection to remain open after a response has been sent. The default is | |
| Specifies the URL to which the client request should be redirected if the URL specified in the client request is no longer appropriate for the requested resource. In this case, if a status code is not automatically set in the first line of the server response, the status code is set to 302 and the status description is set to Object Moved. The value is used as the value of the HTTP RedirectURL property. | |
| Specifies directives about the behavior that must be adhered to by caches involved in the chain comprising a response from a service provider to a consumer. See Section 12.3.4, “Service Provider Cache Control Directives”. | |
| Sets the URL where the resource being sent in a response is located. | |
| Specifies the media type of the information being sent in a response. Media types are specified using multipurpose internet mail extensions (MIME) types. The value is used as the value of the HTTP ContentType location. | |
| Specifies any additional content encodings that have been applied to the information being sent by the service provider. Content encoding labels are regulated by the Internet Assigned Numbers Authority (IANA). Possible content encoding values include zip, gzip, compress, deflate, and identity. This value is used as the value of the HTTP ContentEncoding property. The primary use of content encodings is to allow documents to be compressed using some encoding mechanism, such as zip or gzip. Apache CXF performs no validation on content codings. It is the user’s responsibility to ensure that a specified content coding is supported at application level. | |
|
Specifies what type of server is sending the response. Values take the form |
Example
Example 12.11, “HTTP Service Provider Endpoint Configuration” shows the configuration for an HTTP service provider endpoint that honors keep-alive requests and suppresses all communication errors.
Example 12.11. HTTP Service Provider Endpoint Configuration
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"
xsi:schemaLocation="http://cxf.apache.org/transports/http/configuration
http://cxf.apache.org/schemas/configuration/http-conf.xsd
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">
<http-conf:destination name="{http://apache.org/hello_world_soap_http}SoapPort.http-destination">
<http-conf:server SuppressClientSendErrors="true"
SuppressClientReceiveErrors="true"
HonorKeepAlive="true" />
</http-conf:destination>
</beans>12.3.3. Using WSDL
Namespace
The WSDL extension elements used to configure an HTTP provider endpoint are defined in the namespace http://cxf.apache.org/transports/http/configuration. It is commonly referred to using the prefix http-conf. To use the HTTP configuration elements you must add the line shown in Example 12.12, “HTTP Provider WSDL Element’s Namespace” to the definitions element of your endpoint’s WSDL document.
Example 12.12. HTTP Provider WSDL Element’s Namespace
<definitions ...
xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"Undertow runtime or Netty runtime
You can use the elements from the http-conf namespace to configure either the Undertow runtime or the Netty runtime.
The server element
The http-conf:server element is used to specify the connection properties of an HTTP service provider in a WSDL document. The http-conf:server element is a child of the WSDL port element. It has the same attributes as the server element used in the configuration file. The attributes are described in Table 12.5, “HTTP Service Provider Configuration Attributes”.
Example
Example 12.13, “WSDL to Configure an HTTP Service Provider Endpoint” shows a WSDL fragment that configures an HTTP service provider endpoint specifying that it will not interact with caches.
Example 12.13. WSDL to Configure an HTTP Service Provider Endpoint
<service ... >
<port ... >
<soap:address ... />
<http-conf:server CacheControl="no-cache" />
</port>
</service>12.3.4. Service Provider Cache Control Directives
Table 12.6, “http-conf:server Cache Control Directives” lists the cache control directives supported by an HTTP service provider.
| Directive | Behavior |
|---|---|
| no-cache | Caches cannot use a particular response to satisfy subsequent requests without first revalidating that response with the server. If specific response header fields are specified with this value, the restriction applies only to those header fields within the response. If no response header fields are specified, the restriction applies to the entire response. |
| public | Any cache can store the response. |
| private | Public (shared) caches cannot store the response because the response is intended for a single user. If specific response header fields are specified with this value, the restriction applies only to those header fields within the response. If no response header fields are specified, the restriction applies to the entire response. |
| no-store | Caches must not store any part of the response or any part of the request that invoked it. |
| no-transform | Caches must not modify the media type or location of the content in a response between a server and a client. |
| must-revalidate | Caches must revalidate expired entries that relate to a response before that entry can be used in a subsequent response. |
| proxy-revalidate | Does the same as must-revalidate, except that it can only be enforced on shared caches and is ignored by private unshared caches. When using this directive, the public cache directive must also be used. |
| max-age | Clients can accept a response whose age is no greater that the specified number of seconds. |
| s-max-age | Does the same as max-age, except that it can only be enforced on shared caches and is ignored by private unshared caches. The age specified by s-max-age overrides the age specified by max-age. When using this directive, the proxy-revalidate directive must also be used. |
| cache-extension | Specifies additional extensions to the other cache directives. Extensions can be informational or behavioral. An extended directive is specified in the context of a standard directive, so that applications not understanding the extended directive can adhere to the behavior mandated by the standard directive. |
12.4. Configuring the Undertow Runtime
Overview
The Undertow 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 Undertow runtime.
Maven dependency
If you use Apache Maven as your build system, you can add the Undertow runtime 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-undertow</artifactId>
<version>${cxf-version}</version>
</dependency>Namespace
The elements used to configure the Undertow runtime are defined in the namespace http://cxf.apache.org/transports/http-undertow/configuration. In order to use the Undertow configuration elements you must add the lines shown in Example 12.14, “Undertow Runtime Configuration Namespace” to the beans element of your endpoint’s configuration file. In this example, the namespace is assigned the prefix httpu. In addition, you must add the configuration element’s namespace to the xsi:schemaLocation attribute.
Example 12.14. Undertow Runtime Configuration Namespace
<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
...">The engine-factory element
The httpu:engine-factory element is the root element used to configure the Undertow runtime used by an application. It has a single required attribute, bus, whose value is the name of the Bus that manages the Undertow instances being configured.
The value is typically cxf which is the name of the default Bus instance.
The http:engine-factory element has three children that contain the information used to configure the HTTP ports instantiated by the Undertow runtime factory. The children are described in Table 12.7, “Elements for Configuring a Undertow Runtime Factory”.
| Element | Description |
|---|---|
|
| Specifies the configuration for a particular Undertow runtime instance. See the section called “The engine element”. |
|
Specifies a reusable set of properties for securing an HTTP service provider. It has a single attribute, | |
|
Specifies a reusable set of properties for controlling a Undertow instance’s thread pool. It has a single attribute, |
The engine element
The httpu:engine element is used to configure specific instances of the Undertow runtime. It has a single attribute, port, that specifies the number of the port being managed by the Undertow instance.
You can specify a value of 0 for the port attribute. Any threading properties specified in an httpu:engine element with its port attribute set to 0 are used as the configuration for all Undertow listeners that are not explicitly configured.
Each httpu:engine element can have two children: one for configuring security properties and one for configuring the Undertow 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 httpu:engine-factory element.
The child elements used to provide the configuration properties are described in Table 12.8, “Elements for Configuring an Undertow Runtime Instance”.
| Element | Description |
|---|---|
| Specifies a set of properties for configuring the security used for the specific Undertow instance. | |
|
Refers to a set of security properties defined by a | |
| Specifies the size of the thread pool used by the specific Undertow instance. See the section called “Configuring the thread pool”. | |
|
Refers to a set of properties defined by a |
Configuring the thread pool
You can configure the size of an Undertow instance’s thread pool by either:
-
Specifying the size of the thread pool using a
identifiedThreadingParameterselement in theengine-factoryelement. You then refer to the element using athreadingParametersRefelement. -
Specifying the size of the of the thread pool directly using a
threadingParameterselement.
The threadingParameters has two attributes to specify the size of a thread pool. The attributes are described in Table 12.9, “Attributes for Configuring an Undertow Thread Pool”.
The httpu:identifiedThreadingParameters element has a single child threadingParameters element.
| Attribute | Description |
|---|---|
| Specifies the number of I/O threads to be created for the worker. If not specified, the dafult value will be chosen. The default value is one I/O thread per CPU core. | |
| Specifies the minimum number of threads available to the Undertow instance for processing requests. | |
| Specifies the maximum number of threads available to the Undertow instance for processing requests. |
Example
Example 12.15, “Configuring an Undertow Instance” shows a configuration fragment that configures an Undertow instance on port number 9001.
Example 12.15. Configuring an Undertow Instance
<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>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.
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”.
| Element | Description |
|---|---|
|
| Specifies the configuration for a particular Netty runtime instance. See the section called “The engine element”. |
|
Specifies a reusable set of properties for securing an HTTP service provider. It has a single attribute, | |
|
Specifies a reusable set of properties for controlling a Netty instance’s thread pool. It has a single attribute, |
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.
| Attribute | Description |
|---|---|
|
|
Specifies the port used by the Netty HTTP server instance. You can specify a value of |
|
| 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. |
|
| Specifies the maximum read idle time for a Netty connection. The timer is reset whenever there are any read actions on the underlying stream. |
|
| Specifies the maximum write idle time for a Netty connection. The timer is reset whenever there are any write actions on the underlying stream. |
|
| 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”.
| Element | Description |
|---|---|
| Specifies a set of properties for configuring the security used for the specific Netty instance. | |
|
Refers to a set of security properties defined by a | |
| Specifies the size of the thread pool used by the specific Netty instance. See the section called “Configuring the thread pool”. | |
|
Refers to a set of properties defined by a | |
|
|
When |
|
|
Specifies a boolean value to set the |
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
identifiedThreadingParameterselement in theengine-factoryelement. You then refer to the element using athreadingParametersRefelement. -
Specifying the size of the of the thread pool directly using a
threadingParameterselement.
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”.
The httpn:identifiedThreadingParameters element has a single child threadingParameters element.
| Attribute | Description |
|---|---|
|
| 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>12.6. Using the HTTP Transport in Decoupled Mode
Overview
In normal HTTP request/response scenarios, the request and the response are sent using the same HTTP connection. The service provider processes the request and responds with a response containing the appropriate HTTP status code and the contents of the response. In the case of a successful request, the HTTP status code is set to 200.
In some instances, such as when using WS-RM or when requests take an extended period of time to execute, it makes sense to decouple the request and response message. In this case the service providers sends the consumer a 202 Accepted response to the consumer over the back-channel of the HTTP connection on which the request was received. It then processes the request and sends the response back to the consumer using a new decoupled server→client HTTP connection. The consumer runtime receives the incoming response and correlates it with the appropriate request before returning to the application code.
Configuring decoupled interactions
Using the HTTP transport in decoupled mode requires that you do the following:
Configure the consumer to use WS-Addressing.
See the section called “Configuring an endpoint to use WS-Addressing”.
Configure the consumer to use a decoupled endpoint.
Configure any service providers that the consumer interacts with to use WS-Addressing.
See the section called “Configuring an endpoint to use WS-Addressing”.
Configuring an endpoint to use WS-Addressing
Specify that the consumer and any service provider with which the consumer interacts use WS-Addressing.
You can specify that an endpoint uses WS-Addressing in one of two ways:
Adding the
wswa:UsingAddressingelement to the endpoint’s WSDLportelement as shown in Example 12.18, “Activating WS-Addressing using WSDL”.Example 12.18. Activating WS-Addressing using WSDL
... <service name="WidgetSOAPService"> <port name="WidgetSOAPPort" binding="tns:WidgetSOAPBinding"> <soap:address="http://widgetvendor.net/widgetSeller" /> <wswa:UsingAddressing xmlns:wswa="http://www.w3.org/2005/02/addressing/wsdl"/> </port> </service> ...Adding the WS-Addressing policy to the endpoint’s WSDL
portelement as shown in Example 12.19, “Activating WS-Addressing using a Policy”.Example 12.19. Activating WS-Addressing using a Policy
... <service name="WidgetSOAPService"> <port name="WidgetSOAPPort" binding="tns:WidgetSOAPBinding"> <soap:address="http://widgetvendor.net/widgetSeller" /> <wsp:Policy xmlns:wsp="http://www.w3.org/2006/07/ws-policy"> <wsam:Addressing xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata"> <wsp:Policy/> </wsam:Addressing> </wsp:Policy> </port> </service> ...
The WS-Addressing policy supersedes the wswa:UsingAddressing WSDL element.
Configuring the consumer
Configure the consumer endpoint to use a decoupled endpoint using the DecoupledEndpoint attribute of the http-conf:conduit element.
Example 12.20, “Configuring a Consumer to Use a Decoupled HTTP Endpoint” shows the configuration for setting up the endpoint defined in Example 12.18, “Activating WS-Addressing using WSDL” to use use a decoupled endpoint. The consumer now receives all responses at http://widgetvendor.net/widgetSellerInbox.
Example 12.20. Configuring a Consumer to Use a Decoupled HTTP Endpoint
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:http="http://cxf.apache.org/transports/http/configuration"
xsi:schemaLocation="http://cxf.apache.org/transports/http/configuration
http://cxf.apache.org/schemas/configuration/http-conf.xsd
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">
<http:conduit name="{http://widgetvendor.net/services}WidgetSOAPPort.http-conduit">
<http:client DecoupledEndpoint="http://widgetvendor.net:9999/decoupled_endpoint" />
</http:conduit>
</beans>How messages are processed
Using the HTTP transport in decoupled mode adds extra layers of complexity to the processing of HTTP messages. While the added complexity is transparent to the implementation level code in an application, it might be important to understand what happens for debugging reasons.
Figure 12.1, “Message Flow in for a Decoupled HTTP Transport” shows the flow of messages when using HTTP in decoupled mode.
Figure 12.1. Message Flow in for a Decoupled HTTP Transport
A request starts the following process:
- The consumer implementation invokes an operation and a request message is generated.
The WS-Addressing layer adds the WS-A headers to the message.
When a decoupled endpoint is specified in the consumer’s configuration, the address of the decoupled endpoint is placed in the WS-A ReplyTo header.
- The message is sent to the service provider.
- The service provider receives the message.
- The request message from the consumer is dispatched to the provider’s WS-A layer.
- Because the WS-A ReplyTo header is not set to anonymous, the provider sends back a message with the HTTP status code set to 202, acknowledging that the request has been received.
- The HTTP layer sends a 202 Accepted message back to the consumer using the original connection’s back-channel.
The consumer receives the 202 Accepted reply on the back-channel of the HTTP connection used to send the original message.
When the consumer receives the 202 Accepted reply, the HTTP connection closes.
- The request is passed to the service provider’s implementation where the request is processed.
- When the response is ready, it is dispatched to the WS-A layer.
- The WS-A layer adds the WS-Addressing headers to the response message.
- The HTTP transport sends the response to the consumer’s decoupled endpoint.
- The consumer’s decoupled endpoint receives the response from the service provider.
- The response is dispatched to the consumer’s WS-A layer where it is correlated to the proper request using the WS-A RelatesTo header.
- The correlated response is returned to the client implementation and the invoking call is unblocked.
