The HTTP Client Connector enables greater control on HTTP sessions
than the URL Connector provides. With the HTTP Connector you 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, you will need to add these
to the Tivoli® Directory
Integrator truststore, and configure the truststore in global.properties or solution.properties.
More information about this can be found in the IBM Tivoli Directory Integrator V7.1.1 Installation and Administrator Guide,
in the section named "Client SSL configuration of TDI components".
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 you 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 you can dynamically change the request URL by setting
the search criteria as follows:
If you 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 you 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
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 you must obtain the value in the Connector's After Add hook.
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.
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.
Directory Integrator, Version 7.1.1