The Web Service Receiver Server Connector 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.
This Connector is basically an HTTP Server specialized for servicing
SOAP requests over HTTP. It 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 Web
Service Receiver Server Connector will set the $operation attribute
of the op-entry.
The Web Service Receiver 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.
The Web Service Receiver 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; otherwise the value of this Attribute
is set to false.
This Attribute's value tells the AssemblyLine whether the request
received is a SOAP request or a request for a WSDL file, and allows
the AssemblyLine to distinguish between pure SOAP requests and HTTP
requests for the WSDL file. The AssemblyLine can use a branch component
to execute only the required piece of logic - (1) when a request
for the WSDL file has been received, then the AssemblyLine can read
a WSDL file and send it back to the web service client; (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.
It is the responsibility of the AssemblyLine to provide the necessary
response to either a SOAP request or a request for a WSDL file.
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.
Table 40. Web Service Receiver Server Connector Input Schema
Attribute
Value
host
Type is String. Contains the name of the host
to which the request is sent. This parameter is set only if "wsdlRequested"
is false.
requestedResource
The requested HTTP resource.
soapAction
The SOAP action HTTP header. This parameter
is set only if "wsdlRequested" is false.
soapRequest
The SOAP request in txt/XML or DOMElement format.
This parameter is set only if "wsdlRequested" is false.
wsdlRequested
This parameter is true if a WSDL file is requested
and false otherwise.
http.username
This attribute is used only when HTTP basic
authentication is enabled. The value is the username of the client
connected.
http.password
This attribute is used only when HTTP basic
authentication is enabled. The value is the password of the client
connected.
Output Schema
Table 41. Web Service Receiver Server Connector Output Schema
Attribute
Value
responseContentType
The response type. The default response type
is "text/xml". It is used with SOAP messages.
soapResponse
The SOAP response message. If wsdlRequested
is true, then soapResponse is set to the contents of the WSDL file.
http.credentialsValid
This attribute is used only when HTTP basic
authentication is enabled. When the client provides username and password
for HTTP Basic Authentication then this attribute must be set to true
or false (this is not done by the Connector, it's done by the
AssemblyLine using the Connector). If the value is true this means
that the client is authenticated correctly and access is granted.
If the value is false then the user is not authenticated and an HTTP
"Not Authorized" Connector response is returned.
The port number the service is running (listening) 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.
Input the SOAP message as
Specifies the type of the SOAP Request message input to the
AssemblyLine. This drop-down list allows you to choose either String or
"DOMElement".
Return the SOAP message as
Specifies the type of the SOAP Response message output from
the AssemblyLine. This drop-down list allows you to choose either String or
"DOMElement".
Tag Op-Entry
When this parameter is checked (that is, "true") the
Connector will tag the op-entry even if the currently executed operation
is not on the list of exposed operations in the AssemblyLine/WSDL.
It is up to the Tivoli Directory
Integrator solution implementation to handle this case appropriately.
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
The basic-realm sent to the client in case authentication is
requested.
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.
The Web Service Receiver Server Connector stores the following
information from the HTTP/SOAP request into Attributes of the Connector's conn entry, ready to be mapped into the work entry (also see Schema):
The name of the host to which the request is sent (the local host) -
stored into the "host" Attribute
The requested HTTP resource - stored into the "requestedResource"
Attribute
The value of the "soapAction" HTTP header - stored
into the "soapAction" Attribute
If the value of the Input the SOAP message as FC parameter
is String then the SOAP request message is stored as a java.lang.String object
in the "soapRequest" Attribute.
If the value of the Input the SOAP message as FC parameter
is DOMElement then the SOAP request message is stored as
an org.w3c.dom.Element object in the "soapRequest"
Attribute.
Whether a WSDL file was requested -- in the "wsdlRequested"
Attribute. If this is the case (that is, the value is true,
no other Attributes will be set).
When reaching the Response stage of the AssemblyLine, this Connector
requires the SOAP response message in text XML form or as DOMElement from
the "soapResponse" Attribute of the work Entry
to be mapped out:
If the value of the Return the SOAP message as FC parameter
is String then the SOAP response message must be stored as
a java.lang.String object in the "soapResponse"
Attribute by the AssemblyLine.
If the value of the Return the SOAP message as FC parameter
is DOMElement then the SOAP response message must be stored
as a org.w3c.dom.Element in the "soapResponse"
Attribute by the AssemblyLine.
The Connector then wraps the SOAP response message into an HTTP
response and returns it to the web service client.
Directory Integrator, Version 7.1.1