Start of change
WebSphere Message Brokers
File: ac56200_.dita
Writer: Kate Hostler

Reference topic

This build: July 31, 2007 21:21:28

SOAPAsyncRequest node

This topic describes the SOAPAsyncRequest node.

Purpose

Use the SOAPAsyncRequest node in conjunction with the SOAPAsyncResponse node to construct a pair of message flows that start a Web service asynchronously. The SOAPAsyncRequest node sends a Web service request, but the node does not wait for the associated Web service response to be received (the message flow is not blocked at this point

Draft comment:
when is it blocked? why is it blocked?
). The Web service response is received by the SOAPAsyncResponse node, which is in a separate message flow. The nodes are used as a pair, and correlate responses against the original requests.

The SOAPAsyncRequest node is the first half of the asynchronous request and response node pair. The SOAPAsyncRequest node starts a remote SOAP-based Web service. The request message is sent from the SOAPAsyncRequest node, but the SOAPAsyncRequest node does not receive the response. The response is received by a SOAPAsyncResponse node that is running on a different thread. The SOAPAsyncResponse node is typically at the beginning of a different message flow. The WSA:ReplyTo header must be set to point to the corresponding SOAPAsyncResponse node in the form:
http://thisEG:7080/correspondingAsyncResponseNodeID
The SOAP role for this node is set to RequestingSOAPNode. Although the SOAPAsyncRequest node is similar to the input side of the HTTPRequest node, the SOAPAsyncRequest node does not have the advanced properties for selecting which part of the message is sent to the remote Web server because the SOAPAsyncRequest node expects to send a fully formed SOAP message in the SOAP domain. The message that leaves the Out terminal is the same as the message that arrived at the In terminal.

The SOAPAsyncRequest node is WSDL-driven, in a similar manner to the SOAPRequest node.

The SOAPAsyncRequest node is contained in the Web Services drawer of the palette, and is represented in the workbench by the following icon:

SOAPAsyncRequest node icon

Using this node in a message flow

Look at the following sample to see how to use this node:
  • SOAP sample
*!ENTITY!**!ENTITY!*LINK TO SOAP SAMPLE>>

You can view samples only when you use the information center that is integrated with the Message Brokers Toolkit.

Configuring the SOAPAsyncRequest node

When you have put an instance of the SOAPAsyncRequest node into a message flow, you can configure it; see Configuring a message flow node. The properties of the node are displayed in the Properties view.

All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk.

  1. Optional: On the Description tab, enter a short description, a long description, or both. You can also rename the node on this tab.
  2. On the Basic tab,
    Draft comment:
    (This tab is similar to the Basic tab of the SOAPRequest node.
    you must set the following property:
    • Correlation ID. This property is mandatory. You must specify the unique URL fragment that is common to your pair of SOAPAsyncRequest and SOAPAsyncResponse nodes.
      Draft comment:
      Toolkit says : "specify unique URL fragment common for a pair of asynchronous request/response nodes". Feature doc says "Enter the name of the of the corresponding asynchronous request node." Which is right?
    You must configure the following WSDL Properties:
    • WSDL file name.
      Draft comment:
      (Same as SOAPInput node)
      This property type is String. This property is mandatory. You can change the WSDL file you use to configure this node in the following ways:
      • Click Browse to select a WSDL file to import from the workspace.
      • Type in a file name that is relative to the message set project in which the WSDL exists; for example, type in the full path name of the WSDL but exclude the message set project name.
      • Drag and drop a WSDL file onto the node.

      If you make a new selection then the WSDL file is validated. The WSDL validation is the same as the validation that is done when you drag and drop the WSDL file onto a flow. After the file is validated the message set to which it belongs is added as a reference project if it does not already exist.

      If the WSDL file is not validated, or an incorrect file name is entered, an error message is displayed on the editor and the corresponding WSDL properties are blank.

      If the same WSDL file name is entered into the text box then no validation or updates occur. To refresh the WSDL file contents click Browse, or drag and drop the WSDL file onto the node.

      Compile Time Validation: At the time of flow compilation, it is verified that there is one instance only of the referenced WSDL in the symbol table. An error is generated on the node if the referenced WSDL cannot be resolved, or if there is more than one WSDL file of the same name in the workspace. For a multi-file WSDL, verification takes place only for the main WSDL, and it is also verified that the imports inside the main WSDL have been imported.

      The following situations lead to error conditions on this property editor:
      • The WSDL file does not come from a message set project, or the WSDL was not imported as described in the following topics:
      • The WSDL file contains no HTTP bindings.
      • The WSDL file contains no Port type.
      • An empty string is entered in the text box after a valid WSDL file name has been entered.
      • The WSDL file name entered in the text box does not exist.
    • Port type.
      Draft comment:
      (Same as SOAPInput node)
      This property type is String. This property is mandatory. This field lists all of the Port types defined in the WSDL document.
      Draft comment:
      Which document?
      By default, the first Port type found in the WSDL that has an associated HTTP binding with it, is selected.
      Error Conditions:
      • Selected Port type does not contain at least one operation.
    • Imported binding.
      Draft comment:
      (Same as SOAPInput node)
      This property type is String. This property is mandatory. This property is updated every time that the Port type value changes. The field lists all SOAP bindings with HTTP transport (6.1) associated with the selected Port type. Bindings are listed in the same order in which they appear in the WSDL source. The selected binding is the one that has both ports and operations. If there is no such binding, then binding with ports is selected. If no bindings have ports then the first binding in the list is selected.
      Error Conditions:
      • No SOAP bindings (with HTTP transport) in the WSDL document are associated with the Port type.
      • Selected binding does not have any operations.
    • Binding operation.
      Draft comment:
      (Same as SOAPInput node)
      This property type is String. This property is mandatory. This field lists all of the operations defined by the selected Port type. The first operation in the list is selected by default.
    • Service port.
      Draft comment:
      (Similar to SOAPRequest node)
      This property type is String. This property is mandatory. This field is updated every time that the selected binding is updated. This field lists all WSDL ports that point to the selected binding. The first port for the binding is the selected port by default.
      Error Conditions:
      • No ports point to the selected binding.
    • Target namespace. This is a hidden String property on this tab. Target namespace is implemented as a read-only field. This property is updated with the Target namespace of the WSDL when the WSDL file name is configured.
  3. On the HTTP Transport tab,
    Draft comment:
    (This tab is the same as the HTTPTransport tab of the SoapRequest node)
    you can set the HTTP transport related properties:
    • Web service URL.
      Draft comment:
      (Same as HTTPRequest node)
      This property type is String. This property is mandatory and is automatically set from the SOAP address of the selected port. However, if you override the value then your value persists and the URL is not configured from the service port.
      You must provide this property 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.
    • Request timeout (in seconds). This property type is Integer. This property has the value of the wait time for the remote server to respond with an acknowledgement that the message has been received. The time in seconds that the node waits for a response from the Web service. The valid range is 1 to (231)-1. You cannot enter a value that represents an unlimited wait.
    • HTTP(S) Proxy Location. This property type is String.
      Draft comment:
      (Same as HTTPRequest node)
      In the HTTP(S) Proxy Location field, set the location of the proxy server to which requests are sent. This value must be in the form hostname:port.
    • SSL Protocol. This property type is Enum.
      Draft comment:
      (Same as HTTPRequest node)
      Specify the SSL Protocol that you want to use to make the request. The following options are available:
      ssl
      The default. This option attempts to connect using the SSLv3 protocol first, but the handshake can fall back to the SSLv2 protocol where the SSLv2 protocol is supported by the underlying JSSE provider.
      sslv3
      This option attempts to connect with the SSLv3 protocol only. The handshake cannot fallback to SSLv2.
      tls
      This option attempts to connect with the TLS protocol only. The handshake cannot fallback to SSLv3 or SSLv2.

      Both ends of an SSL connection must use the same protocol. The protocol must be one that the remote server can accept.

    • Allowed SSL Ciphers. This property type is String.
      Draft comment:
      (Same as HTTPRequest node)
      This setting enables you 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 list 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 allows the node to use any, or all, of the available ciphers during the SSL connection handshake. This method enables the greatest scope for making a successful SSL connection.
    • UseHTTPTransport. This is a hidden Boolean property on this tab. It is set to true when the WSDL file name property is configured.
    Draft comment:
    Look up SOAPRequest node
  4. Use the Advanced tab to define your headers.
    Draft comment:
    Look up SOAPRequest node
    • The Must understand headers property lists all of the SOAP headers for the broker runtime to mark as ‘understood’. Thus, the Axis 2 server does not signal SOAP faults if the SOAP input message contains one, or more, headers with Must understand headers turned on. The Must understand headers property configured on this tab will be applied to the corresponding SOAPAsyncResponse node that receives the reply from the remote server. This property is split into WSDL-defined SOAP headers and User-defined SOAP headers tables, each of which is a complex property:
      • The WSDL-defined SOAP headers table is read-only, and is populated based on the SOAP headers defined in the output part of the selected operations. By default, Must understand headers check boxes are selected for all entries in the WSDL-defined table. When the selected operation is updated, the WSDL-defined header table is updated accordingly. This property is generated in the CMF file.
      • The User-defined SOAP headers table. You can add custom headers (these are headers not defined in the WSDL) in the user-defined table. You can Add, Edit, and Delete in this table. You must ensure that the Must understand headers check box for the newly added custom header is selected in order for the header to be added to the Must understand headers list. This property is generated in the CMF file.
      Each table has the following layout:
      • Must understand headers column. If you select the check box in this column it indicates that the header listed in this row is added to the Must understand headers list.
      • Header name column.
      • Header namespace column.
  5. Use the Input Message Parsing tab, (information yet to be developed).
    Draft comment:
    Check this - is not on the Toolkit
  6. Use the Parser Options sub-tab, (information yet to be developed).
    Draft comment:
    Check this - is not on the Toolkit
  7. Use the Validation tab, (information yet to be developed).
    Draft comment:
    Check this - is not on the Toolkit
  8. Use the Security tab
    Draft comment:
    Same as SOAPRequest node
    to implement the security properties of the SOAPAsyncRequest node. The following properties are implemented on this tab:
    • Security profile. This property editor is editable and you can enter your own values. Valid values for this property are:
      • No Security. The default.
      • Default Propagation.
      Draft comment:
      This is supposed to be the same as the SOAPRequest node. However, the SOAPRequest node has two more values: Default LDAP and Default TFIM. Check this.
    • Consumer policy. This is a hidden String property on the node. Its purpose is to override the flow default.
  9. Use the WS-Security sub-tab of the Security tab to implement a complex property related to Web services security.
    Draft comment:
    Same as SOAPRequest node
    This complex property is in the form of a table and consists of two columns:
    • Alias
    • XPath Expression
    You can add XPath Expressions with an associated Alias value to the WS-Security table. The Alias is resolved in a Policy Set that is created by the administrator. The Policy Set resolves the Alias to either encrypt or sign the part of the message referred to by the XPath Expression. You can Add, Edit, and Delete in this table.

Terminals and properties

The SOAPAsyncRequest node terminals are described in the following table.

Terminal Description
Failure The output terminal to which a message is routed if a failure is detected when the message is propagated to the Out flow (such as a message validation failure). Failures routed to this terminal include those caused by the retry processing occurring before the retry propagates the message to the Out flow.
Out The output terminal to which the message is routed if it has been successfully put to the output queue, and if further processing is required within this message flow. If no errors occur within the input node, a message received from an external resource is always sent to the Out terminal first.

The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk 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 SOAPAsyncRequest node Description properties are described in the following table:

Property M C Default Description
Node name No No The node type The name of the node.
Short Description No No None A brief description of the node.
Long Description No No None Text that describes the purpose of the node in the message flow.

The SOAPAsyncRequest node Basic properties are described in the following table:

Property M C Default Description
Correlation ID Yes     Specify the unique URL fragment that is common to your pair of SOAPAsyncRequest and SOAPAsyncResponse nodes.
Draft comment:
Toolkit says : "specify unique URL fragment common for a pair of asynchronous request/response nodes". Feature doc says "Enter the name of the of the corresponding asynchronous request node." Which is right?
WSDL file name
Draft comment:
(Same as SOAPInput node)
Yes     This property type is String. You can change the WSDL file you use to configure this node in the following ways:
  • Click Browse to select a WSDL file to import from the workspace.
  • Type in a file name that is relative to the message set project in which the WSDL exists; for example, type in the full path name of the WSDL but exclude the message set project name.
  • Drag and drop a WSDL file onto the node.
Port type
Draft comment:
(Same as SOAPInput node)
Yes   By default, the first Port type found in the WSDL, that has an associated HTTP binding with it, is selected. This property type is String. The field lists all of the Port types defined in the WSDL document.
Error Conditions:
  • Selected Port type does not contain at least one operation.
Imported binding
Draft comment:
(Same as SOAPInput node)
Yes     This property type is String.

This property is updated every time that the Port type value changes. The field lists all of the SOAP bindings with HTTP transport (6.1) associated with the selected Port type. Bindings are listed in the same order in which they appear in the WSDL source. The selected binding is the one that has both ports and operations. If there is no such binding, then binding with ports is selected. If no bindings have ports then the first binding in the list is selected.

Error Conditions:
  • No SOAP bindings (with HTTP transport) in the WSDL document are associated with the Port type.
  • The selected binding does not have any operations.
Binding operation Yes     This property type is String.

This field lists all of the operations defined by the selected Port type. The first operation in the list is selected by default.

Service port
Draft comment:
(Same as SOAPInput node)
Yes     This property type is String. This field is updated every time that the selected binding is updated. This field lists all of the WSDL ports that point to the selected binding. The first port for the binding is the selected port by default.
Error Conditions:
  • No ports point to the selected binding.
Target namespace       Target namespace is implemented as a read-only field.

This property is a hidden String property. It is updated with the Target namespace of the WSDL when the WSDL file name is configured.

The SOAPAsyncRequest node HTTP Transport properties are described in the following table:

Property M C Default Description
Web service URL
Draft comment:
(Same as HTTPRequest node)
Yes (Yes)   This property type is String. The URL for the Web service. This property is automatically set from the SOAP address of the selected port. However, if you override the value then your value persists, and the URL is not configured from the service port.
You must provide this property 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.
Request timeout (in seconds)     120 This property type is Integer. This property has the value of the wait time for the remote server to respond with an acknowledgement that the message has been received.

The time in seconds that the node waits for a response from the Web service. The valid range is 1 to (231)-1. You cannot enter a value that represents an unlimited wait.

HTTP(S) proxy location
Draft comment:
(Same as HTTPRequest node)
No Yes   This property type is String. The proxy server to which requests are sent. This value must be in the form hostname:port.
SSL Protocol (if using SSL)
Draft comment:
(Same as HTTPRequest node)
No Yes ssl This property type is Enum. The SSL protocol to use when making an HTTPS request. Valid values are:
  • ssl
  • sslv3
  • tls
Allowed SSL ciphers (if using SSL)
Draft comment:
(Same as HTTPRequest node)
No Yes   This property type is String. A comma-separated list of ciphers to use when making an SSL request. The default value of an empty string means use all available ciphers.
useHttpTransport       This is a hidden Boolean property on this tab. It is set to true when the WSDL file name property is configured.

The SOAPAsyncRequest node Advanced properties are described in the following table:

Property M C Default Description
Must understand headers       The Must understand headers column is immediately to the left of the Header name column and contains a check box for each header. The check box is automatically selected for all of the entries in the WSDL-defined SOAP headers table.

You must ensure that the Must understand headers check box for the newly added custom header is selected in order for the header to be added to the Must understand headers list.

The Must understand headers property configured on this tab will be applied to the corresponding SOAPAsyncResponse node that receives the reply from the remote server.

WSDL-defined SOAP headers       This table is read-only, and is populated by the SOAP headers defined in the output part of the selected operations. The table is updated automatically when the selected operation is updated. This property is generated in the CMF file.
User-defined SOAP headers       You can add custom headers in this table. You can Add, Edit and Delete in this table. This property is generated in the CMF file.

The SOAPAsyncRequest node Security properties are described in the following table:

Property M C Default Description
Security profile     No Security Valid values are:
  • No Security
  • Default Propagation
This property editor is editable and you can enter your own values.
Consumer policy       This is a hidden property on the node to override the flow default.

The SOAPAsyncRequest node WS-Security properties are described in the following table:

Property M C Default Description
WS-Security       This complex property is in the form of a table and consists of two columns:
  • Alias
  • XPath Expression
You can add XPath Expressions with an associated Alias value to the WS-Security table. The Alias is resolved in a Policy Set that is created by the administrator. The Policy Set resolves the Alias to either encrypt or sign the part of the message referred to by the XPath Expression. You can Add, Edit and Delete in this table.
Draft comment:
add related links to topics ad30500_ and ad30510_
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:21:28

ac56200_.dita This topic's URL is:
End of change