Chapter 12. Using HTTP
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: Payload 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:address element. SOAP 1.2 uses the soap12:address element. All other payload formats use the http:address element. Note 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 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 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 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: Configuration WSDL 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 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 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" . Table 12.1. Elements Used to Configure an HTTP Consumer Endpoint Element Description http-conf:client Specifies the HTTP connection properties such as timeouts, keep-alive requests, content types, etc. See the section called "The client element" . http-conf:authorization Specifies the parameters for configuring the basic authentication method that the endpoint uses preemptively. The preferred approach is to supply a http-conf:basicAuthSupplier object. http-conf:proxyAuthorization Specifies the parameters for configuring basic authentication against outgoing HTTP proxy servers. http-conf:tlsClientParameters Specifies the parameters used to configure SSL/TLS. http-conf:basicAuthSupplier 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. http-conf:trustDecider Specifies the bean reference or class name of the object that checks the HTTP(S) URLConnection object to establish trust for a connection with an HTTPS service provider before any information is transmitted. 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. Table 12.2. HTTP Consumer Configuration Attributes Attribute Description ConnectionTimeout Specifies the amount of time, in milliseconds, that the consumer attempts to establish a connection before it times out. The default is 30000 . 0 specifies that the consumer will continue to send the request indefinitely. ReceiveTimeout Specifies the amount of time, in milliseconds, that the consumer will wait for a response before it times out. The default is 30000 . 0 specifies that the consumer will wait indefinitely. AutoRedirect Specifies if the consumer will automatically follow a server issued redirection. The default is false . MaxRetransmits Specifies the maximum number of times a consumer will retransmit a request to satisfy a redirect. The default is -1 which specifies that unlimited retransmissions are allowed. AllowChunking Specifies whether the consumer will send requests using chunking. The default is true which specifies that the consumer will use chunking when sending requests. Chunking cannot be used if either of the following are true: http-conf:basicAuthSupplier is configured to provide credentials preemptively. AutoRedirect is set to true . In both cases the value of AllowChunking is ignored and chunking is disallowed. Accept Specifies what media types the consumer is prepared to handle. The value is used as the value of the HTTP Accept property. The value of the attribute is specified using multipurpose internet mail extensions (MIME) types. AcceptLanguage 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 AcceptLanguage property. 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. AcceptEncoding 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 AcceptEncoding property. ContentType 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 ContentType property. The default is text/xml . For web services, this should be set to text/xml . If the client is sending HTML form data to a CGI script, this should be set to application/x-www-form-urlencoded . If the HTTP POST request is bound to a fixed payload format (as opposed to SOAP), the content type is typically set to application/octet-stream . Host 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 Host property. 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). Connection Specifies whether a particular connection is to be kept open or closed after each request/response dialog. There are two valid values: Keep-Alive (default) - Specifies that the consumer wants the connection kept open after the initial request/response sequence. If the server honors it, the connection is kept open until the consumer closes it. close - Specifies that the connection to the server is closed after each request/response sequence. CacheControl 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" . Cookie Specifies a static cookie to be sent with all requests. BrowserType 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. Referer 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 Referer property. 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 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 AutoRedirect attribute is set to true and the request is redirected, any value specified in the Referer attribute is overridden. The value of the HTTP Referer property is set to the URL of the service that redirected the consumer's original request. DecoupledEndpoint 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. ProxyServer Specifies the URL of the proxy server through which requests are routed. ProxyServerPort Specifies the port number of the proxy server through which requests are routed. ProxyServerType Specifies the type of proxy server used to route requests. Valid values are: HTTP (default) SOCKS 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 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 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 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. Table 12.3. http-conf:client Cache Control Directives 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: Configuration WSDL 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 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 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" . Table 12.4. Elements Used to Configure an HTTP Service Provider Endpoint Element Description http-conf:server Specifies the HTTP connection properties. See the section called "The server element" . http-conf:contextMatchStrategy Specifies the parameters that configure the context match strategy for processing HTTP requests. http-conf:fixedParameterOrder 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. Table 12.5. HTTP Service Provider Configuration Attributes Attribute Description ReceiveTimeout Sets the length of time, in milliseconds, the service provider attempts to receive a request before the connection times out. The default is 30000 . 0 specifies that the provider will not timeout. SuppressClientSendErrors Specifies whether exceptions are to be thrown when an error is encountered on receiving a request. The default is false ; exceptions are thrown on encountering errors. SuppressClientReceiveErrors Specifies whether exceptions are to be thrown when an error is encountered on sending a response to a consumer. The default is false ; exceptions are thrown on encountering errors. HonorKeepAlive Specifies whether the service provider honors requests for a connection to remain open after a response has been sent. The default is false ; keep-alive requests are ignored. RedirectURL 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. CacheControl 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" . ContentLocation Sets the URL where the resource being sent in a response is located. ContentType 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. ContentEncoding 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. ServerType Specifies what type of server is sending the response. Values take the form program-name / version ; for example, Apache/1.2.5 . 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 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 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 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. Table 12.6. http-conf:server Cache Control Directives 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: 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 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. Note 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" . Table 12.7. Elements for Configuring a Undertow Runtime Factory Element Description httpu:engine Specifies the configuration for a particular Undertow runtime instance. See the section called "The engine element" . httpu: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. httpu:identifiedThreadingParameters Specifies a reusable set of properties for controlling a Undertow 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 httpu:engine element is used to configure specific instances of the Undertow runtime. It has two attributes, host , that specifies the global IP address with embedded undertow and port , that specifies the number of the port being managed by the Undertow instance. Note 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" . Table 12.8. Elements for Configuring an Undertow Runtime Instance Element Description httpu:tlsServerParameters Specifies a set of properties for configuring the security used for the specific Undertow instance. httpu:tlsServerParametersRef Refers to a set of security properties defined by a identifiedTLSServerParameters element. The id attribute provides the id of the referred identifiedTLSServerParameters element. httpu:threadingParameters Specifies the size of the thread pool used by the specific Undertow instance. See the section called "Configuring the thread pool" . httpu:threadingParametersRef Refers to a set of properties defined by a identifiedThreadingParameters element. The id attribute provides the id of the referred identifiedThreadingParameters element. 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 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 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" . Note The httpu:identifiedThreadingParameters element has a single child threadingParameters element. Table 12.9. Attributes for Configuring an Undertow Thread Pool Attribute Description workerIOThreads 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. minThreads Specifies the minimum number of threads available to the Undertow instance for processing requests. maxThreads 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 Limiting concurrent requests and queue size You can configure a Request Limiting Handler which will set limits for the maximum number of concurrent connection requests and the queue size which can be processed by an Undertow server instance. An example of this configuration is shown at Example 12.16, "Limiting connection requests and queue size" Table 12.10. Attributes for configuring the Request Limiting Handler Attribute Description maximumConcurrentRequests Specifies the maximum number of concurrent requests which can be processed by the Undertow instance. If the number of requests exceeds this limit, the requests are queued. queueSize Specifies the total number of requests which may be queued for processing by the Undertow instance. If the number of requests exceeds this limit, the requests are rejected. Example 12.16. Limiting connection requests and queue size 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: 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: 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.17, "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.17. Netty Runtime Configuration Namespace 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.11, "Elements for Configuring a Netty Runtime Factory" . Table 12.11. 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.12, "Attributes for Configuring a Netty Runtime Instance" shows the attributes supported by the httpn:engine element. Table 12.12. 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.13, "Elements for Configuring a Netty Runtime Instance" . Table 12.13. 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.14, "Attributes for Configuring a Netty Thread Pool" . Note The httpn:identifiedThreadingParameters element has a single child threadingParameters element. Table 12.14. 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.18, "Configuring a Netty Instance" shows a configuration fragment that configures a variety of Netty ports. Example 12.18. Configuring a Netty Instance 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. See the section called "Configuring the consumer" . 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:UsingAddressing element to the endpoint's WSDL port element as shown in Example 12.19, "Activating WS-Addressing using WSDL" . Example 12.19. Activating WS-Addressing using WSDL Adding the WS-Addressing policy to the endpoint's WSDL port element as shown in Example 12.20, "Activating WS-Addressing using a Policy" . Example 12.20. Activating WS-Addressing using a Policy Note 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.21, "Configuring a Consumer to Use a Decoupled HTTP Endpoint" shows the configuration for setting up the endpoint defined in Example 12.19, "Activating WS-Addressing using WSDL" to use use a decoupled endpoint. The consumer now receives all responses at http://widgetvendor.net/widgetSellerInbox . Example 12.21. Configuring a Consumer to Use a Decoupled HTTP Endpoint 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.
netty://http:// RestOfURL <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> <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> <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> <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 ..."> <http-conf:conduit name="{http://widgets/widgetvendor.net}widgetSOAPPort.http-conduit"> </http-conf:conduit> <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> <definitions xmlns:http-conf="http://cxf.apache.org/transports/http/configuration" <service ... > <port ... > <soap:address ... /> <http-conf:client CacheControl="no-cache" /> </port> </service> <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 ..."> <http-conf:destination name="{http://widgets/widgetvendor.net}widgetSOAPPort.http-destination"> </http-conf:destination> <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> <definitions xmlns:http-conf="http://cxf.apache.org/transports/http/configuration" <service ... > <port ... > <soap:address ... /> <http-conf:server CacheControl="no-cache" /> </port> </service> <dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-transports-http-undertow</artifactId> <version>USD{cxf-version}</version> </dependency> <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 ..."> <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> <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> <dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-transports-http-netty-server</artifactId> <version>USD{cxf-version}</version> </dependency> <dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-transports-http-netty-client</artifactId> <version>USD{cxf-version}</version> </dependency> <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 ..."> <?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> <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> <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> <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>