components/camel-vertx-http/src/main/docs/vertx-http-component.adoc

[[vertx-http-component]]
= Vert.x HTTP Client Component
:docTitle: Vert.x HTTP Client
:artifactId: camel-vertx-http
:description: Camel HTTP client support with Vert.x
:since: 3.5
:supportLevel: Preview
:component-header: Only producer is supported

*Since Camel {since}*

*{component-header}*

The http://vertx.io/[Vert.x] HTTP component provides the capability to produce messages to HTTP endpoints via the https://vertx.io/docs/vertx-web-client/java/[Vert.x Web Client].

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-vertx-http</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>
------------------------------------------------------------

== URI format

[source,java]
---------------------------
vertx-http:hostname[:port][/resourceUri][?options]
---------------------------

== Options

// component options: START
The Vert.x HTTP Client component supports 13 options, which are listed below.



[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean
| *allowJavaSerializedObject* (advanced) | Whether to allow java serialization when a request has the Content-Type application/x-java-serialized-object This is disabled by default. If you enable this, be aware that Java will deserialize the incoming data from the request. This can be a potential security risk. | false | boolean
| *basicPropertyBinding* (advanced) | Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean
| *vertx* (advanced) | To use an existing vertx instead of creating a new instance |  | Vertx
| *vertxHttpBinding* (advanced) | A custom VertxHttpBinding which can control how to bind between Vert.x and Camel |  | VertxHttpBinding
| *vertxOptions* (advanced) | To provide a custom set of vertx options for configuring vertx |  | VertxOptions
| *headerFilterStrategy* (filter) | To use a custom org.apache.camel.spi.HeaderFilterStrategy to filter header to and from Camel message. |  | HeaderFilterStrategy
| *proxyHost* (proxy) | The proxy server host address |  | String
| *proxyPassword* (proxy) | The proxy server password if authentication is required |  | String
| *proxyPort* (proxy) | The proxy server port |  | Integer
| *proxyType* (proxy) | The proxy server type. The value can be one of: HTTP, SOCKS4, SOCKS5 |  | ProxyType
| *proxyUsername* (proxy) | The proxy server username if authentication is required |  | String
| *useGlobalSslContextParameters* (security) | Enable usage of global SSL context parameters | false | boolean
|===
// component options: END

// endpoint options: START
The Vert.x HTTP Client endpoint is configured using URI syntax:

----
vertx-http:httpUri
----

with the following path and query parameters:

=== Path Parameters (1 parameters):


[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *httpUri* | *Required* The HTTP URI to connect to |  | URI
|===


=== Query Parameters (24 parameters):


[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *connectTimeout* (producer) | The amount of time in milliseconds until a connection is established. A timeout value of zero is interpreted as an infinite timeout. | 60000 | int
| *cookieStore* (producer) | A custom CookieStore to use when session management is enabled. If this option is not set then an in-memory CookieStore is used | InMemoryCookieStore | CookieStore
| *headerFilterStrategy* (producer) | A custom org.apache.camel.spi.HeaderFilterStrategy to filter header to and from Camel message. | VertxHttpHeaderFilterStrategy | HeaderFilterStrategy
| *httpMethod* (producer) | The HTTP method to use. The HttpMethod header cannot override this option if set. The value can be one of: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT, PATCH, OTHER |  | HttpMethod
| *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean
| *okStatusCodeRange* (producer) | The status codes which are considered a success response. The values are inclusive. Multiple ranges can be defined, separated by comma, e.g. 200-204,209,301-304. Each range must be a single number or from-to with the dash included | 200-299 | String
| *sessionManagement* (producer) | Enables session management via WebClientSession. By default the client is configured to use an in-memory CookieStore. The cookieStore option can be used to override this | false | boolean
| *throwExceptionOnFailure* (producer) | Disable throwing HttpOperationFailedException in case of failed responses from the remote server | true | boolean
| *timeout* (producer) | The amount of time in milliseconds after which if the request does not return any data within the timeout period a TimeoutException fails the request. Setting zero or a negative value disables the timeout. | -1 | long
| *transferException* (producer) | If enabled and an Exchange failed processing on the consumer side, and if the caused Exception was sent 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 HttpOperationFailedException. The caused exception is required to be serialized. This is by default turned off. If you enable this then be aware that Camel will deserialize the incoming data from the request to a Java object, which can be a potential security risk. | false | boolean
| *useCompression* (producer) | Set whether compression is enabled to handled compressed (E.g gzipped) responses | false | boolean
| *vertxHttpBinding* (producer) | A custom VertxHttpBinding which can control how to bind between Vert.x and Camel. |  | VertxHttpBinding
| *webClientOptions* (producer) | Sets customized options for configuring the Vert.x WebClient |  | WebClientOptions
| *basicPropertyBinding* (advanced) | Whether the endpoint should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean
| *synchronous* (advanced) | Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported). | false | boolean
| *proxyHost* (proxy) | The proxy server host address |  | String
| *proxyPassword* (proxy) | The proxy server password if authentication is required |  | String
| *proxyPort* (proxy) | The proxy server port |  | Integer
| *proxyType* (proxy) | The proxy server type. The value can be one of: HTTP, SOCKS4, SOCKS5 |  | ProxyType
| *proxyUsername* (proxy) | The proxy server username if authentication is required |  | String
| *basicAuthPassword* (security) | The password to use for basic authentication |  | String
| *basicAuthUsername* (security) | The user name to use for basic authentication |  | String
| *bearerToken* (security) | The bearer token to use for bearer token authentication |  | String
| *sslContextParameters* (security) | To configure security using SSLContextParameters |  | SSLContextParameters
|===
// endpoint options: END

=== Message Headers

[width="100%",cols="10%,20%,70%",options="header",]
|=======================================================================
|Name |Type |Description

|`Exchange.HTTP_URI` |`String` |URI to call. Will override the existing URI set directly on the endpoint.
This URI is the URI of the http server to call. Its not the same as the
Camel endpoint URI, where you can configure endpoint options such as
security etc. This header does not support that, its only the URI of the
http server.

|`Exchange.HTTP_PATH` |`String` |Request URI's path, the header will be used to build the request URI
with the HTTP_URI.

|`Exchange.HTTP_QUERY` |`String` |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.

|`Exchange.HTTP_RESPONSE_TEXT` | `String` |The HTTP response text from the external server.

|`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 to provide a content encoding, such as `gzip`.
|=======================================================================

=== Usage
The following example shows how to send a request to an HTTP endpoint.

You can override the URI configured on the `vertx-http` producer via headers `Exchange.HTTP_URI` and `Exchange.HTTP_PATH`.

[source,java]
----
from("direct:start")
    .to("vertx-http:https://camel.apache.org");
----

==== URI Parameters

The `vertx-http` 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.

==== 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 `HttpOperationFailedException`
with the information.
* Response code is 400+, Camel regards it as an external server failure
and will throw a `HttpOperationFailedException` with the information.

*throwExceptionOnFailure*
The option, `throwExceptionOnFailure`, can be set to `false` to prevent
the `HttpOperationFailedException` from being thrown for failed response
codes. This allows you to get any response from the remote server. +
There is a sample below demonstrating this.

==== Exceptions

`HttpOperationFailedException` 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

==== HTTP method

The following algorithm determines the HTTP method to be used: +
1. Use method provided as endpoint configuration (`httpMethod`). +
2. Use method provided in header (`Exchange.HTTP_METHOD`). +
3. `GET` if query string is provided in header. +
4. `GET` if endpoint is configured with a query string. +
5. `POST` if there is data to send (body is not `null`). +
6. `GET` otherwise.

==== HTTP form parameters

You can send HTTP form parameters in one of two ways.

1. Set the `Exchange.CONTENT_TYPE` header to the value `application/x-www-form-urlencoded` and ensure the message
body is a `String` formatted as form variables. For example `param1=value1&param2=value2`.

2. Set the message body as a https://vertx.io/docs/apidocs/io/vertx/core/MultiMap.html[MultiMap] which allows you to
configure form parameter names and values.

==== Multipart form data

You can upload text or binary files by setting the message body as a https://vertx.io/docs/apidocs/io/vertx/ext/web/multipart/MultipartForm.html[MultipartForm].

==== Customizing Vert.x Web Client options

When finer control of the Vert.x Web Client configuration is required, you can bind a custom https://vertx.io/docs/apidocs/io/vertx/ext/web/client/WebClientOptions.html[WebClientOptions]
instance to the registry.

[source,java]
---------------------------
WebClientOptions options = new WebClientOptions().setMaxRedirects(5)
    .setIdleTimeout(10)
    .setConnectTimeout(3);

camelContext.getRegistry.bind("clinetOptions", options);
---------------------------

Then reference the options on the `vertx-http` producer.

[source,java]
---------------------------
from("direct:start")
    .to("vertx-http:http://localhost:8080?webClientOptions=#options")
---------------------------

==== SSL

The Vert.x HTTP component supports SSL/TLS configuration through the xref:manual::camel-configuration-utilities.adoc[Camel JSSE Configuration Utility].

It is also possible to configure SSL options by providing a custom `WebClientOptions`.

==== Session Management

Session management can be enabled via the `sessionManagement` URI option. When enabled, an in-memory cookie store is used to track cookies.
This can be overridden by providing a custom `CookieStore` via the `cookieStore` URI option.

include::camel-spring-boot::page$vertx-http-starter.adoc[]