Repository: camel Updated Branches: refs/heads/master 226fb4606 -> 36ce04183
Added camel-undertow docs to Gitbook Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/963acd60 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/963acd60 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/963acd60 Branch: refs/heads/master Commit: 963acd608d737ecb57d369b31aaa2f5f00722b88 Parents: 226fb46 Author: Andrea Cosentino <anco...@gmail.com> Authored: Thu Jun 9 09:05:57 2016 +0200 Committer: Andrea Cosentino <anco...@gmail.com> Committed: Thu Jun 9 09:05:57 2016 +0200 ---------------------------------------------------------------------- .../camel-undertow/src/main/docs/undertow.adoc | 174 +++++++++++++++++++ docs/user-manual/en/SUMMARY.md | 1 + 2 files changed, 175 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/963acd60/components/camel-undertow/src/main/docs/undertow.adoc ---------------------------------------------------------------------- diff --git a/components/camel-undertow/src/main/docs/undertow.adoc b/components/camel-undertow/src/main/docs/undertow.adoc new file mode 100644 index 0000000..275b5ad --- /dev/null +++ b/components/camel-undertow/src/main/docs/undertow.adoc @@ -0,0 +1,174 @@ +[[Undertow-UndertowComponent]] +Undertow Component +~~~~~~~~~~~~~~~~~~ + +*Available as of Camel 2.16* + +The *undertow* component provides HTTP-based +link:endpoint.html[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: + +[source,xml] +------------------------------------------------------------ +<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> +------------------------------------------------------------ + +[[Undertow-URIformat]] +URI format +^^^^^^^^^^ + +[source,java] +------------------------------------------------------- +undertow:http://hostname[:port][/resourceUri][?options] +------------------------------------------------------- + +You can append query options to the URI in the following format, +`?option=value&option=value&...` + +[[Undertow-Options]] +Options +^^^^^^^ + + +// component options: START +The Undertow component supports 2 options which are listed below. + + + +{% raw %} +[width="100%",cols="2s,1m,8",options="header"] +|======================================================================= +| 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 %} +// component options: END + + + +// endpoint options: START +The Undertow component supports 17 endpoint options which are listed below: + +{% raw %} +[width="100%",cols="2s,1,1m,1m,5",options="header"] +|======================================================================= +| Name | Group | Default | Java Type | Description +| httpURI | common | | URI | *Required* The url of the HTTP endpoint to use. +| transferException | common | | 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. +| 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. +| 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 | | 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. +| exchangePattern | advanced | InOnly | ExchangePattern | Sets the default exchange pattern when creating an exchange +| 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 %} +// endpoint options: END + + +[[Undertow-MessageHeaders]] +Message Headers +^^^^^^^^^^^^^^^ + +Camel uses the same message headers as the link:http.html[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. + +[[Undertow-ProducerExample]] +Producer Example +^^^^^^^^^^^^^^^^ + +The following is a basic example of how to send an HTTP request to an +existing HTTP endpoint. + +in Java DSL + +[source,java] +---------------------------------------------------------- +from("direct:start").to("undertow:http://www.google.com";); +---------------------------------------------------------- + +or in Spring XML + +[source,xml] +---------------------------------------------- +<route> + <from uri="direct:start"/> + <to uri="undertow:http://www.google.com"/> +<route> +---------------------------------------------- + +[[Undertow-ConsumerExample]] +Consumer Example +^^^^^^^^^^^^^^^^ + +In this sample we define a route that exposes a HTTP service at +`http://localhost:8080/myapp/myservice`: + +[source,xml] +-------------------------------------------------------------- +<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 +link:how-do-i-let-jetty-match-wildcards.html[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 +https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=46339[Servlet +Transport]. + +[[Undertow-SeeAlso]] +See Also +^^^^^^^^ + +* link:configuring-camel.html[Configuring Camel] +* link:component.html[Component] +* link:endpoint.html[Endpoint] +* link:getting-started.html[Getting Started] + +* link:jetty.html[Jetty] +* link:http.html[HTTP] + http://git-wip-us.apache.org/repos/asf/camel/blob/963acd60/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index a2246eb..259b937 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -266,6 +266,7 @@ * [Swagger Java](swagger-java.adoc) * [Telegram](telegram.adoc) * [Twitter](twitter.adoc) + * [Undertow](undertow.adoc) * [Websocket](websocket.adoc) * [XML Security](xmlsecurity.adoc) * [Yammer](yammer.adoc)
