IBM Integration Bus, Version 9.0.0.8 Operating Systems: AIX, HP-Itanium, Linux, Solaris, Windows, z/OS

See information about the latest product version

HTTPAsyncRequest node

Use the HTTPAsyncRequest node with the HTTPAsyncResponse node to construct a pair of message flows that interact with a web service asynchronously.

The HTTPAsyncRequest node is available in the following operation modes:
  • Developer
  • Standard
  • Advanced
  • Express
  • Scale
  • Adapter
For more information, see Operation modes.

This topic contains the following sections:

Purpose

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.

Depending on the configuration, this node constructs an HTTP or an HTTP over SSL (HTTPS) request from the specified contents of the input message, and sends this 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. The HTTPAsyncRequest node generates HTTP headers if they are required by your configuration.

The HTTPAsyncRequest node is contained in the HTTP drawer of the palette, and is represented in the IBM® Integration Toolkit by the following icon:

HTTPRequest node icon

Using the HTTPAsyncRequest node to issue a request to a web service

An HTTP request has two parts:
  1. The URL of a service.
  2. A stream of data that the remote server processes in order to send back a response, which is often a SOAP or other web service message in XML.

The URL is of the format http://<address>[:<port>]/<function>; for example, http://localhost:7080/request. This URL can be specified statically in the HTTPAsyncRequest node parameters as a field in the message itself, or dynamically as a field in the local environment.

The data must be in CCSID 1208 format for most requests. If the request is successful, the HTTPResponse is returned to the paired HTTPAsyncResponse node.

You can use an HTTP proxy to route a request through an intermediate site. You can run tools as a proxy to see the request and the response, and thereby debug your flows. The HTTP destination is as seen by the proxy; if you specify the HTTP destination of localhost, and your HTTP proxy is running on a different computer, the request is routed to the remote proxy computer, not the computer from which the original request was issued.

Timeouts

You can specify a timeout interval, 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, the request and an exception are propagated to the Failure terminal of the HTTPAsyncRequest node. Similarly, if a timeout occurs during the response phase of processing, an exception 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 rare 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.

Using the HTTPAsyncRequest node in a message flow

The HTTPAsyncRequest node can be used in any message flow that must send an HTTP request and receive a response asynchronously. The most common example is a message flow that calls a web service.

For more information about working with HTTP, see Processing HTTP messages.

Handling errors

The node interacts directly with an external service using TCP/IP; therefore it can experience errors that are generated by TCP/IP. For example, no route to host or connection refused. If the node detects these errors, it generates an exception, populates the exception list with the error information that is received, and routes the input message unchanged to the Failure terminal.

Terminals and properties

The HTTPAsyncRequest node terminals are described in the following table.

Terminal Description
In The input terminal that accepts a message for processing by the node.
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.

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 BAR file to deploy it).

The HTTPAsyncRequest node Description properties are described in the following table.

Property M C Default Description
Node name No No The node type, HTTPAsyncRequest 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 HTTPAsyncRequest node Basic properties are described in the following table.

Property M C Default Description mqsiapplybaroverride command property
Unique identifier Yes No   This property is the unique identifier that links a pair of HTTPAsyncRequest and HTTPAsyncResponse nodes. asyncResponseCorrelator
Web service URL Yes Yes   The URL for the web service. You must provide this in the form http://hostname[:port]/[path] where
  • http://hostname must be specified.
  • port has a default of 80. If you specify a value, you must include the : before the port number.
  • path has a default of /. If you specify a value, you must include the / before the path.

The HTTPAsyncRequest node determines the URL for the web service to which it sends a request. Select one of the following three options; the node checks these in the order shown (that is, the first always overrides the second, the second overrides the third):

  1. X-Original-HTTP-URL in the HTTPRequest header in the input message
  2. LocalEnvironment.Destination.HTTP.RequestURL in the input message
  3. The Web service URL property

The first two options provide dynamic methods to set a URL for each input message as it passes through the message flow. To use either of these options, include a Compute node in the message flow, before the HTTPAsyncRequest node, to create and initialize the required value.

The third option provides a value that is fixed for every message that is received in this node. Set this property to contain a default setting that is used if the other fields have not been created, or contain a null value. If either field contains a value, the setting of this property is ignored. The Web service URL property must contain a valid URL or the deployment fails. Ensure that the value that you set in X-Original-HTTP-URL or the LocalEnvironment.Destination.HTTP.RequestURL is also a valid URL; if it is not, the node uses the default setting from the Web service URL property.

URLSpecifier
Request timeout (sec) Yes Yes 120 The value of the wait time for the remote web server to send a response to the HTTPAsyncResponse node. The valid range is 1 through (231)-1. You cannot enter a value that represents an unlimited wait.

For more information about timeout behavior, see Timeouts.

timeoutForServer

The HTTPAsyncRequest node HTTP Settings properties are described in the following table.

Property M C Default Description mqsiapplybaroverride command property
HTTP(S) proxy location No Yes   The proxy server to which requests are sent. This value must be in the form hostname:port. httpProxyLocation
HTTP method No No POST The HTTP method. Valid values are POST, GET, PUT, DELETE, and HEAD. By default, the HTTPAsyncRequest node uses the HTTP POST method when it connects to the remote web server. HEAD is used to determine whether a service is available - for example, by a Network Dispatcher trying to work out which servers are available - and sends back the correct headers (including content-length) but no body data.  
Use compression No Yes None This property controls whether the content of the HTTP request is compressed. You can choose a value from none, gzip, zlib (deflate), and deflate. If the request is compressed, the Content-Encoding header is set to indicate that the content is compressed.

zlib (deflate) represents RFC 1950 + RFC 1951 combined.

deflate represents RFC 1951 only.

The default value is none, meaning that the content of the request is not compressed.

requestCompressionType
Attention: The HTTPRequest or HTTPAsyncRequest node always rewrites the Content-Length header, even if you have cleared Generate default HTTP headers from input or request. This action ensures that the content is correct.

The HTTPAsyncRequest node SSL properties are described in the following table.

Property M C Default Description mqsiapplybaroverride command property
Protocol No Yes TLS Specify the SSLProtocol property to use when making an HTTPS request. Both ends of an SSL connection must agree on the protocol to use. Therefore, the selected protocol must be one that the remote server can accept. The following options are available:
  • SSL. This option tries to connect using the TLS protocol first, but enables the handshake to fall back to the SSLv2 protocol where the SSLv2 protocol is supported by the underlying JSSE provider.
  • SSLv3. This option tries to connect with the SSLv3 protocol only. Fallback to SSLv2 is not possible.
    Note: SSLv3 is disabled by default in IBM Integration Bus Version 9.0, because SSLv3 is no longer considered secure.
  • TLS. This option is the default. This option tries to connect with the TLS protocol only. Fallback to SSLv2 is not possible.
  • TLSv1.0. This option attempts to connect with the TLS v1.0 protocol only. Fallback to SSLv3 or SSLv2 is not allowed.
  • TLSv1.1. This option attempts to connect with the TLS v1.1 protocol only. Fallback to SSLv3, SSLv2, or TLSv1.0 is not allowed.
  • TLSv1.2. This option attempts to connect with the TLS v1.2 protocol only. Fallback to SSLv3, SSLv2, TLSv1.0, or TLSv1.1 is not allowed.
  • SSL_TLS. This option enables all SSL v3.0 and TLS v1.0 protocols. Fallback to SSLv2 is not allowed.
  • SSL_TLSv2. This option enables all SSL v3.0 and TLS v1.0, v1.1, and v1.2 protocols. Fallback to SSLv2 is not allowed.
protocol
Allowed SSL ciphers No Yes   A comma-separated list of ciphers to use when making an SSL request.

Use this setting to specify a single cipher (such as SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA) or a list of ciphers that are the only ones used by the connection. This set of ciphers must include one or more that are accepted by the remote server. A comma is used as a separator between the ciphers.

The default value is an empty string, which enables the node to use any, or all, of the available ciphers during the SSL connection handshake. This method gives the greatest scope for making a successful SSL connection.

allowedCiphers
Enable SSL certificate hostname checking No Yes Yes This property specifies whether the host name of the server that is receiving the request must match the host name in the SSL certificate. hostnameChecking
SSL client authentication key alias No Yes "" (empty string) This property specifies an SSL authentication alias for the client-side of an HTTPAsyncRequest connection. Taking the default value means that the first appropriate key is chosen for you automatically. keyAlias
Enable certificate revocation list checking No Yes Not selected This property specifies whether CRL checking should be enabled for SSL connections enableCRLCheck

The HTTPAsyncRequest node Advanced properties are described in the following table.

Property M C Default Description mqsiapplybaroverride command property
Generate default HTTP headers from input No No Selected If you select this check box, an HTTPRequestHeader is generated. If you clear this check box, a valid HTTPRequestHeader must exist in the input message.

To control the contents of the HTTPRequestHeader that is included in the request message, include a Compute node that adds an HTTPRequestHeader to the input message before this HTTPAsyncRequest node in the message flow, and clear this check box.

  • If you have selected Generate default HTTP headers from input and the input message includes an HTTPRequestHeader, the HTTPAsyncRequest node extracts web service headers from the input HTTPRequestHeader and adds any unique web service headers, except Host (see the following table), that are present in an HTTPInputHeader, if one exists in the input message. (An HTTPInputHeader might be present if the input message has been received from a web service by the HTTPInput node.)

    The HTTPAsyncRequest node also adds the web service headers shown in the following table, with default values, if these are not present in the HTTPRequestHeader or the HTTPInputHeader.

    Header Default value
    SOAPAction "" (empty string)
    Content-Type text/xml; charset=ccsid of the message body

    Unless the input message is in the JSON domain, where the default is:

    application/json; charset=ccsid of the message body

    Host The host name to which the request is to be sent.

    The HTTPAsyncRequest node also adds the optional header Content-Length with the correct calculated value, even if this value is not present in the HTTPRequestHeader or the HTTPInputHeader.

  • If you have selected Generate default HTTP headers from input and the input message does not include an HTTPRequestHeader, the HTTPAsyncRequest node extracts web service headers, except Host, from the HTTPInputHeader (if it is present in the input message). The HTTPAsyncRequest node adds the required web service headers with default values, if these values are not present in the HTTPInputHeader.
  • If you have cleared Generate default HTTP headers from input and the input message includes an HTTPRequestHeader, the node extracts all web service headers present in the input HTTPRequestHeader. The node does not check for the presence of an HTTPInputHeader in the input message, and it does not add the required web service headers if they are not supplied by the input HTTPRequestHeader.
  • If you have cleared Generate default HTTP headers from input and the input message does not include an HTTPRequestHeader, no web service headers are generated. The HTTPAsyncRequest node does not check for the presence of an HTTPInputHeader in the input message and does not add any required web service header. The request message is propagated to the web service without an HTTPRequestHeader. This action typically causes an error to be generated by the web service, unless the web service is configured to handle the message contents.
If you have selected Use compression or Accept compressed responses by default, the Content-Encoding and Accept-Encoding HTTP header fields are populated regardless of whether you have selected Generate default HTTP headers from input:
  • If the value of Use compression is not the default of None, the Content-Encoding HTTP header is populated with this value, and the bit stream is compressed. If the Content-Encoding header is already present in an existing HTTP header, this field is updated with the value of the Use compression property. If the existing Content-Encoding header already starts with the named compression function, then no further compression takes place. If the Content-Encoding header starts with deflate, then no compression takes place irrespective of whether ZLIB (deflate)or deflate is selected.
  • If you have selected Accept compressed responses, the Accept-Encoding field is populated. If this field is already present in an existing HTTP header, the existing value overrides the property on the node. However, if a compressed response is received, it is not decompressed.
 
Accept compressed responses by default No Yes Cleared This property indicates whether the HTTPAsyncResponse node handles compressed responses by default. If the request header does not contain an Accept-Encoding header and this option is selected, the node sets the Accept-Encoding header to "gzip, deflate", and any compressed response that is received is decompressed by the response node.

If the message propagated to the HTTPAsyncResponse node includes an Accept-Encoding header, the message flow or client application should handle any compressed response. Therefore selecting this option has no effect in that case.

acceptCompressedResponses
The Monitoring properties of the node are described in the following table.
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.

Local environment overrides

You can dynamically override set values in the local environment in the same way as setting values in other elements of a message. The following values can be set under LocalEnvironment.Destination.HTTP.
Setting Description
Compression Overrides the Use compression property on the node. For example:
SET OutputLocalEnvironment.Destination.HTTP.Compression =
 'gzip';
To set a minimum size (in bytes) at which compression is applied, use the following override:
SET OutputLocalEnvironment.Destination.HTTP.MinimumCompressionSize = 1048576;
ProxyConnectHeaders Specifies additional headers that are used if the outbound request is an SSL connection through a proxy. These additional headers are sent with the initial CONNECT request to the proxy. For example, you can send proxy authentication information to a proxy server when you are using SSL. You can send multiple headers but each one must be separated by a carriage return and a line feed (ASCII 0x0D 0x0A), in accordance with RFC2616; for example:
DECLARE CRLF CHAR CAST(X'0D0A' AS CHAR CCSID 1208);
SET OutputLocalEnvironment.Destination.HTTP.ProxyConnectHeaders =
'Proxy-Authorization: Basic Zm5lcmJsZTpwYXNzd29yZA==' || CRLF || 
'Proxy-Connection: Keep-Alive' || CRLF;
This setting is used only if the request is an SSL request through a proxy server. To send proxy authentication information for a non-SSL request, specify the individual headers in the HTTPRequestHeader folder, as shown in the following example:
SET OutputRoot.HTTPRequestHeader."Proxy-Authorization" =
 'Basic Zm5lcmJsZTpwYXNzd29yZA==';
SET OutputRoot.HTTPRequestHeader."Proxy-Connection" = 'Keep-Alive';
ProxyURL Overrides the HTTP(S) proxy location property on the node. For example:
SET OutputLocalEnvironment.Destination.HTTP.ProxyURL = 'my.proxy';
QueryString Allows the setting of outbound query string parameters. Each parameter must be set individually. For example:
SET OutputLocalEnvironment.Destination.HTTP.QueryString.param1 = 'my"Value"1';
SET OutputLocalEnvironment.Destination.HTTP.QueryString.param2 = 'my"Value"2';
The above ESQL results in the following query string being encoded (according to http://tools.ietf.org/html/rfc3986) and sent with the outbound request:
?param1=my%22Value%221&param2= my%22Value%222
If the destination URL already has one or more query parameters, additional parameters specified here are appended to the existing list.
QueryStringCCSID Specifies that, before encoding, the query string parameters must be converted into a character set other than the default, which is UTF-8. Any query string parameters are first converted into the specified CCSID before the resulting string is encoded, according to RFC3986. For example:
SET OutputLocalEnvironment.Destination.HTTP.QueryStringCCSID = 943;
The above ESQL results in any QueryString parameters being converted to the 943 code page before they are encoded. Note: Any query string parameters must contain the data in unicode.
QueryStringPercentEncodeSpace Specifies that any space character in the QueryString be percent encoded and then sent with outbound request. By default any space character in the QueryString is converted to "+" character. For example:
SET OutputLocalEnvironment.Destination.HTTP.QueryStringPercentEncodeSpace = TRUE;
QueryStringSendWithRedirect Specifies that the QueryString be sent with HTTP(S) redirect. For example:
SET OutputLocalEnvironment.Destination.HTTP.QueryStringSendWithRedirect = TRUE;
QueryStringDoNotPercentEncodeCharacters Specifies any characters in the QueryString that are not to be percent encoded while the URI is built. For example:
SET OutputLocalEnvironment.Destination.HTTP.QueryStringDoNotPercentEncodeCharacters = 'ch"ar';
QueryStringSemicolonSeparator Specifies that the semicolon be used as a separator between query strings instead of "&". For example:
SET OutputLocalEnvironment.Destination.HTTP.QueryStringSemicolonSeparator = TRUE;
RequestLine.RequestURI Overrides the RequestURI, which is the path after the URL and port. For example:
SET OutputLocalEnvironment.Destination.HTTP.RequestLine.RequestURI = '/abc/def';
RequestLine.HTTPVersion Overrides the HTTP version property on the node. For example:
SET OutputLocalEnvironment.Destination.HTTP.RequestLine.HTTPVersion = 'HTTP/1.1';
RequestLine.Method Overrides the HTTP method property on the node. For example:
SET OutputLocalEnvironment.Destination.HTTP.RequestLine.Method = 'GET';
RequestURL Overrides the Web service URL property on the node. For example:
SET OutputLocalEnvironment.Destination.HTTP.RequestURL = 'http://ibm.com/abc/';
SSL authentication alias Overrides the SSL authentication alias for the client-side of an HTTP connection on the node. For example:
SET OutputLocalEnvironment.Destination.HTTP.KeyAlias = 'Key1Alias';
SSLProtocol Overrides the SSLProtocol. For example:
SET OutputLocalEnvironment.Destination.HTTP.SSLProtocol = 'TLS';
Valid values are: SSL, SSLv3, TLS, TLSv1, TLSv1.1, TLSv1.2, SSL_TLS, and SSL_TLSv2
Note: SSLv3 is disabled by default in IBM Integration Bus Version 9.0, because SSLv3 is no longer considered secure.
SSLCiphers Overrides the Allowed SSL Ciphers property on the node. For example:
SET OutputLocalEnvironment.Destination.HTTP.SSLCiphers =
 'SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA';
UserContext You can store BLOB context data in the following location in the local environment. The HTTPAsyncResponse node can later retrieve this data.
SET OutputLocalEnvironment.Destination.HTTP.UserContext = x'aabbccddeeff11223344556677889900';
Data stored in the UserContext must be in BLOB format.
Enable CRL checking Overrides the Enable Certificate Revocation List checking property on the node. For example:
SET OutputLocalEnvironment.Destination.HTTP.EnableCRLCheck = 'true';

Working with WrittenDestination data

After the request has been made, the WrittenDestination folder in the local environment is updated with the URI to which the request was sent and compression details (if used). A WrittenDestination for an HTTPAsyncRequest node has the following format, with Compression present only if it is used:
WrittenDestination = (
   HTTP  = (
      RequestURL = 'http://127.0.0.1:7800/HTTPFLOW' (CHARACTER)
      Compression = (
        OriginalSize = 53 (INTEGER)
        CompressedSize = 71 (INTEGER)
      )
   )
)

bc19308_.htm | Last updated Friday, 21 July 2017