This Confluence has been LDAP enabled, if you are an ASF Committer, please use your LDAP Credentials to login. Any problems file an INFRA jira ticket please.

Child pages
  • Netty HTTP

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Wiki Markup
h2. Netty HTTP Component
*Available as of Camel 2.12*

The *netty-http* component is an extension to [Netty] component to facilitiate HTTP transport with [Netty].

This camel component supports both producer and consumer endpoints.

{info:title=Stream}
Netty is stream based, which means the input it receives is submitted to Camel as a stream. That means you will only be able to read the content of the stream *once*.
If you find a situation where the message body appears to be empty or you need to access the data multiple times (eg: doing multicasting, or redelivery error handling)
you should use [Stream Caching] or convert the message body to a {{String}} which is safe to be re-read multiple times.
{info}

Maven users will need to add the following dependency to their {{pom.xml}} for this component:
{code:xml}
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-netty-http</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>
{code}

h3. URI format

The URI scheme for a netty component is as follows

{code}
netty-http:http://localhost:8080[?options]
{code}

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

h3. HTTP Options

{info:title=A lot more options}
*Important:* This component inherits all the options from [Netty]. So make sure to look at the [Netty] documentation as well.
Notice that some options from [Netty] is not applicable when using this [Netty HTTP] component, such as options related to UDP transport.
{info}

{div:class=confluenceTableSmall}
|| Name || Default Value || Description ||
| {{chunked}} | {{true}} | Allow using chunked transfer if the client supports it from the HTTP headers. |
| {{compression}} | {{false}} | Allow using gzip/deflate for compression if the client supports it from the HTTP headers. |
| {{headerFilterStrategy}} | | To use a custom  {{org.apache.camel.spi.HeaderFilterStrategy}} to filter headers. |
| {{httpMethodRestrict}} | | To disable HTTP methods on the Netty HTTP consumer. You can specify multiple separated by comma. |
| {{mapHeaders}} | {{true}} | If this option is enabled, then during binding from Netty to Camel [Message] then the headers will be mapped as well (eg added as header to the Camel [Message] as well). You can turn off this option to disable this. The headers can still be accessed from the {{org.apache.camel.component.netty.http.NettyHttpMessage}} message with the method {{getHttpRequest()}} that returns the Netty HTTP request {{org.jboss.netty.handler.codec.http.HttpRequest}} instance. |
| {{matchOnUriPrefix}} | {{false}} | Whether or not Camel should try to find a target consumer by matching the URI prefix if no exact match is found. See further below for more details. |
| {{nettyHttpBinding}} | | To use a custom {{org.apache.camel.component.netty.http.NettyHttpBinding}} for binding to/from Netty and Camel Message API. |
| {{bridgeEndpoint}} | {{false}} | If the option is {{true}}, the producer will ignore the {{Exchange.HTTP_URI}} header, and use the endpoint's URI for request. You may also set the {{throwExceptionOnFailure}} to be {{false}} to let the producer send all the fault response back. |
| {{throwExceptionOnFailure}} | {{true}} | Option to disable throwing the {{HttpOperationFailedException}} in case of failed responses from the remote server. This allows you to get all responses regardles of the HTTP status code. |
| {{traceEnabled}} | {{false}} | Specifies whether to enable HTTP TRACE for this Netty HTTP consumer. By default TRACE is turned off. |
| {{transferException}} | {{false}} | If enabled and an [Exchange] failed processing on the consumer side, and if the caused Exception was send back serialized in the response as a {{application/x-java-serialized-object}} content type. On the producer side the exception will be deserialized and thrown as is, instead of the {{HttpOperationFailedException}}. The caused exception is required to be serialized. |
| {{urlDecodeHeaders}} | {{true}} | If this option is enabled, then during binding from Netty to Camel [Message] then the header values will be URL decoded (eg %20 will be a space character. Notice this option is used by the default {{org.apache.camel.component.netty.http.NettyHttpBinding}} and therefore if you implement a custom {{org.apache.camel.component.netty.http.NettyHttpBinding}} then you would need to decode the headers accordingly to this option. |
{div}

h3. Message Headers

The following headers can be used on the producer to control the HTTP request.

{div:class=confluenceTableSmall}
|| Name || Type || Description ||
| {{CamelHttpMethod}} | {{String}} | Allow to control what HTTP method to use such as GET, POST, TRACE etc. The type can also be a {{org.jboss.netty.handler.codec.http.HttpMethod}} instance. |
| {{CamelHttpQuery}} | {{String}} | Allows to provide URI query parameters as a {{String}} value that overrides the endpoint configuration. Separate multiple parameters using the & sign. For example: {{foo=bar&beer=yes}}. |
| {{Content-Type}} | {{String}} | To set the content-type of the HTTP body. For example: {{text/plain; charset="UTF-8"}}. |
{div}

The following headers is provided as meta-data when a route starts from an [Netty HTTP] endpoint:

The description in the table takes offset in a route having: {{from("netty-http:http:0.0.0.0:8080/myapp")...}} 

{div:class=confluenceTableSmall}
|| Name || Type || Description ||
| {{CamelHttpMethod}} | {{String}} | The HTTP method used, such as GET, POST, TRACE etc. |
| {{CamelHttpUrl}} | {{String}} | The URL including protocol, host and port, etc: {code}http://0.0.0.0:8080/myapp{code} |
| {{CamelHttpUri}} | {{String}} | The URI without protocol, host and port, etc: {code}/myapp{code} |
| {{CamelHttpQuery}} | {{String}} | Any query parameters, such as {{foo=bar&beer=yes}} |
| {{CamelHttpPath}} | {{String}} | Additional context-path. This value is empty if the client called the context-path {{/myapp}}. If the client calls {{/myapp/mystuff}}, then this header value is {{/mystuff}}. In other words its the value after the context-path configured on the route endpoint. |
| {{Content-Type}} | {{String}} | The content type if provided. For example: {{text/plain; charset="UTF-8"}}. |
{div}


h3. Access to Netty types

This component uses the {{org.apache.camel.component.netty.http.NettyHttpMessage}} as the message implementation on the [Exchange]. This allows end users to get access to the original Netty request/response instances if needed, as shown below:

{code}
org.jboss.netty.handler.codec.http.HttpRequest request = exchange.getIn(NettyHttpMessage.class).getHttpRequest();
{code}

h3. Examples

In the route below we use [Netty HTTP] as a HTTP server, which returns back a hardcoded "Bye World" message. 
{code}
    from("netty-http:http://0.0.0.0:8080/foo")
      .transform().constant("Bye World");
{code}

And we can call this HTTP server using Camel also, with the [ProducerTemplate] as shown below:
{code}
    String out = template.requestBody("netty-http:http://localhost:8080/foo", "Hello World", String.class);
    System.out.println(out);
{code}

And we get back "Bye World" as the output.

h3. How do I let Netty match wildcards

By default [Netty HTTP] will only match on exact uri's. But you can instruct Netty to match prefixes. For example
{code}
from("netty-http:http://0.0.0.0:8123/foo").to("mock:foo");
{code}

In the route above [Netty HTTP] will only match if the uri is an exact match, so it will match if you enter
{{http://0.0.0.0:8123/foo}} but not match if you do {{http://0.0.0.0:8123/foo/bar}}.

So if you want to enable wildcard matching you do as follows: 
{code}
from("netty-http:http://0.0.0.0:8123/foo?matchOnUriPrefix=true").to("mock:foo");
{code}
So now Netty matches any endpoints with starts with {{foo}}.

To match *any* endpoint you can do:
{code}
from("netty-http:http://0.0.0.0:8123?matchOnUriPrefix=true").to("mock:foo");
{code}


{include:Endpoint See Also}
- [Netty]
- [Jetty]