HTTPAsyncResponse node

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:

• DFDL
• XMLNSC
• JSON
• BLOB
• MIME
• MRM
• XMLNS

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.

Handling errors

The node interacts directly with an external service using TCP/IP; it can, therefore, experience the following types of error:

• Errors that are generated by TCP/IP, for example connection reset by peer.

  If the node detects these errors, it generates an exception and propagates it to the Failure terminal.

• Errors that are returned by the web server. These errors are represented by HTTP status codes that are outside the range 100 - 299. If the node detects these errors, it routes the reply to the Error terminal while following the properties specified on the Error tab.

  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.

HTTP Response Codes

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.

The 400 and 500 series status codes are errors. If the request is sent successfully by the HTTPAsyncRequest node, but the web service is not successful, the HTTPResponse is inserted into the message tree, and propagated to the Error terminal of the HTTPAsyncResponse node. You might have to use a Compute node to cast this response to an appropriate code page to be able to display the data, for example:

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.

Timeouts

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.

Manipulating headers

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.

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.

The HTTPAsyncResponse node Basic property is described in the following table.

The HTTPAsyncResponse node Response Message Parsing properties are described in the following table.

The HTTPAsyncResponse node Parser Options properties are described in the following table.

The HTTPAsyncResponse node Validation properties are described in the following table.

For a full description of these properties see Validation properties.

You can retrieve information that was set by the paired HTTPAsyncRequest node from the following property under LocalEnvironment.Destination.HTTP:

SET myVar = InputLocalEnvironment.Destination.HTTP.UserContext;

DECLARE myVar BLOB;
SET myVar = InputLocalEnvironment.Destination.HTTP.UserContext;