HTTP outbound gateway · eMagiz Documentation

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 be text/plain
If the message payload is a byte[], the content type will be application/octet-stream
If the message payload is a javax.xml.transform.Source, the content type will be text/xml
If the message payload is a Map<String, String>, the content type will be application/x-www-form-urlencoded
If the message payload is a Map<String, ?>, the content type will be multipart/form-data (note: because of rule 6, this means at least one value in the map must be a type other than String)
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 body
String: these are converted to bytes using the specified charset and written to the body
javax.xml.transform.Source: these are written to the body using the identity transform
Map<String, ?>: these are written as form data to the body, using either the multipart/form-data format (if so specified by the Content-Type) or the application/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