HTTP outbound gateway
Used to send HTTP requests and receive HTTP response messages.
A gateway that sends HTTP requests based on incoming messages, and converts the HTTP response (which might just be a HTTP status code) to the result message.
If you're not interested in the response message, use a HTTP outbound channel adapter instead.
This gateway dynamically determines the Content-Type
for the outgoing HTTP request using these rules:
- If present, the value of the
contentType
message header is used - If the HTTP method is one of
GET, HEAD, TRACE
, the content type is not applicable (these methods do not use a request body) - If the message payload is a
String
, the content type will betext/plain
- If the message payload is a
byte[]
, the content type will beapplication/octet-stream
- If the message payload is a
javax.xml.transform.Source
, the content type will betext/xml
- If the message payload is a
Map<String, String>
, the content type will beapplication/x-www-form-urlencoded
- If the message payload is a
Map<String, ?>
, the content type will bemultipart/form-data
(note: because of rule 6, this means at least one value in the map must be a type other thanString
) - If none of the above, the content type will be
application/x-java-serialized-object
Supported payload types when filling the body of the HTTP request message include:
byte[]
: these are simply copied to the bodyString
: these are converted to bytes using the specified charset and written to the bodyjavax.xml.transform.Source
: these are written to the body using the identity transformMap<String, ?>
: these are written as form data to the body, using either themultipart/form-data
format (if so specified by theContent-Type
) or theapplication/x-www-form-urlencoded
format otherwise
Note that while rules 3-7 nicely match the supported payload types, by using rule 1 you can create any content type. However, this also allows you to create invalid combinations if you don't correctly match it to the payload type.
URL
URL to which the requests should be sent. It may include {placeholders}
.
Required
HTTP method
The HTTP method to use when executing requests with this gateway.
Default is POST
.
Expected response type
The expected type to which the response body should be converted. Default is org.springframework.http.ResponseEntity
.
To take advantage of the HTTP message converters registered on this gateway provide a different type, such as java.lang.String
. This is the recommended value when the expected response is a text-based content type, for example application/json
or text/xml
.
To access the raw HTTP body of the response without any automatic conversion, use type byte[]
. This should work for all content types, even for text-based ones. In some special cases this can be useful in order to manually solve character encoding issues.
Expression to be evaluated against the message to replace a URI {placeholder}
with the evaluation result.
URL expression
SpEL expression resolving to a URL to which the requests should be sent. The resolved value may include {placeholders}
for further evaluation against URI variables.
Optional ; mutually exclusive with URL.
Encode URI
When set to false
, the real URI won't be encoded before the request is sent. This may be useful in some scenarios as it allows user control over the encoding, if needed, for example by using the URL expression.
Default is true
.
HTTP method expression
SpEL expression to dynamically determine the HTTP method (POST
, GET
, etc) to use when executing requests with this adapter.
Optional ; mutually exclusive with HTTP method.
Note that the standard JDK HTTP library does not support the HTTP PATCH
method. Use a custom REST template support object configured with the Apache HttpComponents request factory to enable PATCH
.
Expected response type expression
SpEL expression to determine the type for the expected response to which the response body should be converted. The returned value of the expression could be an instance of java.lang.Class
or java.lang.String
representing a fully qualified class name.
Optional ; mutually exclusive with expected response type.
Extract request payload
Specify whether the outbound message's payload should be extracted when preparing the request body; otherwise the message itself will be serialized.
Default value is true
.
Mapped request headers
Comma-separated list of names of message headers to be mapped into the HTTP headers of the HTTP request. The values in this list can also be simple patterns to be matched against the header names (e.g. foo
or foo
). The string HTTP_REQUEST_HEADERS
will match against any of the standard HTTP request headers.
All standard HTTP request headers are mapped by default.
Note that all non-standard headers will automatically be prefixed with X-
. This behaviour can be changed by using a custom header mapper. Also note that the contentType
message header is mapped to the standard HTTP header Content-Type
.
Mapped response headers
Comma-separated list of names of HTTP headers to be mapped from the HTTP response into the message headers. The values in this list can also be simple patterns to be matched against the header names (e.g. foo
or foo
). The string HTTP_RESPONSE_HEADERS
will match against any of the standard HTTP response headers.
All standard HTTP response headers are mapped by default.
Note that all non-standard headers will automatically be prefixed with X-
. This behaviour can be changed by using a custom header mapper. Also note that the standard HTTP header Content-Type
is mapped to the contentType
message header.
Be aware that independently from this setting, the http_statusCode
message header will always be present on the reply message. This message header – together with other special headers such as Accept
, Access-Control-Allow-Methods
, Access-Control-Request-Method
, Allow
, Content-Type
, and Range
– can cause problems when left on the reply message. To prevent these issues you might want to not map any response headers at all, or only explicitly map the ones you are actually interested in. Remember that you still might have to remove the http_statusCode
message header: the header filter transformer makes this really easy.
Header mapper
A custom HeaderMapper
implementation can be used to fully control the mapping between message headers and HTTP headers. For example, to configure whether to use the X-
prefix for user-defined HTTP headers or not.
This setting is mutually exclusive with mapped request headers and mapped response headers.
Charset
Specify the charset name to use for converting string-typed payloads to bytes.
Default is UTF-8
.
Reply timeout
Allows you to specify how long (in milliseconds) this gateway will wait for the reply message to be sent successfully to the reply channel before throwing an exception. This attribute only applies when the channel might block, for example when using a bounded queue channel that is currently full.
Also, keep in mind that when sending to a direct channel, the invocation will occur in the sender's thread. Therefore, the failing of the send operation may be caused by other components further downstream.
If not specified, by default the gateway will wait indefinitely.
Transfer cookies
When set to true
, if a response contains a HTTP Set-Cookie header, it will be mapped to a Cookie message header. This enables simple cookie handling where subsequent HTTP interactions in the same message flow can use a cookie supplied by the server.
Default is false
.
REST template
Allows for specifying a custom RestTemplate
.
A REST template provides a configurable extension point for communicating with HTTP servers using RESTful principles. This can be used to add authentication to HTTP connections, for example.
Request channel
Channel to consume the request messages from.
Required
Reply channel
Channel where reply messages should be sent to.
You can select the nullChannel
here to silently drop the reply messages.
Required
Advice can be added to change the behaviour of this endpoint, for example to add retry logic in case of failures. The following types of advice are available:
Retry advice: allows configuration of sophisticated retry scenarios; this includes specifying policies for retry attemps, backoff periods between attempts and the recovery strategy when retries are exhausted Circuit breaker: if a certain number of consecutive attempts fails, new requests will fail fast and no attempt will be made to invoke the request handler again until some time has expired Expression evaluating advice: general advice that evaluates a configurable SpEL expression on successful and/or failed attempts, and optionally can send a message to a success channel and/or failure channel
By adding multiple advices to this endpoint you can create even more complex combined behaviour. For example, if you add a circuit breaker and a retry advice, you can create a scenario where the circuit breaker only opens when all retries are exhaused. Note that the order of the advice types is important, as switching the order will change the combined behaviour: the first item in the list will be the top of the advice chain, meaning it will be the last advice that is evaluated. Also note that if any advice "traps" exceptions, all advices higher up in the chain won't know about any failures.
Id
Name that uniquely identifies this flow component.
Required