Axis2 WS Client Function Component

The Axis2 WS Client FC is a Web Service client which is used to invoke a running Service. The Function Component uses the Apache Axis2 library to send the request to and to receive the response from the Web Service.

Both WSDL 1.1 (http://www.w3.org/TR/wsdl/) and WSDL 2.0 (http://www.w3.org/TR/wsdl20/) documents are supported.

Both SOAP 1.1 and SOAP 1.2 protocols are supported. Only literal SOAP messages can be used, encoded SOAP messages are not supported. This is a limitation of the underlying Axis2 library (version 1.4.0.1).

Using the FC

The Axis2 WS Client FC invokes a configured Web Service's operation and returns the response of it using the HTTP transfer protocol. The Function Component expects its payload in a Tivoli® Directory Integrator hierarchical attribute named after the input message element in the WSDL document. The Axis2 WS Client FC will return the response in another hierarchical attribute named after the output message element in the WSDL document.

In the case of an In-Only operation the response hierarchical object will not be created and an empty Entry will be returned.

Supported Message Exchange Patterns

The Axis2 Web Service Client FC supports the following message exchange patterns (for more information see Axis2 Web Service Server Connector):

In-Only

The Axis2 library requires the pattern to be http://www.w3.org/ns/wsdl/in-only in the WSDL file

In-Out

The Axis2 library requires the pattern to be http://www.w3.org/ns/wsdl/in-out in the WSDL file

Robust-In-Only

The Axis2 library requires the pattern to be http://www.w3.org/ns/wsdl/robust-in-only in the WSDL file

SOAP Headers

See SOAP Headers.

Schema

The Axis2 components (Axis2WSClientFC and Axis2WSServerConector) receive and send data in the form of attributes with hierarchical structure. These attributes can be created in a Script Component, for instance, but their structure depends on the WSDL document provided as a parameter to the component.

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="HelloService" 
targetNamespace="http://www.example.com/HelloService.wsdl" >
...
<binding name="Hello_Binding" type="tns:Hello_PortType">
<soap:binding style="rpc | document"
transport="http://schemas.xmlsoap.org/soap/http"/>
<operation ... >
<input>
               		<soap:body use="literal|encoded"? namespace="uri"?>
           		</input>
           		<output>
               		<soap:body use="literal|encoded"? namespace="uri"?>
           		</output>
        	</operation>
</binding>
...
</definitions>

If this document is in accordance with WSDL 1.1 standard, there are two options:

1. The style of the operation in the soap binding can be rpc.

   Then an additional element is used to wrap the data that will be placed in the soap body.

   If the message that will be wrapped is a request, this wrapper element is named identically to the operation name. It has a namespace with the same value as either the optional namespace attribute defined in the soap:body element of the binding or, if the first is not present, the targetNamespace of the wsdl definition.

   Otherwise, if the wrapper is for the response message, its name will be formed by the operation's name plus the word "Response" and the namespace will be formed the same way as above. Each message part (parameter) appears under the wrapper, represented by an accessor named identically to the corresponding parameter of the call. Parts are arranged in the same order as the parameters of the call.

   A WSDL snippet:

   <?xml version="1.0" encoding="UTF-8"?>
   <definitions name="HelloService"
   		targetNamespace="http://www.example.com/wsdl/HelloService.wsdl"
   		xmlns="http://schemas.xmlsoap.org/wsdl/"
   		xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
   		xmlns:tns="http://www.example.com/wsdl/HelloService.wsdl"
   		xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <message name="SayHelloRequest">
   <part name="firstName" type="xsd:string"/>
   </message>
   <message name="SayHelloResponse">
   <part name="greeting" type="xsd:string"/>
   </message>
   <portType name="Hello_PortType">
   <operation name="sayHello">
   <input message="tns:SayHelloRequest"/>
   <output message="tns:SayHelloResponse"/>
   </operation>
   </portType>
   <binding name="Hello_Binding" type="tns:Hello_PortType">
   <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
   ...
   </binding>
   ...

   The script for creating the hierarchical attribute that will be passed to the web service (the request: SayHelloRequest) is:

   var wrapper = work.createElementNS("http://www.example.com/HelloService.wsdl" ,"ns:sayHello"); 
   var message = work.createElement("firstName");
   message.appendChild(work.createTextNode("My Text Value"));
   wrapper.appendChild(message);
   work.setAttribute(wrapper);

   And the SOAP request looks like:

   <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" >
      <soap:Header/>
      <soap:Body>
         <ns:sayHello xmlns:ns="http://www.example.com/HelloService.wsdl">
            <firstName>My Text Value </firstName>
         </ns:sayHello>
      </soap:Body>
   </soap:Envelope>

   If you are assembling the response of the web service (from the Axis2WSServerConnctor for instance), the script is:

   var wrapper = work.createElementNS("http://www.example.com/wsdl/HelloService.wsdl", "ns:sayHelloResponse");
   var message = work.createElement("greeting");
   message.appendChild(work.createTextNode("Returned Value"));
   wrapper.appendChild(message);
   work.setAttribute(wrapper);

   And the SOAP response looks like:

   <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" >
      <soap:Header/>
      <soap:Body>
         <ns:sayHelloResponse  xmlns:ns="http://www.example.com/wsdl/HelloService.wsdl">
            <greeting>Returned Value </greeting>
         </ns:sayHelloResponse>
      </soap:Body>
   </soap:Envelope>

2. The style of the operation can be document.

   Then there are no additional wrappers, and the message parts appear directly under the SOAP Body element. We only need to create an attribute with the same name as the message part name, and its child element that hold the data we need to pass (in this example a string).

   For the same WSDL snippet:

   ...
   <message name="SayHelloRequest">
   <part name="firstName" type="xsd:string"/>
   </message>
   <message name="SayHelloResponse">
   <part name="greeting" type="xsd:string"/>
   </message>
   <portType name="Hello_PortType">
   <operation name="sayHello">
   <input message="tns:SayHelloRequest"/>
   <output message="tns:SayHelloResponse"/>
   </operation>
   </portType>
   <binding name="Hello_Binding" type="tns:Hello_PortType">
   <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
   ...
   </binding>
   ...

   The script for creating the request attribute looks like:

   var message = work.createElement("firstName");
   message.appendChild(work.createTextNode("My Text Value"));
   work.setAttribute(message);

   And the SOAP request:

   <soapenv:Envelope xmlns:soapenv=" http://www.w3.org/2003/05/soap-envelope/">
      <soapenv:Header/>
      <soapenv:Body>
         <firstName>My Text Value </firstName>
      </soapenv:Body>
   </soapenv:Envelope>

   If you are assembling the response of the web service (from the Axis2WSServerConnctor for instance), the script should look like:

   var message = work.createElement("greeting");
   message.appendChild(work.createTextNode("Returned Value"));
   work.setAttribute(message);

   And the SOAP response:

   <soapenv:Envelope xmlns:soapenv=" http://www.w3.org/2003/05/soap-envelope/">
      <soapenv:Header/>
      <soapenv:Body>
         <greeting>Returned Value </greeting>
      </soapenv:Body>
   </soapenv:Envelope>

   For additional information on this subject, see http://www.w3.org/TR/wsdl/, section 3.5.

If the supplied WSDL file is in accordance with WSDL 2.0 standard, then:

The situation is similar to the document operation style - there is no need for additional wrappers.

The hierarchy of the attribute must comply with the structure of the message as defined by the types block of the WSDL file.

For SOAP Headers information see SOAP Headers.

The Axis2WSClientFC has the ability to log the HTTP headers of received SOAP responses when in detailed log mode. That way you can easily access this information. In addition, HTTP attributes can be mapped in the Input Map of the FC, thus setting specific headers of the SOAP request. . For more information on HTTP Headers, see HTTP Server Connector and Axis2 Web Service Server Connector.

Configuration

The Axis2 WS Client Function Component has the following parameters:

WSDL URL

The location of the WSDL file which will be used for the WebService invocation.

Service

The name of the Service (as written in the WSDL file) which is to be invoked. This parameter has a button with an assigned script to it; this script will display a drop down box from which you can select the desired Service name. However, for the script to function you must first specify a WSDL file because it shows the Services in it.

Operation

The name of the SOAP Operation which is to be invoked. This parameter has a button with an assigned script to it; this script will display a drop down box from which you can select the desired operation. However, for the script to function you must first select a Service because the intention is to show the operations associated with the service.

Endpoint

The name of the Endpoint (as written in the WSDL file) which corresponds to the WebService to be invoked. This parameter has button with assigned script to it; this script will display a drop down box from which you can select the desired Endpoint name. However, for the script to function you must first specify as Service because it shows the endpoints associated with it.

Username

The username to be used for HTTP Basic Authentication invocations.

Password

The password to be used for HTTP Basic Authentication invocations.

When configuring this Connector, you first configure the WSDL file, after which you select the Service. Next, you select the SOAP Operation and Endpoint.

See also

The example in TDI_install_dir/examples/axis2_web_services.