Web service outbound gateway

Used to request webservice calls and receive reply messages.

A gateway that sends SOAP requests over HTTP(S) based on incoming messages, and converts the SOAP response to the result message.

Both the request and the response messages should be plain XML, as this gateway will automatically wrap and unwrap them with the required SOAP elements. Responses containing a SOAP Fault are automatically converted to a SoapFaultClientException, thereby triggering the flow's error handling.

When developing or debugging a web service, it can be quite useful to look at the content of a (SOAP) message when it arrives, or just before it is sent. If you have access to the eMagiz OSGi runtime, you can do this by using the following console commands: log:set TRACE org.springframework.ws.client.MessageTracing.sent and/or log:set TRACE org.springframework.ws.client.MessageTracing.received

Alternatively, you can add the following lines to the etc/org.ops4j.pax.logging.cfg config file (no restart required): log4j.logger.org.springframework.ws.client.MessageTracing.sent = TRACE and/or log4j.logger.org.springframework.ws.client.MessageTracing.received = TRACE

Both methods will cause the (SOAP) requests and responses to be written to the log file. Don't forget to change log levels back to INFO, as TRACE has negative performance impact and can seriously compromise security!

URI

The destination URI for this web service gateway.

This URI may include {placeholders} whose values are determined by evaluating SpEL expressions provided via uri-variable sub-elements. The root object for those evaluations is the actual request message at runtime, i.e. you can access its payload or headers in the expression.

Requires reply

Specify whether this outbound gateway must return a non-null value, i.e. whether every request message must result in a reply message.

If true, a ReplyRequiredException will be thrown when the underlying service returns a null value or an empty string (if ignore empty responses is true).

Default is false.

Ignore empty responses

Indicates whether empty string response payloads should be considered as null. See also requires reply.

Note that when requires reply is true the response is not actually "ignored", because it will cause a ReplyRequiredException to be thrown. Set this to false if you want to send empty string responses in reply messages.

Default is true.

Message factory

Specifies the web service message factory responsible for creating the request messages and parsing the response messages.

If not specified, a SaajSoapMessageFactory for SOAP version 1.1 will be used.

Message sender

Sets the single message sender used for sending messages.

This message sender will be used to resolve an URI to a WebServiceConnection.

By default, a HttpUrlConnectionMessageSender is used: this WebServiceMessageSender implementation uses standard J2SE facilities to execute POST requests, without support for HTTP authentication or advanced configuration options. It is designed for easy subclassing, customizing specific template methods. However, consider HttpComponentsMessageSender for more sophisticated needs: the J2SE HttpURLConnection is rather limited in its capabilities.

Interceptor

Interceptor that will be applied to the request and the response. An intercepter can manipulate the request or the response before and after the processing of the message by the gateway.

These can be extremely useful when you want to apply specific functionality to certain requests, for example, dealing with security-related SOAP headers, or the logging of request and response messages.

Some of the security-related interceptor implementations and their specific functionality are:

Mendix authentication SAAJ SOAP interceptor Adds Mendix specific authentication SOAP headers to request messages, containing a username and password.

Metacom authentication SAAJ SOAP interceptor Adds a Metacom specific session ID token to the SOAP body of the request message. The session ID tokens are acquired by sending a username and password to the Metacom login system.

Zimbra authentication SAAJ SOAP interceptor Adds Zimbra specific authentication token SOAP headers to request messages. The authentication tokens are acquired by sending a username and password to the Zimbra authentication system.

WSS4J security interceptor Interceptor based on Apache's WSS4J that adds WS-Security aspects (authentication, XML digital signatures, XML encryption and decryption) to the web service. Implements the following OASIS Web Services Security standards:

• SOAP Message Security 1.1
• Username Token Profile 1.1
• X.509 Certificate Token Profile 1.1
• SAML Token Profile 1.1
• Kerberos Token Profile 1.1
• Basic Security Profile 1.1

Request callback

Callback that will be applied to the request. A web service request callback can change the request message after the payload has been written to it but prior to invocation of the actual web service (and before any interceptors are applied).

SOAP action callback Adds a SOAPAction HTTP header to the request message.

WS-Addressing action callback Adds a wsa:Action SOAP header to the request message.

Fault message resolver

Specifies the fault message resolver responsible for handling faults when calling the web service.

If not specified, a SOAP fault message resolver will be used: this fault resolver simply throws a SoapFaultClientException when a fault occurs. The message of this exception only contains the <faultstring> of the SOAP Fault.

You can also choose to use a detailed SOAP fault message resolver instead: this fault resolver throws a SoapFaultException when a fault occurs. The message of this exception includes the <faultcode>, <faultstring> and <detail> of the SOAP Fault.

Mapped request headers

Comma-separated list of names of message headers to be mapped into the SOAP headers of the SOAP request.

The values in this list can also be simple patterns to be matched against the header names (e.g. foo or foo).

Cannot be used in combination with a header mapper.

Mapped reply headers

Comma-separated list of names of SOAP headers to be mapped from the SOAP reply into the message headers.

Header mapper

A SOAP header mapper that this gateway will use to map between Spring Integration message headers and the SOAP message.

Cannot be used in combination with mapped request headers or mapped reply headers.

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.

Encode URI

When set to false, the 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.

Default is true.

Expression to be evaluated against the message to replace a URI {placeholder} with the evaluation result.

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