InvokeSoap WS Function Component

Directory Integrator, Version 7.1.1

InvokeSoap WS Function Component

Introduction

The Axis InvokeSoapWS Function Component (FC) is part of the Tivoli® Directory Integrator Web Services suite.

Note:

Due to limitations of the Axis library used by this component only WSDL (http://www.w3.org/TR/wsdl) version 1.1 documents are supported. Furthermore, the supported message exchange protocol is SOAP 1.1.

It is used to perform a web service call, given the input message for the call. It has no built-in SOAP parsing functionality and can be used with the Axis Soap To Java Function Component and Axis Java To Soap Function Component to provide a complete web service solution.

The InvokeSoapWS Function Component requires a complete SOAP request message. When called with a SOAP message the Function Component invokes the remote web service operation with this message. The Function Component returns the SOAP response message. The Function Component, however, does not perform any XML-Java binding (that is, the SOAP response message is not parsed) - the Function Component only returns the SOAP response message.

Authentication

The InvokeSoapWS FC supports the HTTP basic authentication method. If username and password parameters are filled, then the "authorization" HTTP header field is set with the proper credentials (as specified in the HTTP specification for using HTTP basic authentication). Before sending the username and password, the FC encodes them. The encoding used is Base64 and is done internally by the InvokeSoapWS FC.

Configuration

Parameters

WSDL URL: The URL of the WSDL document describing the service. his parameter is required; otherwise an exception is thrown on initialization.
SOAP Operation: The name of the SOAP operation as described in the WSDL file. This parameter is required; otherwise an exception is thrown on initialization.
Provider URL: The URL of the web service provider; substitutes the value in the WSDL; this parameter is provided to allow for dynamic provider switching. If this parameter is Empty then the value from the WSDL is used.
Login username: The login username sent to the server, using HTTP Basic Authentication. If the server requires authorization it uses this value and the next (Login password) to authenticate the client. The encoding used is Base64 and is done internally by the InvokeSoapWS FC.
Login password: The login password sent to the server, using HTTP Basic Authentication. If the server requires authorization it uses this value and the previous (Login username) to authenticate the client.
Input the SOAP message as: This drop-down list specifies whether the SOAP request message will be passed to the FC as a string or as a DOM object. This is a required parameter.
Return the SOAP message as: This drop-down list specifies whether the SOAP response message should be returned as a string or as a DOM object. This is a required parameter. If the parameter is not specified or has an invalid value, an exception is thrown on initialization. Also, if the SOAP request message does not conform to the format specified by the this parameter, an error will occur. However, it is ignored when invoking one-way web service operations (seeOne-way web service operation support.)
Detailed Log: When checked, will generate additional log messages.
Comment: Your own comments go here.

Function Component Input

An Entry, a java.lang.String object, or an org.w3c.dom.Element object - contains the complete SOAP request message.

If anything else is passed, an Exception is thrown.

If an Entry is passed to the FC and if the value of the Input the SOAP message as FC parameter is String then the SOAP request message must be stored in the "xmlString" Attribute of that Entry. If an Entry is passed to the FC and if the value of the Input the SOAP message as FC parameter is DOMElement then the SOAP request message must be stored in the "xmlDOMElement" Attribute.

If a non-Entry object (either String or Element) is passed to the FC and if the value of the Input the SOAP message as FC parameter is String then the SOAP request message must be passed as a java.lang.String object. If a non-Entry object (either String or Element) is passed to the FC and if the value of the Input the SOAP message as FC parameter is DOMElement then the SOAP request message must be passed as an org.w3c.dom.Element object.

Function Component Output

An Entry object with 3 attributes - one for the whole SOAP message, one for the SOAP Header and one for the SOAP Body. The SOAP message, Body and Header will be either XML strings or DOM objects, as specified by the Return the SOAP message as parameter. Refer to "Using the FC", next.

Using the FC

This Function Component makes a web service call by sending a SOAP request message and receiving a SOAP response message.

If an Entry was passed to the FC, then if the value of the Return the SOAP message as FC parameter is String then the SOAP response message is stored in the "xmlString" Attribute; however, If the value of the Return the SOAP message as FC parameter is DOMElement then the SOAP response message is stored in the "xmlDOMElement" Attribute.
Additionally, if this FC was passed an Entry object, then the FC stores the SOAP response Header and SOAP response Body (apart from the entire SOAP response message) as Attributes in the returned Entry. If the value of the Output the SOAP message as FC parameter is String then the SOAP Header and Body are stored in the "soapHeaderString" and "soapBodyString" Attributes respectively as java.lang.String objects. If the value of the Return the SOAP message as FC parameter is DOMElement then the SOAP Header and Body are stored in the "soapHeaderDOMElement" and "soapBodyDOMElement" Attributes respectively as org.w3c.dom.Element objects.
If a non-Entry object was passed to this FC, then the return value of the FC is either a java.lang.String object (when the value of the Return the SOAP message as FC parameter is String) or an org.w3c.dom.Element object (when the value is DOMElement).
This FC is capable of sending and receiving SOAP messages encoded using both "literal" encoding and SOAP Section 5 encoding.
This FC is capable of sending and receiving SOAP messages containing values of complex types which are defined in the <types> section of a WSDL document.
This FC sets the "soapAction" HTTP Header for the SOAP request message to the value specified in the WSDL document (whose location is specified by the WSDL URL FC parameter) for the given SOAP operation (whose name is specified by the SOAP Operation FC parameter).
This FC sends the SOAP request message over HTTP to the web service address specified in the "WSDL URLl" parameter. If the "WSDL URL" parameter is missing or empty, the web service address specified in the WSDL document (whose location is specified by the WSDL URL FC parameter) for the given SOAP operation (whose name is specified by the SOAP Operation FC parameter) is used .
This FC provides Username and Password parameters. If these parameters are provided, then the FC sets the basic authorization header and sends it to the server. It encodes the supplied username and password using encoding method base64; this is done inside the InvokeSoapWS FC

One-way web service operation support

WSDL 1.1 has four transmission primitives that a web service endpoint can support:

One-way: The endpoint receives a message.
Request-response: The endpoint receives a message, and sends a correlated message.
Solicit-response: The endpoint sends a message, and receives a correlated message.
Notification: The endpoint sends a message.

WSDL refers to these transmission primitives as operations. (More information on the subject can be found on: http://www.w3.org/TR/wsdl#_porttypes.)

The InvokeSoapWS Function Component supports only request-response and one-way web service operations. During the initialization phase, the InvokeSoapWS FC reads the configured WSDL document and checks whether the specified SOAP operation is one-way. If the operation is not one-way, it is assumed to be request-response.

The following is a sample WSDL fragment, which describes a request-response operation:

	<operation name="myRequestResponseOperation">
		<input message="myInputMessage"/>
		<output message="myOutputMessage"/>
	</operation>

And the following sample WSDL fragment describes a one-way operation:

	<operation name="myOneWayOperation">
		<input message="myInputMessage"/>
	</operation>

Note:

One-way web service operations do not involve a server response - the client sends a request message but the server is not supposed to reply back (not even with a fault message). That is why the InvokeSoapWS does not return a response when invoking a one-way SOAP operation: If the 'perform' method of the FC is passed an Entry argument (for example when the FC is executed as a part of an AssemblyLine), the FC returns an empty Entry. If the 'perform' method of the FC is passed a java.lang.Object (for example when the FC is executed by a script), the FC returns null.