You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ac...@apache.org on 2016/01/25 11:04:39 UTC
camel git commit: Add Camel-ahc gitbook docs
Repository: camel
Updated Branches:
refs/heads/master dc929d6d6 -> 08a5d7d89
Add Camel-ahc gitbook docs
Project: http://git-wip-us.apache.org/repos/asf/camel/repo
Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/08a5d7d8
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/08a5d7d8
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/08a5d7d8
Branch: refs/heads/master
Commit: 08a5d7d89d66b2c04cd0f65610af5a90dce2fdcf
Parents: dc929d6
Author: Andrea Cosentino <an...@gmail.com>
Authored: Mon Jan 25 11:03:40 2016 +0100
Committer: Andrea Cosentino <an...@gmail.com>
Committed: Mon Jan 25 11:03:40 2016 +0100
----------------------------------------------------------------------
components/camel-ahc/src/main/docs/readme.adoc | 468 ++++++++++++++++++++
docs/user-manual/en/SUMMARY.md | 1 +
2 files changed, 469 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/08a5d7d8/components/camel-ahc/src/main/docs/readme.adoc
----------------------------------------------------------------------
diff --git a/components/camel-ahc/src/main/docs/readme.adoc b/components/camel-ahc/src/main/docs/readme.adoc
new file mode 100644
index 0000000..e5c1b14
--- /dev/null
+++ b/components/camel-ahc/src/main/docs/readme.adoc
@@ -0,0 +1,468 @@
+[[AHC-AsyncHttpClientComponent]]
+Async Http Client Component
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*Available as of Camel 2.8*
+
+The *ahc:* component provides HTTP based link:endpoint.html[endpoints]
+for consuming external HTTP resources (as a client to call external
+servers using HTTP). +
+ The component uses the
+https://github.com/AsyncHttpClient/async-http-client[Async Http Client]
+library.
+
+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-ahc</artifactId>
+ <version>x.x.x</version>
+ <!-- use the same version as your Camel core version -->
+</dependency>
+------------------------------------------------------------
+
+[[AHC-URIformat]]
+URI format
+^^^^^^^^^^
+
+[source,java]
+---------------------------------------------------
+ahc:http://hostname[:port][/resourceUri][?options]
+ahc:https://hostname[:port][/resourceUri][?options]
+---------------------------------------------------
+
+Will by default use port 80 for HTTP and 443 for HTTPS.
+
+You can append query options to the URI in the following format,
+`?option=value&option=value&...`
+
+[[AHC-AhcEndpointOptions]]
+AhcEndpoint Options
+^^^^^^^^^^^^^^^^^^^
+
+[width="100%",cols="10%,10%,80%",options="header",]
+|=======================================================================
+|Name |Default Value |Description
+|`throwExceptionOnFailure` |`true` |Option to disable throwing the `AhcOperationFailedException` in case of
+failed responses from the remote server. This allows you to get all
+responses regardless of the HTTP status code.
+
+|`bridgeEndpoint` |`false` |If the option is true, then the Exchange.HTTP_URI header is ignored, and
+use the endpoint's URI for request. You may also set the
+*throwExcpetionOnFailure* to be false to let the AhcProducer send all
+the fault response back.
+
+|`transferException` |`false` |If enabled and an link:exchange.html[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
+(for example using link:jetty.html[Jetty] or link:servlet.html[Servlet]
+Camel components). On the producer side the exception will be
+deserialized and thrown as is, instead of the
+`AhcOperationFailedException`. The caused exception is required to be
+serialized.
+
+|`client` |`null` |To use a custom `com.ning.http.client.AsyncHttpClient`.
+
+|`clientConfig` |`null` |To configure the `AsyncHttpClient` to use a custom
+`com.ning.http.client.AsyncHttpClientConfig` instance. This instance
+replaces any instance configured at the component level.
+
+|`clientConfig.x` |`null` |To configure additional properties of the
+`com.ning.http.client.AsyncHttpClientConfig` instance used by the
+endpoint. Note that configuration options set using this parameter will
+be merged with those set using the `clientConfig` parameter or the
+instance set at the component level with properties set using this
+parameter taking priority.
+
+|`clientConfig.realm.x` |`null` |*Camel 2.11:* To configure realm properties of the
+`com.ning.http.client.AsyncHttpClientConfig` The options which can be
+used are the options from `com.ning.http.client.Realm.RealmBuilder`. eg
+to set scheme, you can configure `"clientConfig.realm.scheme=DIGEST"`
+
+|`binding` |`null` |To use a custom `org.apache.camel.component.ahc.AhcBinding`.
+
+|`sslContextParameters` |`null` | *Camel 2.9:* Reference to a
+`org.apache.camel.util.jsse.SSLContextParameters` in the
+link:registry.html[Registry]. This reference overrides any configured
+SSLContextParameters at the component level. See link:ahc.html[Using
+the JSSE Configuration Utility]. Note that configuring this option will
+override any SSL/TLS configuration options provided through the
+clientConfig option at the endpoint or component level.
+
+|`bufferSize` |`4096` | *Camel 2.10.3:* The initial in-memory buffer size used when transferring
+data between Camel and AHC Client.
+|=======================================================================
+
+[[AHC-AhcComponentOptions]]
+AhcComponent Options
+^^^^^^^^^^^^^^^^^^^^
+
+[width="100%",cols="10%,10%,80%",options="header",]
+|=======================================================================
+|Name |Default Value |Description
+|`client` |`null` |To use a custom `com.ning.http.client.AsyncHttpClient`.
+
+|`clientConfig` |`null` |To configure the `AsyncHttpClient` to use a custom
+`com.ning.http.client.AsyncHttpClientConfig`.
+
+|`binding` |`null` |To use a custom `org.apache.camel.component.ahc.AhcBinding`.
+
+|`sslContextParameters` |`null` |*Camel 2.9:* To configure custom SSL/TLS configuration options at the
+component level. See link:ahc.html[Using the JSSE Configuration
+Utility] for more details. Note that configuring this option will
+override any SSL/TLS configuration options provided through the
+clientConfig option at the endpoint or component level.
+|=======================================================================
+
+
+Notice that setting any of the options on the `AhcComponent` will
+propagate those options to
+`AhcEndpoints` being created. However the `AhcEndpoint` can also
+configure/override a custom option. Options set on endpoints will always
+take precedence over options from the `AhcComponent`.
+
+[[AHC-MessageHeaders]]
+Message Headers
+^^^^^^^^^^^^^^^
+
+[width="100%",cols="10%,10%,80%",options="header",]
+|=======================================================================
+|Name |Type |Description
+|`Exchange.HTTP_URI` |`String` |URI to call. Will override existing URI set directly on the endpoint.
+
+|`Exchange.HTTP_PATH` |`String` |Request URI's path, the header will be used to build the request URI
+with the HTTP_URI. If the path is start with "/", http producer will try
+to find the relative path based on the Exchange.HTTP_BASE_URI header or
+the `exchange.getFromEndpoint().getEndpointUri();`
+
+|`Exchange.HTTP_QUERY` |`String` |*Camel 2.11 onwards:* URI parameters. Will override existing URI
+parameters set directly on the endpoint.
+
+|`Exchange.HTTP_RESPONSE_CODE` |`int` |The HTTP response code from the external server. Is 200 for OK.
+
+|`Exchange.HTTP_CHARACTER_ENCODING` |`String` |Character encoding.
+
+|`Exchange.CONTENT_TYPE` |`String` |The HTTP content type. Is set on both the IN and OUT message to provide
+a content type, such as `text/html`.
+
+|`Exchange.CONTENT_ENCODING` |`String` |The HTTP content encoding. Is set on both the IN and OUT message to
+provide a content encoding, such as `gzip`.
+|=======================================================================
+
+[[AHC-MessageBody]]
+Message Body
+^^^^^^^^^^^^
+
+Camel will store the HTTP response from the external server on the OUT
+body. All headers from the IN message will be copied to the OUT message,
+so headers are preserved during routing. Additionally Camel will add the
+HTTP response headers as well to the OUT message headers.
+
+[[AHC-Responsecode]]
+Response code
+^^^^^^^^^^^^^
+
+Camel will handle according to the HTTP response code:
+
+* Response code is in the range 100..299, Camel regards it as a success
+response.
+* Response code is in the range 300..399, Camel regards it as a
+redirection response and will throw a `AhcOperationFailedException` with
+the information.
+* Response code is 400+, Camel regards it as an external server failure
+and will throw a `AhcOperationFailedException` with the information.
++
+throwExceptionOnFailure
++
+The option, `throwExceptionOnFailure`, can be set to `false` to prevent
+the `AhcOperationFailedException` from being thrown for failed response
+codes. This allows you to get any response from the remote server.
+
+[[AHC-AhcOperationFailedException]]
+AhcOperationFailedException
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This exception contains the following information:
+
+* The HTTP status code
+* The HTTP status line (text of the status code)
+* Redirect location, if server returned a redirect
+* Response body as a `java.lang.String`, if server provided a body as
+response
+
+[[AHC-CallingusingGETorPOST]]
+Calling using GET or POST
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following algorithm is used to determine if either `GET` or `POST`
+HTTP method should be used: +
+ 1. Use method provided in header. +
+ 2. `GET` if query string is provided in header. +
+ 3. `GET` if endpoint is configured with a query string. +
+ 4. `POST` if there is data to send (body is not null). +
+ 5. `GET` otherwise.
+
+[[AHC-ConfiguringURItocall]]
+Configuring URI to call
+^^^^^^^^^^^^^^^^^^^^^^^
+
+You can set the HTTP producer's URI directly form the endpoint URI. In
+the route below, Camel will call out to the external server, `oldhost`,
+using HTTP.
+
+[source,java]
+----------------------------------
+from("direct:start")
+ .to("ahc:http://oldhost");
+----------------------------------
+
+And the equivalent Spring sample:
+
+[source,xml]
+---------------------------------------------------------------------
+<camelContext xmlns="http://activemq.apache.org/camel/schema/spring">
+ <route>
+ <from uri="direct:start"/>
+ <to uri="ahc:http://oldhost"/>
+ </route>
+</camelContext>
+---------------------------------------------------------------------
+
+You can override the HTTP endpoint URI by adding a header with the key,
+`Exchange.HTTP_URI`, on the message.
+
+[source,java]
+-------------------------------------------------------------
+from("direct:start")
+ .setHeader(Exchange.HTTP_URI, constant("http://newhost"))
+ .to("ahc:http://oldhost");
+-------------------------------------------------------------
+
+[[AHC-ConfiguringURIParameters]]
+Configuring URI Parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The *ahc* producer supports URI parameters to be sent to the HTTP
+server. The URI parameters can either be set directly on the endpoint
+URI or as a header with the key `Exchange.HTTP_QUERY` on the message.
+
+[source,java]
+---------------------------------------------------------
+from("direct:start")
+ .to("ahc:http://oldhost?order=123&detail=short");
+---------------------------------------------------------
+
+Or options provided in a header:
+
+[source,java]
+-------------------------------------------------------------------------------
+from("direct:start")
+ .setHeader(Exchange.HTTP_QUERY, constant("order=123&detail=short"))
+ .to("ahc:http://oldhost");
+-------------------------------------------------------------------------------
+
+[[AHC-HowtosetthehttpmethodtotheHTTPproducer]]
+How to set the http method to the HTTP producer
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The HTTP component provides a way to set the HTTP request method by
+setting the message header. Here is an example;
+
+[source,java]
+--------------------------------------------------------------
+from("direct:start")
+ .setHeader(Exchange.HTTP_METHOD, constant("POST"))
+ .to("ahc:http://www.google.com")
+ .to("mock:results");
+--------------------------------------------------------------
+
+And the equivalent Spring sample:
+
+[source,xml]
+---------------------------------------------------------------------
+<camelContext xmlns="http://activemq.apache.org/camel/schema/spring">
+ <route>
+ <from uri="direct:start"/>
+ <setHeader headerName="CamelHttpMethod">
+ <constant>POST</constant>
+ </setHeader>
+ <to uri="ahc:http://www.google.com"/>
+ <to uri="mock:results"/>
+ </route>
+</camelContext>
+---------------------------------------------------------------------
+
+[[AHC-Configuringcharset]]
+Configuring charset
+^^^^^^^^^^^^^^^^^^^
+
+If you are using `POST` to send data you can configure the `charset`
+using the `Exchange` property:
+
+[source,java]
+----------------------------------------------------------
+exchange.setProperty(Exchange.CHARSET_NAME, "iso-8859-1");
+----------------------------------------------------------
+
+[[AHC-URIParametersfromtheendpointURI]]
+URI Parameters from the endpoint URI
+++++++++++++++++++++++++++++++++++++
+
+In this sample we have the complete URI endpoint that is just what you
+would have typed in a web browser. Multiple URI parameters can of course
+be set using the `&` character as separator, just as you would in the
+web browser. Camel does no tricks here.
+
+[source,java]
+--------------------------------------------------------------------
+// we query for Camel at the Google page
+template.sendBody("ahc:http://www.google.com/search?q=Camel", null);
+--------------------------------------------------------------------
+
+[[AHC-URIParametersfromtheMessage]]
+URI Parameters from the Message
++++++++++++++++++++++++++++++++
+
+[source,java]
+---------------------------------------------------------------------
+Map headers = new HashMap();
+headers.put(Exchange.HTTP_QUERY, "q=Camel&lr=lang_en");
+// we query for Camel and English language at Google
+template.sendBody("ahc:http://www.google.com/search", null, headers);
+---------------------------------------------------------------------
+
+In the header value above notice that it should *not* be prefixed with
+`?` and you can separate parameters as usual with the `&` char.
+
+[[AHC-GettingtheResponseCode]]
+Getting the Response Code
++++++++++++++++++++++++++
+
+You can get the HTTP response code from the AHC component by getting the
+value from the Out message header with `Exchange.HTTP_RESPONSE_CODE`.
+
+[source,java]
+----------------------------------------------------------------------------------------------
+Exchange exchange = template.send("ahc:http://www.google.com/search", new Processor() {
+ public void process(Exchange exchange) throws Exception {
+ exchange.getIn().setHeader(Exchange.HTTP_QUERY, constant("hl=en&q=activemq"));
+ }
+ });
+ Message out = exchange.getOut();
+ int responseCode = out.getHeader(Exchange.HTTP_RESPONSE_CODE, Integer.class);
+----------------------------------------------------------------------------------------------
+
+[[AHC-ConfiguringAsyncHttpClient]]
+Configuring AsyncHttpClient
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The `AsyncHttpClient` client uses a `AsyncHttpClientConfig` to configure
+the client. See the documentation at +
+ http://github.com/sonatype/async-http-client[Async Http Client] for
+more details.
+
+In Camel *2.8*, configuration is limited to using the builder pattern
+provided by `AsyncHttpClientConfig.Builder`. In Camel 2.8, the
+`AsyncHttpClientConfig` doesn't support getters/setters so its not easy
+to create/configure using a Spring bean style (eg the <bean> tag in the
+XML file).
+
+The example below shows how to use a builder to create the
+`AsyncHttpClientConfig` which we configure on the `AhcComponent`.
+
+In Camel *2.9*, the AHC component uses Async HTTP library 1.6.4. This
+newer version provides added support for plain bean style configuration.
+The `AsyncHttpClientConfigBean` class provides getters and setters for
+the configuration options available in `AsyncHttpClientConfig`. An
+instance of `AsyncHttpClientConfigBean` may be passed directly to the
+AHC component or referenced in an endpoint URI using the `clientConfig`
+URI parameter.
+
+Also available in Camel *2.9* is the ability to set configuration
+options directly in the URI. URI parameters starting with
+"clientConfig." can be used to set the various configurable properties
+of `AsyncHttpClientConfig`. The properties specified in the endpoint URI
+are merged with those specified in the configuration referenced by the
+"clientConfig" URI parameter with those being set using the
+"clientConfig." parameter taking priority. The `AsyncHttpClientConfig`
+instance referenced is always copied for each endpoint such that
+settings on one endpoint will remain independent of settings on any
+previously created endpoints. The example below shows how to configure
+the AHC component using the "clientConfig." type URI parameters.
+
+[source,java]
+---------------------------------------------------------------------------------------------------------
+from("direct:start")
+ .to("ahc:http://localhost:8080/foo?clientConfig.maxRequestRetry=3&clientConfig.followRedirects=true")
+---------------------------------------------------------------------------------------------------------
+
+[[AHC-SSLSupport]]
+SSL Support (HTTPS)
+^^^^^^^^^^^^^^^^^^^
+
+[[AHC-UsingtheJSSEConfigurationUtility]]
+Using the JSSE Configuration Utility
+
+As of Camel 2.9, the AHC component supports SSL/TLS configuration
+through the link:camel-configuration-utilities.html[Camel JSSE
+Configuration Utility]. This utility greatly decreases the amount of
+component specific code you need to write and is configurable at the
+endpoint and component levels. The following examples demonstrate how
+to use the utility with the AHC component.
+
+[[AHC-Programmaticconfigurationofthecomponent]]
+Programmatic configuration of the component
+
+[source,java]
+-------------------------------------------------------------------------
+KeyStoreParameters ksp = new KeyStoreParameters();
+ksp.setResource("/users/home/server/keystore.jks");
+ksp.setPassword("keystorePassword");
+
+KeyManagersParameters kmp = new KeyManagersParameters();
+kmp.setKeyStore(ksp);
+kmp.setKeyPassword("keyPassword");
+
+SSLContextParameters scp = new SSLContextParameters();
+scp.setKeyManagers(kmp);
+
+AhcComponent component = context.getComponent("ahc", AhcComponent.class);
+component.setSslContextParameters(scp));
+-------------------------------------------------------------------------
+
+[[AHC-SpringDSLbasedconfigurationofendpoint]]
+Spring DSL based configuration of endpoint
+
+[source,xml]
+----------------------------------------------------------------------------------
+...
+ <camel:sslContextParameters
+ id="sslContextParameters">
+ <camel:keyManagers
+ keyPassword="keyPassword">
+ <camel:keyStore
+ resource="/users/home/server/keystore.jks"
+ password="keystorePassword"/>
+ </camel:keyManagers>
+ </camel:sslContextParameters>...
+...
+ <to uri="ahc:https://localhost/foo?sslContextParameters=#sslContextParameters"/>
+...
+----------------------------------------------------------------------------------
+
+[[AHC-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]
+* link:http4.html[HTTP4]
+
http://git-wip-us.apache.org/repos/asf/camel/blob/08a5d7d8/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index 0937c6a..c5ec1d0 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -3,5 +3,6 @@
* [Introduction](README.md)
* [Legal Notice](notice.md)
* Components References
+ * [Ahc](components/camel-ahc/src/main/docs/readme.adoc)
* [Atom](components/camel-atom/src/main/docs/readme.adoc)
* [JMS](components/camel-jms/src/main/docs/readme.adoc)