Gateway operation mode for SOAP nodes
The SOAPInput, SOAPRequest, and SOAPAsyncRequest nodes have
two operation modes: WSDL mode, and Gateway mode.
If the node is configured to be in WSDL mode, which is the default,
the web service operations performed by the node are specified by
a WSDL that configures the node. In Gateway mode, SOAP nodes in a
message flow handle generic SOAP request messages in the following
scenarios.
- Provider scenario
- In a provider scenario, IBM® Integration Bus receives
generic SOAP/HTTP or SOAP/JMS requests by using a SOAPInput node, and sends a
reply to the originating client by using a SOAPReply node. A single SOAPInput node can receive
any SOAP request message, and is not configured with a WSDL.
- Consumer scenario
- In a consumer scenario, IBM Integration Bus can
route a SOAP request to any external web service provider by using
the SOAPRequest node or
a pair of SOAPAsyncRequest and SOAPAsyncResponse nodes. Endpoint
information can be specified in the local environment, which is used
dynamically at run time to send the outbound request message.
- Façade scenario
- In a façade scenario, IBM Integration Bus can
receive SOAP requests from multiple different clients, and route them
to any one of multiple back end web service providers, or existing
systems. Endpoint information for the back-end web service provider
can be specified dynamically at run time by setting values in the
local environment.
The SOAP nodes act and are configured differently in the two different
operation modes.
- If you configure a node in Gateway mode, some node properties
are disabled because they are not applicable in Gateway mode.
- Transport properties must be configured. The transport-specific
properties are mandatory depending on the Transport property; for example,
the JMS transport properties are mandatory if the selected transport
is JMS.
- A SOAPInput node can
only be configured to receive messages of a single specified transport,
for example, HTTP. Use separate input nodes to send or receive messages
with different transports.
- A SOAPRequest node
can only be configured to send messages of a single specified transport,
for example, JMS. However, you can change the transport for any message
using the local environment.
- A SOAPAsyncRequest node
can only be configured to send and receive messages over a single
transport, for example, JMS, and this transport is always used for
the paired SOAPAsyncResponse node
to receive the response message. However, you can change the outbound
request transport for any message by using the local environment.
For example, if a SOAPAsyncRequest node
is configured to use JMS transport, its paired SOAPAsyncResponse node always
expects to receive responses over JMS, and this cannot be changed.
At run time, the SOAPAsyncRequest node
also then assumes JMS as the default transport. However, you can instruct
it to instead send the request over HTTP by using the local environment.
This request includes the WSA:ReplyTo JMS address for the SOAPAsyncResponse node.
- If a SOAPInput node
receives a one-way SOAP request, the node attempts to detect that
it is a one-way message. However, the node cannot detect all cases,
and therefore it is sometimes necessary to instruct the SOAPReply node that it is a
one-way message, by using the local environment. For example:
SET OutputLocalEnvironment.Destination.SOAP.Reply.Gateway.OneWay = True;
For
more information, see One-way messages in Gateway mode.
- If you use the SOAPAsyncRequest node
in Gateway mode, you must set the WS-Addressing Action property in the local environment
in the message flow before the SOAPAsyncRequest node. Set
this property by using OutputLocalEnvironment.Destination.SOAP.Request.WSA.Action.
- If you use the SOAPRequest node
in Gateway mode and the remote service provider expects a SOAPAction,
set the SOAPAction in the flow. In Gateway mode the SOAPAction from
a WSDL is not available to the node. For example, to set the SOAPAction
using ESQL:
SET OutputRoot.HTTPRequestHeader.SOAPAction = 'mySoapAction';
By default the SOAPRequest node
sends an empty SOAPAction of "".
- If you use the SOAPRequest node
in Gateway mode and are using WS-Addressing, you must set the WS-Addressing Action property in the local environment
in the message flow before the SOAPRequest node. Set this
property by using OutputLocalEnvironment.Destination.SOAP.Request.WSA.Action.
- In Gateway mode, you can add inbound "must understand" headers
to the SOAPInput node or
to the SOAPRequest and SOAPAsyncRequest nodes by specifying
the details on the node property. However, if you will be adding services
dynamically, where all the "must understand" headers cannot be known
in advance, you can add these headers with a wildcard (*)
for name, namespace, operation, or any combination of the three. This
removes the need to redeploy your message flow when new services are
added. However, consider that if you add a wildcard for the name,
namespace, and also operation, this means that all headers with a
"must understand" flag are allowed into the flow.
- If you use the SOAPReply node
as part of a façade message flow, with the SOAPInput node set to Gateway
mode, and the SOAPRequest node
acting in WSDL mode, disable validation on the SOAPReply node or add an explicit
Message Set in the Properties folder as documented above. If you do
not disable validation or reference a Message Set in the Properties
folder, parsing errors occur when the message is serialized.
- In Gateway mode, the SOAP nodes send SOAP 1.1 messages by default,
although they also accept inbound SOAP 1.2 messages. To send an outbound
SOAP 1.2 message, set the SOAP.Context field to indicate
that SOAP 1.2 is required. For example, to set this field using ESQL:
SET OutputRoot.SOAP.Context.SOAP_Version = '1.2';
The
outbound message then uses a SOAP 1.2 SOAP Envelope. You can also
set the namespace prefix used by the SOAP Envelope. For example, by
using ESQL:DECLARE soapenc NAMESPACE 'http://www.w3.org/2003/05/soap-envelope';
SET OutputRoot.SOAP.Context.Namespace.(SOAP.NamespaceDecl)xmlns:soap12 = soapenc;
SET OutputRoot.SOAP.Context.SOAP_Version = '1.2';
In
this example, soap12 is the prefix used in the outbound
message.