HTTP Client Connector

IBM Tivoli Directory Integrator

HTTP Client Connector

The HTTP Client Connector enables greater control on HTTP sessions than the URL Connector provides. With the HTTP Connector we can set HTTP headers and body using predefined attributes. Also, any request to a server that returns data is available for the user as attributes.

This Connector supports secure connections using the SSL protocol when so requested by the server, for example when accessing a server using the 'https://' prefix in an URL. If client-side certificates are required by the server, we will need to add these to the TDI truststore, and configure the truststore in global.properties or solution.properties. More information about this can be found in the IBM TDI V7.1 Installation and Administrator Guide, in the section named "Client SSL configuration of TDI components".

The HTTP Client Connector does not support the Advanced Link Criteria (see "Advanced link criteria" in IBM TDI V7.1 Users Guide).

Modes

The HTTP client Connector can be used in four different AssemblyLine modes. These are:

Iterator: Each call to the Connector requests the same URL configured for the Connector. This causes the Connector to run forever requesting the same page unless you include a Parser in the Connector's configuration. If you include a Parser, the Parser notifies when the last entry has been read from the connection and the Connector eventually causes an AssemblyLine to stop.
Lookup: In this mode the Connector requests a page every time the Lookup function is called. In your search criteria we can specify the page or URL to request, or include any number of parameters all of which are appended to the base URL as request parameters.
AddOnly: In this mode the Connector request is performed much like the Iterator mode.
Call/Reply: In this mode the Connector has two attribute maps, Input and Output. When the AssemblyLine invokes the Connector, an Output map operation is performed, followed by an Input map operation.

Lookup Mode

In Lookup mode we can dynamically change the request URL by setting the search criteria as follows:

If we have only one criteria and the attribute is named url, then the value specified in the criteria is used as the request URL.
```
 url equals $url
```
If we have more than one criteria or the only criteria is anything but url, then all attribute names and values are appended to the URL given by the Connector configuration as the request URL.
Base URL: http://www.example_page_only.com/lookup.cgi
Search Criteria:
```
name equals john  
mail equals doe.com
```
Resulting URL: http://www.example_page_only.com/lookup.cgi?name=john&mail=doe.com
The Lookup function ignores the operand. So if you specify contains instead of equals the Connector still constructs the URL as if equals where used.

Special attributes

When using the Connector in Iterator or Lookup mode the following set of attributes or properties is returned in the Connector ("conn") entry:

http.responseCode

The HTTP response code as an Integer object.

200 OK ---> 200

http.responseMsg

The HTTP response message as a String object.

200 OK ---> OK

http.content-type

The content type for the returned http.body (if any).

http.content-encoding

The encoding of the returned http.body (if any).

http.content-length

The number of bytes in http.body.

http.body

This object is an instance/subclass of java.io.InputStream class that can be used to read bytes of the returned body.

var body = conn.getObject ("http.body");
var ch;

while ( (ch = body.read()) != -1 ) {
  task.logmsg ("Next character: " + ch);
}

Consult the Javadocs for the InputStream classes and their methods.

http.body.response

When the Connector operates in AddOnly mode, responses from the server http.body part will be made available in this Attribute; and the http.body Attribute as it was on the outbound call will be unmodified. If on the outbound call you did not specify a value in the http.body Attribute, then on return from the server the http.body Attribute will be identical to the http.body.response Attribute.

http.text-body

If the http.content-type starts with the sequence text/, the Connector assumes the body is textual data and reads the http.body stream object into this attribute.

When using the Connector in AddOnly mode the Connector transmits any attribute named http. as a header. Thus, to set the content type for a request name the attribute http.content-type and provide the value as usual. One special attribute is http.body that can contain a string or any java.io.InputStream or java.io.Reader subclass.

For all modes the Connector always sets the http.responseCode and http.responseMsg attributes. In AddOnly mode this is special because the conn object being passed to the Connector is the object being populated with these attributes. To access these obtain the value in the Connector's After Add hook.

Character Encoding

The HTTP Client Connector uses internally the HTTP Parser to parse the input and output streams of the created socket to the specified URL. The default character encoding used for this is ISO-8859-1.

If the HTTP Client Connector has a configured Parser, then this parser is used to write the http.body attribute using its specified character encoding; or, if not specified, the default character encoding of the platform is used.

To explicitly specify the character encoding of the http.body attribute, use the Content Type parameter of the HTTP Client Connector. For more information see Configuration.

Configuration

The Connector has the following parameters:

HTTP URL

The HTTP page to request.

If we use an https:// address, you might need to import a certificate as well.

Request Method

The HTTP method to use when requesting the page. See http://www.w3.org/Protocols/HTTP/Methods.html for more information

Username

If set the HTTP Authorization header is set using this parameter along with the Password parameter.

Password

Used if Username is specified.

Proxy

If specified, connect to a proxy server rather than directly to the host specified in the URL. The format is proxyhost:port (for example, proxy:8080), where proxy is the name of the proxyhost, and 8080 is the port number to use.

File to HTTP Body

The full path of the file. The file contents are copied as HTTP body in the HTTP message. This overrides any possible Parser processing.

Content Type

If set, this will be used as the http.content-type for the file sent as specified by the File to HTTP Body parameter, or other HTTP Body Attribute that may be present in the Entry (see the HTTP Attributes described above).

File from Response HTTP Body

The full path of the file. The body of the response HTTP message is copied to the file.

Timeout

Timeout in seconds for each of the operations: connecting to the server and receiving response from it. A timeout of zero is interpreted as an infinite timeout. If the timeout expires, a java.net.SocketTimeoutException is raised (for more information see the online documentation for java.net.Socket).

Detailed Log

If this parameter is checked, more detailed log messages are generated.

You select a Parser from the Parser pane; select the parser by clicking the top-left Select Parser button. If specified, this Parser is used to generate the http.body content when sending data. The parser gets an entry with those attributes where the name does not begin with http. Also, this Parser (if specified) gets the http.body for additional parsing when receiving data. However, do not specify system:/Parsers/ibmdi.HTTP, because a message body does not contain another message.

Examples

In your attribute map we can use the following assignment to post the contents of a file to the HTTP server:

// Attribute assignment for "http.body" 
ret.value = new java.io.FileInputStream ("myfile.txt"); 

// Attribute assignment for "http.content-type" 
ret.value = "text/plain";

The Connector computes the http.content-length attribute for you. There is no need to specify this attribute.