Axis Easy Web Service Server Connector

The Axis Easy Web Service Server Connector is part of the Tivoli® Directory Integrator Web Services suite. It is a simplified version of the Web Service Receiver Server Connector in that it internally instantiates, configures and uses the AxisSoapToJava and AxisJavaToSoap FCs.

The functionality provided is the same as if you chain and configure these FCs in an AssemblyLine which hosts the Web Service Receiver Server Connector. When using this Connector you forgo the possibility of hooking custom processing before parsing the SOAP request and after serializing the SOAP response, that is, you are tied to the processing and binding provided by Axis, but you gain simplicity of setup and use.

The Axis Easy Web Service Server Connector operates in Server mode only.

AssemblyLines support an Operation Entry (op-entry). The op-entry has an attribute $operation that contains the name of the current operation executed by the AssemblyLine. In order to process different web service operations easier, the Axis Easy Web Service Server Connector will set the $operation attribute of the op-entry.

The Axis Easy Web Service Server Connector supports generation of a WSDL file according to the input and output schema of the AssemblyLine. As in Tivoli Directory Integrator 7.1.1 AssemblyLines support multiple operations, the WSDL generation can result in a web service definition with multiple operations. There are some rules about naming the operations:

• Pre-6.1 TDI configuration files contain only one input and one output schema referred to as default operation schemas. When a pre-6.1 TDI configuration is used the only operation generated is named as the name of the AssemblyLine as in TDI 6.0.
• In Tivoli Directory Integrator 7.1.1 configurations if there is an operation named "Default", the corresponding operation in the WSDL file is named as the name of the AssemblyLine.
• In Tivoli Directory Integrator 7.1.1 configurations if there is an operation named "Default" and there is also an operation with a name as the name of the AssemblyLine, both operations preserve their names in the WSDL file.
• In all other cases the operations appear in the WSDL file as they are named in the AssemblyLine configuration.

This Connector's configuration is relatively simple. The Connector parses the incoming SOAP request, stores it (along with HTTP specific data) into the event Entry and then presents this Entry to the AssemblyLine for Attribute mapping. When the work Entry (now storing the Java representation of the SOAP response) is returned to the Connector in the Response phase, the Connector serializes the response and returns it to the Web Service client.

When this Connector receives a SOAP request, the connector parses it and sets the $operation attribute of the op-entry. The name of the operation is determined by the name of the element nested in the Body element of the SOAP envelope. For parsing the SOAP messages, a SAX parser is used, which compared to a DOM parser adds less performance overhead.

There are several types of SOAP messages:

• When using RPC-style SOAP messages the name of the element is the same as the name of the operation.
• When using Document-style SOAP messages there are two scenarios:
  • Using Wrapped Document-style SOAP messages - in this case the body of the SOAP message looks like it is an RPC-style SOAP message; this is achieved by wrapping the contents of the SOAP Body in an element nested in the SOAP Body Element; the name of this element is the name of the SOAP operation.
  • Using ordinary, or unwrapped Document-style SOAP messages - in this case the notion of SOAP operation is not defined: the SOAP message is part of some SOAP message exchange. In this case, the Connectors would set the $operation attribute of the op-entry to the name of the element nested in the SOAP Body element and it is the responsibility of you as the Tivoli Directory Integrator developer/deployer to make sure that a Tivoli Directory Integrator solution handles this correctly. When using ordinary or unwrapped Document-style SOAP messages, it is best not to depend on the value of the $operation attribute of the op-entry.

Hosting a WSDL file

The Axis Easy Web Service Server Connector provides the "wsdlRequested" Connector Attribute to the AssemblyLine.

If an HTTP request arrives and the requested HTTP resource ends with "?WSDL" then the Connector sets the value of the "wsdlRequested" Attribute to true and reads the contents of the file specified by the WSDL File parameter into the "soapResponse" Connector Attribute; otherwise the value of this Attribute is set to false.

This Attribute's value thus allows you to distinguish between pure SOAP requests and HTTP requests for the WSDL file. The AssemblyLine can use a Branch Component to execute only the appropriate piece of logic - (1) when a request for the WSDL file has been received, then the AssemblyLine could perform some optional logic or read a different WSDL file and send it back to the web service client, or just rely on default processing; (2) when a SOAP request has been received the AssemblyLine will handle the SOAP request. Alternatively, you could program the system.skipEntry(); call at an appropriate place (in a script component, in a hook in the first Connector in the AssemblyLine, etc.) to skip further processing and go directly to the Response channel processing.

It is the responsibility of the AssemblyLine to provide the necessary response to a SOAP request.

The Connector implements a public method:

public String readFile (String aFileName) throws IOException;

This method can be used from Tivoli Directory Integrator JavaScript in a script component to read the contents of a WSDL file on the local file system. The AssemblyLine can then return the contents of the WSDL in the "soapResponse" Attribute, and thus to the web service client in case a request for the WSDL was received.

Schema

Input Schema

Output Schema

Configuration

Parameters

TCP Port

The port that the web service will listen for client connections on.

Connection Backlog

This represents the maximum queue length for incoming connection indications (a request to connect). If a connection indication arrives when the queue is full, the connection is refused.

WSDL File

This parameter is required; its type is string. The value of this parameter must be the complete file system path to the WSDL document that describes this web service.

SOAP Operation

The name of the SOAP operation as described in the WSDL file.

Complex Types

This parameter is not required, but if specified it is a list of fully qualified Java class names (including the package name), where the different elements (Java classes) of this list are separated by one or more of the following symbols: a comma, a semicolon, a space, a carriage return or a new line.

Tag Op-Entry

When this parameter is checked (that is, "true") the Connector will tag the op-entry only when the executed operation is on the list of exposed operations in the AssemblyLine/WSDL. If the operation cannot be found in the WSDL then a SOAP Fault message will be generated and returned to the client.

Note:

In TDI 6.0 the AxisEasyWSServerConnector required the Soap Operation parameter to be set. In Tivoli Directory Integrator 7.1.1 when the Tag Op-Entry parameter is set to "true" the AxisEasyWSServerConnector will use the extracted operation name instead of the name specified with the Soap Operationparameter. In this case the Soap Operation parameter is not a required parameter, it can be left blank.

Use SSL

If checked the server will only accept SSL (https) connections. The SSL parameters (keystore, etc.) are specified as values of Java system properties in the global.properties file located in the Tivoli Directory Integrator installation folder.

Require Client Authentication

Specifies whether this Connector will require clients to authenticate with client SSL certificates. If the value of this parameter is true (that is, checked) and the client does not authenticate with a client SSL certificate, then the Connector will drop the client connection. If the value of this parameter is true and the client does authenticate with a client SSL certificate, then the Connector will continue processing the client request. If the value of this parameter is false, then the Connector will process the client request regardless of whether the client authenticates with a client SSL certificate.

Auth Realm

This is the basic-realm sent to the client in case authentication is requested. The default is "IBM Tivoli Directory Integrator".

Use HTTP Basic Authentication

This connector supports HTTP basic authentication. To activate, check the Use HTTP Basic Authentication checkbox. If activated, the server checks if any credentials are already sent and if not, the server sends authorization request to client. After the client sends the needed credentials, the Connector then sets two attributes: "http.username" and "http.password". These two attributes contain the username and password of the client. It is responsibility of the AssemblyLine to check if this pair of username and password is valid. If the client is authorized successfully then "http.credentialsValid" work Entry Attribute must be set to true. If the client is not authorized then "http.credentialsValid" work Entry Attribute must be set to false. If the client is not authorized then the server sends a "Not Authorized" HTTP message.

Comment

Your own comments go here.

Detailed Log

If checked, will generate additional log messages.

WSDL Output to Filename

The name of the WSDL file to be generated when the "Generate WSDL" button is clicked. This parameter is only used by the WSDL Generation Utility - this parameter is not used during the Connector execution.

Web Service provider URL

The address on which web service clients will send web service requests. Also this parameter is only used by the WSDL Generation Utility - this parameter is not used during the Connector execution.

The Generate WSDL button runs the WSDL generation utility.

The WSDL Generation utility takes as input the name of the WSDL file to generate and the URL of the provider of the web service (the web service location). This utility extracts the input and output parameters of the AssemblyLine in which the Connector is embedded and uses that information to generate the WSDL parts of the input and output WSDL messages. It is mandatory that for each Entry Attribute in the "Initial Work Entry" and "Result Entry" Schema the "Native Syntax" column be filled in with the Java type of the Attribute (for example, "java.lang.String"). The WSDL file generated by this utility can then be manually edited.

The operation style of the SOAP Operation defined in the generated WSDL is "rpc".

The WSDL generation utility cannot generate a <types...>...</types> section for complex types in the WSDL.

Connector Operation

For an overview of the Axis Easy Web Service Server Connector Attributes, used to exchange information to and from the HTTP/SOAP request, see Schema.

This Connector parses the incoming SOAP request message and stores the Java representation of the SOAP request in the "requestObjArray" Connector Attribute. The Connector is capable of parsing both Document-style and RPC-style SOAP messages as well as generating (a) Document-style SOAP response messages, (b) RPC-style SOAP response messages and (c) SOAP Fault response messages. The style of the message generated is determined by the WSDL specified by the WSDL File Connector parameter.

The Connector is capable of parsing SOAP request messages and generating SOAP response messages which contain values of complex types which are defined in the <types> section of the WSDL document. In order to do that this Connector requires that (1) the Complex Types Connector parameter contains the names of all Java classes that implement the complex types used as request and response parameters to the SOAP operation and that (2) these Java classes' class files are located in the Java class path of Tivoli Directory Integrator.

If during parsing the SOAP request an Exception is thrown by the parsing code, then the Connector generates a SOAP Fault Object (org.apache.axis.AxisFault) and stores it in the "soapFault" Connector Attribute.

This Connector is capable of parsing and generating SOAP response messages encoded using both "literal" encoding and SOAP Section 5 encoding. The encoding of the SOAP response message generated is determined by the WSDL specified by the WSDL File Connector parameter.

At the end of AssemblyLine processing in the Response channel phase, this Connector requires the Java representation (Object[]) of the SOAP response message from the "responseObjArray" Attribute of the work Entry to be mapped out. The Connector then serializes the SOAP response message, wraps it into an HTTP response and returns it to the web service client.

See also

Web Service Receiver Server Connector.