Web Service Receiver Server Connector

The Web Service Receiver Server Connector is part of the TDI Web Services suite.

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 TDI 7.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 TDI 7.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 TDI 7.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.

Hosting a WSDL file

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 TDI 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

Table 32. 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 33. 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.

Configuration

Parameters

TCP Port

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 us 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 us 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 TDI 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 TDI 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.

Connector Operation

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.

See also

Axis Easy Web Service Server Connector.