Directory Integrator, Version 7.1.1
The Axis2 Web Service Server Connector can be used to provide a SOAP web service, which is accessible via HTTP/HTTPS.
The logic of such a service is supposed to be implemented as a Tivoli® Directory Integrator AssemblyLine, thus leveraging existing Tivoli Directory Integrator components.
The Connector is named after the underlying Axis2 Java library: http://ws.apache.org/axis2/.
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).
The Axis2 Web Service Server Connector supports Server Mode only.
Generally, there are only few cases in which you should use Axis1 components:
In all other cases the Axis2 components should be used because they:
The binding in a WSDL1.1 document describes how the service is bound to a messaging protocol, particularly the SOAP messaging protocol. A WSDL SOAP binding can be either a Remote Procedure Call (RPC) style binding or a document style binding. A SOAP binding can also have an encoded use or a literal use. This gives you four style/use models:
For more information, see http://www.ibm.com/developerworks/webservices/library/ws-whichwsdl/.
Support of style/use models in the Tivoli Directory IntegratorAxis2 components is as follows:
In WSDL 2.0 everything is similar to the document/literal model (all messages are defined directly using a type language, such as XML Schema) so there is no problem with our Axis2 components. As for RPC calls, WSDL2.0 defines a set of rules for designing messages suitable for them. For more information, see http://www.sdn.sap.com/irj/sdn/go/portal/prtroot/docs/library/uuid/74bae690-0201-0010-71a5-9da49f4a53e2.
All major frameworks for web services support Document/literal messages. Most of the popular frameworks also have some support for rpc/encoded, so developers can still use it to create encoded-only services. As a result it is hard to estimate how many web services, in production use, work only with SOAP encoded messages. However there is a tendency to move away from RPC/encoded towards Document/literal. This is so, because the SOAP encoding specification does not guarantee 100% interoperability and there are vendor deviations in the implementation of RPC/encoded.
Here are some references about encoded support in some popular frameworks:
The product is deprecated by Microsoft and its support stopped on July 1, 2004: http://msdn2.microsoft.com/en-us/library/aa286526.aspx.
If you need to use the RPC/encoded model the old web services suite can be used. Also, if you have more information on the service and the SOAP messages, a solution can be created using the HTTP Components and XML Parser.
The Axis2 Web Service Server Connector is designed for a "WSDL first" way of development. This means that the Connector requires a WSDL document describing the web service, so that it knows how clients expect the web service to behave. The implementation of the web service then must stick to the model outlined by the WSDL. (An alternative would be to implement the logic first and have the Connector produce an appropriate WSDL for that implementation.) The reason for this design choice is to make it easy for Tivoli Directory Integrator to fit into an existing communication model by conforming to an already established WSDL description.
For situations where an existing Assembly Line needs to be exposed through a web service interface, Tivoli Directory Integrator offers some basic WSDL generation functionality (see WSDL Generation).
A WSDL document can describe multiple interfaces (or port types in WSDL 1.1 terms). Each interface groups a set of operations. One instance of the Axis2 Web Service Server Connector can be used to implement just a single interface. To help the AssemblyLine logic distinguish between different operations, the Connector passes the name of the operation (the local part of the qualified name) in the $operation Attribute of the Operational Entry (op-entry). For more information on AssemblyLine Operations and the Operational Entry see IBM Tivoli Directory Integrator V7.1.1 Users Guide.
The Axis2 Web Service Server Connector supports the following message exchange patterns (described in WSDL 2.0 terms):
For more information on message exchange patterns see:
You can instruct the Axis2 Web Service Server Connector to generate a SOAP fault in response to a client's request.
This can be achieved using the following Connector attributes:
See Schema a detailed description of these and other attributes.
For more information on SOAP faults see:
The Connector provides access to the SOAP header of the SOAP request for analysis, in case of special or advanced use.
It also allows user-defined SOAP headers to be included in the response.
Note that any user-defined SOAP headers affect both normal SOAP messages and SOAP faults.
See section Schema for a detailed description of the attributes.
The Axis2 Web Service Server Connector uses the HTTP Server Connector as its HTTP transport.
In special, advanced cases you can take advantage of the control that the HTTP Server Connector provides over the HTTP request and the HTTP response.
You can analyze the HTTP headers of the request and set the HTTP headers of the response.
You can even override the whole HTTP body of a response. The Axis2 Web Service Server Connector parses SOAP messages out of HTTP POST requests only. HTTP GET requests are not processed by the SOAP engine, and you are free to implement your own logic in such cases - for example you can return a WSDL document if an HTTP GET request arrives with an URI that ends with "?wsdl".
The Axis2 WS Server Connector requires a WSDL document in order to function. If you have a working AssemblyLine but you do not have a WSDL document, you can use Tivoli Directory Integrator to generate one, using an instance of this Connector. The service name in the generated WSDL document will be set to the name of the AssemblyLine.
Note that the WSDL generation functionality is aimed at novice users as a quick start. If you have some web service expertise, we strongly recommend that you design the WSDL document yourself or at least thoroughly inspect the generated WSDL document before putting it into production use.
To generate a WSDL file:
See the documentation of the HTTP Server Connector for transport related attributes.
You can add attributes such as http.content-type and http.content-length to the Input Map and use these parameters of the SOAP request in the logic of the AssemblyLine.
Another useful attribute is http.method, which holds the type of request received by the server (GET or POST). Since the connector parses only POST requests, the value of this attribute can be checked and in case of a GET request a specific return value set (for example the WSDL document describing the service or an HTML document).
http.SOAPAction is also a significant HTTP header that is important for the Web Services. It is set in the HTTP binding of the SOAP message, and its value is an URI. Some SOAP bindings do not require a SOAPAction and omit this attribute.
A SOAP Message Embedded in an HTTP Request:
POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "Some-URI"
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
...
</soapenv:Body>
</soapenv:Envelope>See the Schema section of the Axis2 WS Client Function Component for a description of WSDL-specific Attributes, such as the incoming message.
For example, consider the following SOAP message:
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header
xmlns:myns="http://www.my.com">
<myns:myheader />
</soapenv:Header>
<soapenv:Body><payload /></soapenv:Body>
</soapenv:Envelope>Then the $soapHeader Hierarchical Attribute will be a DOM representation of the following XML element:
<$soapHeader
xmlns:myns="http://www.my.com">
<myns:myheader />
</$soapHeader>Note that the only difference between the $soapHeader element and the Header element from the SOAP message is that the $soapHeader element does not have an associated namespace. The idea is to save you from considering what namespace to use (the namespace of the header element differs between SOAP versions).
See the documentation of the HTTP Server Connector for transport related attributes.
The HTTP attributes can be used not only to set characteristics of the SOAP response, but to alter the behavior of the AssemblyLine. For instance when the attribute http.body is mapped in the Output Map of the connector, its value is directly set as SOAP response and the Axis2 engine is not used to generate it. A similar technique is used in the first of the shipped examples. There the value of http.method is checked and in case of a GET request the http.body attribute is set with the contents of the WSDL file describing the service. If a POST request is received a SOAP response is assembled and sent.
Another useful HTTP attribute is http.status. It can be mapped to the Output Map of the connector and its value set according to the AssemblyLine logic. This way you can modify the status of the HTTP response that the server will send. Set "200" for OK, "403" for Forbidden, "404" for Not Found, and so forth.
See the Axis2 WS Client Function Component Schema section for description of WSDL-specific Attributes, such as the incoming message.
If the Attribute is set to "true" (case insensitive), the authentication of the client is considered successful, otherwise (if the Attribute is missing or has some other value) the Connector assumes the authentication has failed and returns an error HTTP response to the client.
For more information on authentication see section Authentication.
For example consider the following SOAP message:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header
xmlns:myns="http://www.my.com">
<myns:myheader />
</soapenv:Header>
<soapenv:Body><payload/></soapenv:Body>
</soapenv:Envelope>Suppose that the $soapHeader Hierarchical Attribute is the DOM representation of the following XML element:
<$soapHeader
xmlns:otherns="http://www.other.com">
<otherns:otherheader>
This is an example of a user-defined SOAP header.
</otherns:otherheader>
</$soapHeader>When combining the above SOAP message with the contents of the $soapHeader Hierarchical Attribute, the result will be the following SOAP message:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header
xmlns:myns="http://www.my.com"
xmlns:otherns="http://www.other.com">
<myns:myheader />
<otherns:otherheader>
This is an example of a user-defined SOAP header.
</otherns:otherheader>
</soapenv:Header>
<soapenv:Body><payload/></soapenv:Body>
</soapenv:Envelope>The $faultCode Attribute is designed to be used in combination with the $faultCodeNamespacePrefix and $faultCodeNamespaceURI. Together these three Attributes can fully define a qualified name - that is a namespace URI ($faultCodeNamespaceURI), a local part ($faultCode) and a namespace prefix ($faultCodeNamespacePrefix). This qualified name represents the code of the SOAP fault.
When working with SOAP 1.2, the $faultCode Attribute will be used as the local part of the qualified name, which appears inside the Value element, which is a child of the Code element, which is a child of the Fault element.
For example, if the $faultCode Attribute contains the string "mycode" and the $faultCodeNamespacePrefix and $faultCodeNamespaceURI Attributes are missing, the fault element inside the body of the SOAP message would look like this:
<soapenv:Fault xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
<soapenv:Code>
<soapenv:Value>mycode</soapenv:Value>
</soapenv:Code>
...
</soapenv:Fault>On the other hand, if you set all three Attribute like this:
$faultCodeNamespaceURI = http://www.w3.org/2003/05/soap-envelope
$faultCode = Sender
$faultCodeNamespacePrefix= envthen this is what the SOAP fault will look like:
<soapenv:Fault xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"
xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<soapenv:Code>
<soapenv:Value>env:Sender</soapenv:Value>
</soapenv:Code>
...
</soapenv:Fault>When working with SOAP 1.1, the $faultCode Attribute will be used as the content of the $faultcode element, which is a child of the Fault element.
For example if you set the following Attribute values:
$faultCodeNamespaceURI = http://www.my.com
$faultCode = myfaultcode
$faultCodeNamespacePrefix = myprefthen the fault element inside the SOAP body will look like this:
<soapenv:Fault xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mypref="http://www.my.com">
<faultcode>mypref:myfaultcode</faultcode>
...
</soapenv:Fault>In general, you might prefer to use some of the predefined SOAP fault codes rather than make up your own:
The $faultReason Attribute should contain a human-friendly description of the SOAP fault. When working with SOAP 1.2, the value of the $faultReason Attribute is used as the content of the first Text element, which is a child of the Reason element inside the Fault element.
For example, if you set the $faultReason Attribute to "myreason", the SOAP fault element will look like this:
<soapenv:Fault xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
...
<soapenv:Reason>
<soapenv:Text
xml:lang="en-US"
xmlns:xml="http://www.w3.org/XML/1998/namespace">
myreason
</soapenv:Text>
</soapenv:Reason>
...
</soapenv:Fault>Note that the language will always be set to "en-US". When working with SOAP 1.1, the value of the $faultReason Attribute is used as the content of the faultstring element inside the Fault element.
For example, if you set the $faultReason Attribute to "myreason", the SOAP fault element will look like this:
<soapenv:Fault xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
...
<faultstring>myreason</faultstring>
...
</soapenv:Fault>The $faultNode Attribute corresponds to the Node element in SOAP 1.2 and the faultactor element in SOAP 1.1.
The $faultRole Attribute corresponds to the Role element in SOAP 1.2.
For more information on SOAP roles see http://www.w3.org/TR/soap12-part1/#soaproles.
When working with SOAP 1.1 the value of this Attribute is ignored.
The first child element of the $faultDetail Hierarchical Attribute will be used as the content of the Detail element in SOAP 1.2 or the detail element in SOAP 1.1.
For example if the $faultDetail Hierarchical Attribute is the DOM representation of the following XML element:
<$faultDetail>
<myfaultdata>some information here</myfaultdata>
</$faultDetail>then the SOAP fault element will look like this (using SOAP 1.2):
<soapenv:Fault xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
...
<soapenv:Detail>
<myfaultdata>some information here</myfaultdata>
</soapenv:Detail>
...
</soapenv:Fault>Using SOAP 1.1, it will look like this:
<soapenv:Fault xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
...
<detail>
<myfaultdata>some information here</myfaultdata>
</detail>
...
</soapenv:Fault>The Axis2 Web Service Server Connector has the following parameters:
If the WSDL document contains a description of a single service, this parameter can be left empty. On the other hand, if the WSDL document describes multiple services, this parameter is mandatory.
When SSL is used, the Connector will use the default Tivoli Directory Integrator Server SSL settings - certificates, keystore and truststore.
The following parameters are related to WSDL file generation (they are not used at runtime):
The Axis2 Web Service Server Connector supports transport level security by the use of SSL/TLS.
To turn SSL on, set the Use SSL Connector parameter to true.
To turn SSL client authentication on, set the Require Client Authentication Connector parameter to true.
For more information on Connector parameters, see Configuration.
By default the Axis2 Web Service Server Connector has HTTP basic authentication disabled.
To turn HTTP basic authentication on, set the HTTP Basic Authentication Connector parameter to true. Also set the Auth Realm to the name of the authentication realm - the client will be prompted to authenticate against that realm.
For more information on Connector parameters see Configuration.
The following Connector Attributes are related to HTTP basic authentication:
Note that the actual authentication logic must be implemented in the associated Assembly Line, for example by verifying client credentials against a database or an LDAP server.
You can implement custom authorization logic in the Connector's associated AssemblyLine, based on the username (see Authentication) provided by the Connector.
The example in TDI_install_dir/examples/axis2_web_services.