41.4. Handling HTTP Headers

Overview

When building bridge applications using HTTP or HTTP-based components, it is important to be aware of how the HTTP-based endpoints process headers. In many cases, internal headers (prefixed by Camel) or other headers can cause unwanted side-effects on your application. It is often necessary to remove or filter out certain headings or classes of headings in your route, in order to ensure that your application behaves as expected.

HTTP-based components

The behavior described in this section affects not just the Camel HTTP component (camel-http), but also a number of other HTTP-based components, including:
camel-http
camel-http4
camel-jetty
camel-restlet
camel-cxf
camel-cxfrs

HTTP headers in Camel CXF

The Camel CXF component copies HTTP headers into message headers for all of the supported data formats:
  • POJO
  • PAYLOAD
  • MESSAGE

HTTP consumer endpoint

When a HTTP consumer endpoint receives an incoming message, it creates an In message with the following headers:
CamelHttp* headers
Several headers with the CamelHttp prefix are created, which record the status of the incoming message. For details of these internal headers, see HTTP.
HTTP headers
All of the HTTP headers from the original incoming message are mapped to headers on the exchange's In message.
URL options (Jetty only)
The URL options from the original HTTP request URL are mapped to headers on the exchange's In message. For example, given the client request with the URL, http://myserver/myserver?orderid=123, a Jetty consumer endpoint creates the orderid header with value 123.

HTTP producer endpoint

When a HTTP producer endpoint receives an exchange and converts it to the target message format, it handles the In message headers as follows:
CamelHttp*
Headers prefixed by CamelHttp are used to control the behaviour of the HTTP producer endpoint. Any headers of this kind are consumed by the HTTP producer endpoint and the endpoint behaves as directed.
Note
However, CamelHttp message headers are ignored by Camel CXF producer endpoints (but not by Camel CXF-RS producer endpoints).
Camel*
All other headers prefixed by Camel are presumed to be meant for internal use and are not mapped to HTTP headers in the target message (in other words, these headers are ignored).
*
All other headers are converted to HTTP headers in the target message, with the exception of the following headers, which are blocked (based on a case-insensitive match):
content-length
content-type
cache-control
connection
date
pragma
trailer
transfer-encoding
upgrade
via
warning

Implications for HTTP bridge applications

When defining a HTTP bridge application (that is, a route starting with a HTTP consumer endpoint and ending with a HTTP producer endpoint), the CamelHttp* headers set by the consumer endpoint at the start of the route can affect the behavior of the producer endpoint. For this reason, in a bridge application it is advisable to remove the CamelHttp* headers, as follows:
from("http://0.0.0.0/context/path")
  .removeHeaders("CamelHttp*)
  ...
  .to("http://remoteHost/context/path");

Setting a custom header filter

If you want to customize the way that a HTTP producer endpoint processes headers, you can define your own customer header filter by defining the headerFilterStrategy option on the endpoint URI. For example, to configure a producer endpoint with the myHeaderFilterStrategy filter, you could use a URI like the following:
http://remoteHost/context/path?headerFilterStrategy=#myHeaderFilterStrategy
Where myHeaderFilterStrategy is the bean ID of your custom filter instance.