Undertow Component

Table of Contents

URI format
Options
Message Headers
Producer Example
Consumer Example
See Also

Available as of Camel 2.16

The undertow component provides HTTP-based endpoints for consuming and producing HTTP requests. That is, the Undertow component behaves as a simple Web server. Undertow can also be used as a http client which mean you can also use it with Camel as a producer.

Maven users will need to add the following dependency to their pom.xml for this component:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-undertow</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>

URI format

undertow:http://hostname[:port][/resourceUri][?options]

You can append query options to the URI in the following format, ?option=value&option=value&…

Options

The Undertow component supports 2 options which are listed below.

{% raw %}

Name	Java Type	Description
undertowHttpBinding	`UndertowHttpBinding`	To use a custom HttpBinding to control the mapping between Camel message and HttpClient.
sslContextParameters	`SSLContextParameters`	To configure security using SSLContextParameters

{% endraw %}

The Undertow component supports 17 endpoint options which are listed below:

{% raw %}

Name	Group	Default	Java Type	Description
httpURI	common		`URI`	Required The url of the HTTP endpoint to use.
bridgeErrorHandler	consumer	`false`	`boolean`	Allows for bridging the consumer to the Camel routing Error Handler which mean any exceptions occurred while the consumer is trying to pickup incoming messages or the likes will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions that will be logged at WARN/ERROR level and ignored.
httpMethodRestrict	consumer		`String`	Used to only allow consuming if the HttpMethod matches such as GET/POST/PUT etc. Multiple methods can be specified separated by comma.
matchOnUriPrefix	consumer	`true`	`Boolean`	Whether or not the consumer should try to find a target consumer by matching the URI prefix if no exact match is found.
optionsEnabled	consumer	`false`	`boolean`	Specifies whether to enable HTTP OPTIONS for this Servlet consumer. By default OPTIONS is turned off.
exceptionHandler	consumer (advanced)		`ExceptionHandler`	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions that will be logged at WARN/ERROR level and ignored.
exchangePattern	consumer (advanced)		`ExchangePattern`	Sets the exchange pattern when the consumer creates an exchange.
keepAlive	producer	`true`	`Boolean`	Setting to ensure socket is not closed due to inactivity
options	producer		`Map`	Sets additional channel options. The options that can be used are defined in org.xnio.Options. To configure from endpoint uri then prefix each option with option. such as option.close-abort=true&option.send-buffer=8192
reuseAddresses	producer	`true`	`Boolean`	Setting to facilitate socket multiplexing
tcpNoDelay	producer	`true`	`Boolean`	Setting to improve TCP protocol performance
throwExceptionOnFailure	producer	`true`	`Boolean`	If the option is true HttpProducer will ignore the Exchange.HTTP_URI header and use the endpoint’s URI for request. You may also set the option throwExceptionOnFailure to be false to let the producer send all the fault response back.
transferException	producer	`false`	`Boolean`	Option to disable throwing the HttpOperationFailedException in case of failed responses from the remote server. This allows you to get all responses regardless of the HTTP status code.
headerFilterStrategy	advanced		`HeaderFilterStrategy`	To use a custom HeaderFilterStrategy to filter header to and from Camel message.
synchronous	advanced	`false`	`boolean`	Sets whether synchronous processing should be strictly used or Camel is allowed to use asynchronous processing (if supported).
undertowHttpBinding	advanced		`UndertowHttpBinding`	To use a custom UndertowHttpBinding to control the mapping between Camel message and undertow.
sslContextParameters	security		`SSLContextParameters`	To configure security using SSLContextParameters

{% endraw %}

Message Headers

Camel uses the same message headers as the HTTP component. From Camel 2.2, it also uses Exchange.HTTP_CHUNKED,CamelHttpChunked header to turn on or turn off the chuched encoding on the camel-undertow consumer.

Camel also populates all request.parameter and request.headers. For example, given a client request with the URL, http://myserver/myserver?orderid=123, the exchange will contain a header named orderid with the value 123.

Producer Example

The following is a basic example of how to send an HTTP request to an existing HTTP endpoint.

in Java DSL

from("direct:start").to("undertow:http://www.google.com");

or in Spring XML

<route>
    <from uri="direct:start"/>
    <to uri="undertow:http://www.google.com"/>
<route>

Consumer Example

In this sample we define a route that exposes a HTTP service at http://localhost:8080/myapp/myservice:

<route>
  <from uri="undertow:http://localhost:8080/myapp/myservice"/>
  <to uri="bean:myBean"/>
</route>

NOTE:*Usage of localhost* When you specify localhost in a URL, Camel exposes the endpoint only on the local TCP/IP network interface, so it cannot be accessed from outside the machine it operates on.

If you need to expose a Jetty endpoint on a specific network interface, the numerical IP address of this interface should be used as the host. If you need to expose a Jetty endpoint on all network interfaces, the 0.0.0.0 address should be used.

TIP:To listen across an entire URI prefix, see How do I let Jetty match wildcards.

TIP:If you actually want to expose routes by HTTP and already have a Servlet, you should instead refer to the Servlet Transport.