Use the HTTPAsyncRequest node with the HTTPAsyncResponse node to construct a pair of message flows that interact with a Web service asynchronously.
This topic contains the following sections:
The HTTPAsyncRequest node sends a Web service request, but the node does not wait for the associated Web service response to be received. The Web service response is received by the HTTPAsyncResponse node, which can be in a separate message flow but must be in the same integration server. The nodes are used as a pair, and correlate responses against the original requests using a unique identifier. The HTTPAsyncRequest node passes the request socket to the HTTPAsyncResponse node for the backend server to use for the response. If the latency of the backend server is high, it might not respond within the socket timeout.
Passing the HTTP socket to the HTTPAsyncResponse node enables the message flow to retrieve the next message from the queue without waiting for the response, and thereby uses threads and storage more efficiently than a synchronous message flow.
The HTTPAsyncResponse node handles messages in the following message domains:
The HTTPAsyncResponse node is contained in the HTTP drawer of the palette, and is represented in the IBM® Integration Toolkit by the following icon:
Use the HTTPAsyncResponse node as a pair with the HTTPAsyncRequest node to make an HTTP request and asynchronously receive a response. The HTTPAsyncRequest node sends a request to the web service. The HTTPAsyncResponse node receives the response from the web service, and parses the response for inclusion in its output tree.
For more information about working with HTTP, see Processing HTTP messages.
If the local environment property LocalEnvironment.Destination.HTTP.RequestIdentifier was provided to the paired HTTPAsyncRequest node, this is passed to the local environment for the HTTPAsyncResponse node.
The node interacts directly with an external service using TCP/IP; it can, therefore, experience the following types of error:
If the node detects these errors, it generates an exception and propagates it to the Failure terminal.
The reply is produced as a BLOB message because the node cannot determine in what format the reply will be. Messages with a redirection status code (3xx) are also handled in the same way.
The HTTPAsyncResponse node treats the 100 series status codes as a 'continue' response, discards the current response, and waits for another response from the web server.
The 200 series status codes are treated as success. The node properties determine the format of the output message that is generated, and the response is routed to the Out terminal of the node.
The 300 series status codes are for redirection. Redirection is not supported by the HTTPAsyncResponse node, and redirection codes are treated as an error.
Set OutputRoot.XMLNS.error850 = CAST(InputRoot.XMLNS.error.BLOB as CHAR CCSID 850);
For
information about HTTP, see Hypertext Transfer Protocol - HTTP/1.1.
For more information about HTTP return codes, see HTTP Response codes.You can specify a timeout interval on the HTTPAsyncRequest node, so that if the whole request-response operation takes longer than the specified duration, the request is propagated to the Failure terminal on one of the paired nodes. The timeout interval applies to the interval that starts with the request being sent by the HTTPAsyncRequest node, and ends with the response being completely received by the HTTPAsyncResponse node.
For each request that the HTTPAsyncRequest node processes it uses a connection to send the request, and passes the connection to the paired HTTPAsyncResponse node for the response. If the timeout interval is specified, the socket is closed if the interval expires. This closure ensures that a request gets only the correct response, and any response data for a request that has timed out is discarded.
The request-response processing is split between the HTTPAsyncRequest node and the HTTPAsyncResponse node. If a timeout occurs during the request phase of processing, an exception is propagated to the Failure terminal of the HTTPAsyncRequest node. Similarly, if a timeout occurs during the response phase of processing, the request is propagated to the Failure terminal of the HTTPAsyncResponse node.
In most cases the timeout would occur when waiting for a server response, in which case the Failure terminal of the HTTPAsyncResponse node is used. In some cases a timeout might occur when the request node sends data to the server. In this case, the Failure terminal of the HTTPAsyncRequest node is used.
The HTTPResponse header, which contains the headers that are returned by the remote web service, is the first header in the message (after Properties) that is propagated from the node. This action is taken regardless of the options that are selected. Therefore, for the response from the HTTPAsyncResponse node to be put to a WebSphere® MQ queue, manipulate the headers so that an MQMD is the first header (after Properties).
SET OutputRoot = InputRoot;
SET OutputRoot.HTTPResponseHeader = NULL;
SET OutputRoot = InputRoot;
DECLARE HTTPHeaderRef REFERENCE TO OutputRoot.HTTPResponseHeader;
DETACH HTTPHeaderRef;
ATTACH HTTPHeaderRef TO OutputRoot.MQMD AS NEXTSIBLING;
The HTTPAsyncResponse node terminals are described in the following table.
Terminal | Description |
---|---|
Failure | The output terminal to which the message is routed if a failure is detected during processing in the node. |
Out | The output terminal to which the message is routed if it represents successful completion of the web service request, and if further processing is required within this message flow. |
Error | The output terminal to which messages that include an HTTP status code that is not in the range 200 through 299, including redirection codes (3xx), is routed. Redirection is not supported by the HTTPAsyncResponse node. |
Catch | The output terminal to which the message is routed if an exception is thrown downstream and caught by this node. |
The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk on the panel if you must enter a value when no default is defined); the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the broker archive file to deploy it).
The HTTPAsyncResponse node Description properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Node name | No | No | The node type, HTTPAsyncResponse | The name of the node. |
Short description | No | No | A brief description of the node. | |
Long description | No | No | Text that describes the purpose of the node in the message flow. |
The HTTPAsyncResponse node Basic property is described in the following table.
Property | M | C | Default | Description | mqsiapplybaroverride command property |
---|---|---|---|---|---|
Unique identifier | Yes | No | Specify the unique identifier that links your pair of HTTPAsyncRequest and HTTPAsyncResponse nodes. | asyncRequestCorrelator |
The HTTPAsyncResponse node Response Message Parsing properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Message domain | No | No | BLOB | The domain that is used to parse the message. If the field is blank then the default is BLOB. |
Message model | No | No | Cleared | The name or location of the message model schema file in which the message is defined. This list is populated with all available message model schema files for the Message domain that you have selected. |
Message | No | No | Cleared | The name or location of the message root within your message model schema file. This list is populated with all available messages that are defined in the Message model that you have selected. |
Physical format | No | No | Cleared | The name of the physical format of the message. If you are using the MRM or IDOC parser, select the physical format of the incoming message from the list. This list includes all the physical formats that you have defined for the selected message model. If you set the Message domain property to DataObject, you can set this property to XML or SAP ALE IDoc. Set this property to SAP ALE IDoc when you have to parse a bit stream from an external source and generate a message tree. |
The HTTPAsyncResponse node Parser Options properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Parse timing | No | No | On Demand | This property controls when a response message
is parsed. Valid values are On
Demand, Immediate,
and Complete. The default
value is On Demand, which
causes parsing of the message to be delayed. For a full description of this property, see Parsing on demand. |
Build tree using XML schema data types | No | No | Cleared | This property controls whether the XMLNSC parser creates syntax elements in the message tree with data types taken from the XML schema. You can select this property only if you set the Validate property on the Validation tab to Content or Content and Value. |
Use XMLNSC compact parser for XMLNS domain | No | No | Cleared | This property controls whether the XMLNSC Compact Parser is used for messages in the XMLNS Domain. If you set this property, the response message data is displayed under XMLNSC in nodes that are connected to the output terminal when the input MQRFH2 header or Response Message Parsing properties Domain is XMLNS. |
Retain mixed content | No | No | Cleared | This property controls whether the XMLNSC parser creates elements in the message tree when it encounters mixed text in a response message. If you select the check box, elements are created for mixed text. If you clear the check box, mixed text is ignored and no elements are created. |
Retain comments | No | No | Cleared | This property controls whether the XMLNSC parser creates elements in the message tree when it encounters comments in a response message. If you select the check box, elements are created for comments. If you clear the check box, comments are ignored and no elements are created. |
Retain processing instructions | No | No | Cleared | This property controls whether the XMLNSC parser creates elements in the message tree when it encounters processing instructions in a response message. If you select the check box, elements are created for processing instructions. If you clear the check box, processing instructions are ignored and no elements are created. |
Opaque elements | No | No | Blank | This property is used to specify a list of elements in the response message that are to be opaquely parsed by the XMLNSC parser. Opaque parsing is performed only if validation is not enabled (that is, if the Validate property is set to None); entries that are specified in Opaque Elements are ignored if validation is enabled. |
The HTTPAsyncResponse node Validation properties are described in the following table.
For a full description of these properties see Validation properties.
Property | M | C | Default | Description | mqsiapplybaroverride command property |
---|---|---|---|---|---|
Validate | No | Yes | None | This property controls whether validation takes
place. Valid values are None, Content and Value, Content, and Inherit. For more details see Validating messages and Validation properties. |
validateMaster |
Failure action | No | No | Exception | This property controls what happens if validation fails. You can set this property only if you set Validate to Content or Content and Value. Valid values are User Trace, Local Error Log, Exception, and Exception List. |
Property | M | C | Default | Description |
---|---|---|---|---|
Events | No | No | None | Events that you have defined for the node are
displayed on this tab. By default, no monitoring events are defined
on any node in a message flow. Use Add, Edit,
and Delete to create, change or delete monitoring
events for the node; see Configuring monitoring event sources using monitoring properties for details. You can enable and disable events that are shown here by selecting or clearing the Enabled check box. |
You can retrieve information that was set by the paired HTTPAsyncRequest node from the following property under LocalEnvironment.Destination.HTTP:
Setting | Description |
---|---|
UserContext | You can retrieve context data that was stored
by the HTTPAsyncRequest node
from the following location in the local environment:
Context
data is stored as a BLOB. To retrieve context data, assign the variable
as a BLOB type or use a CAST. For
example:
|