HTTP Parser

The HTTP Parser interprets a byte stream according to the HTTP specification. This Parser is used by the HTTP Client Connector and by the HTTP Server Connector.

Configuration

The Parser has the following parameters:

Headers As Properties

If set, the header values are retrieved as Properties and set as Properties. If not set, the header values are read as Attributes and returned as Attributes.

Client Mode

If set, the parser operates in client HTTP response mode. If not set, the parser operates in server mode. This is of interest only if the Parser is writing an output stream.

Character Encoding

Character Encoding to be used. Also see Character sets/Encoding.

Detailed Log

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

Schema

The HTTP Parser sets the following Attributes in the work Entry (Input Attribute Map and Output Attribute Map). Note that when configuration parameter Header as Properties is enabled this schema is not useful because all attributes described below will be configured as Entry properties.

http.method

The method to be performed on the resource identified by the Request-URI. The method is case-sensitive (default is GET). See http://www.w3.org/Protocols/HTTP/Methods.html for more information about HTTP methods.

http.base

URI which identifies the resource upon which to apply the request.

http.responseCode

A 3-digit integer result code of the attempt to understand and satisfy the request. This attribute or property is mandatory in client mode.

http.responseMsg

Short textual description of the Response Code. This attribute or property is mandatory in client mode.

http.body

Body of the message. Used to carry the entity-body associated with the request or response message. The message-body differs from the entity-body only when a transfer-coding has been applied, as indicated by the http.Transfer-Encoding header field. When reading, depending on the content-type of the data, this object is an instance of java.lang.StringBuffer, a char[] or a byte[].

http.url

The URL to use. This attribute or property is mandatory in client mode.

http.remote_user

Username if present in http.Authorization header field of request message.

http.remote_pass

Password if present in http.Authorization header field of request message.

http.status

Used when writing in server mode. The default is 200 OK. Used to compose the Status-Line of the HTTP response message (see http://tools.ietf.org/html/rfc2616#section-6.1). Must contain the HTTP response Status-Code (3 digit number) and the HTTP response Reason-Phrase separated by a single space character. For example "201 Created". As an alternative we can use one of the following predefined values:

• OK or 200 OK - Returns a 200 OK response.

• FORBIDDEN or 401 Forbidden - Returns a 401 Forbidden response. The response uses the http.auth-realm attribute or property.

• NOT FOUND or 404 File Not Found - Returns a 404 File Not Found response.

http.auth-realm

Used when requesting additional authentication. The default value is IBM-Directory-Integrator.

http.redirect

When this attribute or property has a value, and you are writing and in server mode, redirect message pointing to the value of this attribute or property is sent.

http.qs.*

Parts of the query string when reading in server mode. The key is the part of the name after http.qs. The value is contained in the attribute or property.

http.*

All other attributes or properties beginning with http. are used to generate a header line when writing. When reading, headers are put into attributes or properties with a name beginning with http., and continuing with the name of the header.

General Header fields

http.Cache-Control

Used to specify directives that MUST be obeyed by all caching mechanisms along the request/response chain.

http.Connection

Allows the sender to specify options that are desired for that particular connection and MUST NOT be communicated by proxies over further connections.

http.Date

Represents the date and time at which the message was originated. The field value is an HTTP-date and has following format: 1*2DIGIT month 2*4DIGIT.

http.Pragma

Used to include implementation-specific directives that might apply to any recipient along the request/response chain. All pragma directives specify optional behavior from the viewpoint of the protocol.

http.Trailer

Indicates that the given set of header fields is present in the trailer of a message encoded with chunked transfer-coding.

http.Transfer-Encoding

Indicates what (if any) type of transformation has been applied to the message body in order to safely transfer it between the sender and the recipient. This differs from the content-coding in that the transfer-coding is a property of the message, not of the entity.

http.Upgrade

Allows the client to specify what additional communication protocols it supports and would like to use if the server finds it appropriate to switch protocols. This field is used within a 101 code (Switching Protocols).

http.Via

Allows the client to specify what additional communication protocols it supports and would like to use if the server finds it appropriate to switch protocols. This field is used within a 101 code (Switching Protocols).

http.Warning

Used to carry additional information about the status or transformation of a message which might not be reflected in the message. It has this format: 3DIGIT-warn-code SP warn-agent SP warn-text [SP warn-date].

Entity Header Fields

http.Allow

Lists the set of methods supported by the resource identified by the Request-URI. The purpose of this field is strictly to inform the recipient of valid methods associated with the resource. An Allow header field is present in a 405 (Method Not Allowed) response.

http.content-encoding

Used as a modifier to the media-type. When present, its value indicates what additional content codings have been applied to the entity-body, and thus what decoding mechanisms must be applied in order to obtain the media-type referenced by the http.Content-Type field.

http.Content-Language

Describes the natural language(s) of the intended audience for the enclosed entity. Note that this might not be equivalent to all the languages used within the entity-body.

http.content-length

Indicates the size of the entity-body, in decimal number of OCTETs, sent to the recipient or, in the case of the HEAD method, the size of the entity-body that would have been sent if the request was a GET. This attribute or property is returned when reading, and ignored when writing. It is recomputed by the Parser.

http.Content-Location

MAY be used to supply the resource location for the entity enclosed in the message when that entity is accessible from a location separate from the requested resource's URI. (absolute URI or relative URI).

http.Content-MD5

Is an MD5 digest of the entity-body for the purpose of providing an end-to-end message integrity check (MIC) of the entity-body.

http.Content-Range

Sent with a partial entity-body to specify where in the full entity-body the partial body should be applied.

http.content-type

Indicates the media type of the entity-body sent to the recipient or, in the case of the HEAD method, the media type that would have been sent had if the request was a GET.

http.Expires

Gives the date/time after which the response is considered stale.

http.Last-Modified

Indicates the date and time at which the origin server believes the variant was last modified. The format is HTTP-date.

Request Header Fields

http.Accept

Used to specify a set of desired media types which are acceptable for the response.

http.Accept-Charset

Used to indicate what character sets are acceptable for the response.

http.Accept-Encoding

Used to specify content-codings that are acceptable in the response.

http.Accept-Language

Used to specify set of natural languages that are preferred as a response to the request.

http.authorization

Consists of credentials containing the authentication information of the user agent for the realm of the resource being requested.

http.Expect

Used to indicate that particular server behaviors are required by the client.

http.From

If given, it contains an Internet e-mail address for the human user who controls the requesting user agent.

http.Host

Specifies the Internet host and port number of the resource being requested, as obtained from the original URI given by the user or referring resource (generally an HTTP URL). The Host field value MUST represent the naming authority of the origin server or gateway given by the original URL.

http.If-Match

Used with a method to make it conditional. A client that has one or more entities previously obtained from the resource can verify that one of those entities is current by including a list of their associated entity tags in the If-Match header field. The purpose of this feature is to allow efficient updates of cached information with a minimum amount of transaction overhead. It is also used, on updating requests, to prevent inadvertent modification of the wrong version of a resource. As a special case, the value "*" matches any current entity of the resource.

http.If-Modified-Since

Used with a method to make it conditional: if the requested variant has not been modified since the time specified in this field, an entity will not be returned from the server; instead, a 304 (not modified) response will be returned without any message-body. The format is HTTP-date.

http.If-None-Match

Used with a method to make it conditional. A client that has one or more entities previously obtained from the resource can verify that none of those entities is current by including a list of their associated entity tags in the If-None-Match header field.

http.If-Range

If a client has a partial copy of an entity in its cache, and wishes to have an up-to-date copy of the entire entity in its cache, it could use the Range request-header with a conditional GET. If the requested entity is unchanged, the part(s) that the client misses are send, otherwise - entire new entity. MAY contain HTTP date.

http.If-Unmodified-Since

Used with a method to make it conditional. If the requested resource has not been modified since the time specified in this field, the server would perform the requested operation as if the If-Unmodified-Since header were not present. If the requested variant has been modified since the specified time, the server will not perform the requested operation, and will return a 412 code (Precondition Failed). The format is HTTP-date.

http.Max-Forwards

Provides a mechanism with the TRACE and OPTIONS methods to limit the number of proxies or gateways that can forward the request to the next inbound server.

http.Proxy-Authorization

Allows the client to identify itself (or its user) to a proxy which requires authentication. Consist of credentials containing the authentication information of the user agent for the proxy and/or realm of the resource being requested.

http.Range

Indicates what range(s) (in bytes) of the result entity returned from HTTP request (using GET methods) will be received.

http.Referer

Allows the client to specify, for the server's benefit, the address (URI) of the resource from which the Request-URI was obtained.

http.TE

Indicates what extension transfer-codings it is willing to accept in the response and whether or not it is willing to accept trailer fields in a chunked transfer-coding.

http.User-Agent

Contains information about the user agent originating the request.

Response Header Fields

http.Accept-Ranges

Indicates that server accepts range requests for a resource but even if it is missing that doesn't mean not accepting.

http.Age

Conveys the sender's estimate of the amount of time since the response (or its revalidation) was generated at the originating server.

http.ETag

Provides the current value of the entity tag for the requested variant.The entity tag MAY be used for comparison with other entities from the same resource.

http.Location

Used to redirect the recipient to a location other than the Request-URI for completion of the request or identification of a new resource. The field value consists of a single absolute URI.

http.Proxy-Authenticate

Included as part of a 407 (Proxy Authentication Required) response. The field value consists of a challenge that indicates the authentication scheme and parameters applicable to the proxy for this Request-URI.

http.Retry-After

Can be used with a 503 (Service Unavailable) response to indicate how long the service is expected to be unavailable to the requesting client. This field MAY also be used with any 3xx (Redirection) response to indicate the minimum time the user-agent is asked wait before issuing the redirected request. The value of this field can be either an HTTP-date or an integer number of seconds (in decimal) after the time of the response.

http.Server

Contains information about the software used by the originating server to handle the request.

http.Vary

Indicates the set of request-header fields that fully determines, while the response is fresh, whether a cache is permitted to use the response to reply to a subsequent request without revalidation. For uncacheable or stale responses, the Vary field value advises the user agent about the criteria that were used to select the representation

http.WWW-Authenticate

Included in 401 (Unauthorized) response messages. The field value consists of at least one challenge that indicates the authentication scheme(s) and parameters applicable to the Request-URI.

Character sets/Encoding

Character set when reading

The default character encoding when reading is iso-8859-1. This encoding is overridden by the Character Encoding parameter in the config pane for this Connector; and this characterSet parameter is overridden in turn by a header of the type "Content-type: text/plain; charset=iso-8859-1". For optimum performance and compatibility, this header should be present.

Character set when sending

The default character encoding when reading is iso-8859-1. This encoding is overridden by the Character Encoding parameter in the config pane for this Connector. When sending a text message, the Entry to send should contain an attribute with the name "http.content-type", having a text value of the form "Content-type: text/plain; charset=iso-8859-1". The defaults will be used only if this attribute is not present .

If the http.body attribute is a java.io.File object, that file will be sent as is, no character conversion will be performed.

For further observations on Character Sets, also see Character Encoding conversion.

How to use HTTP cookies

HTTP cookies are HTTP headers whose syntax conforms to the HTTP State Management Mechanism standard (RFC 2109, RFC 2965).

The HTTP components of IBM TDI do not perform any special processing of cookie headers. If you wish to use cookies, we have to interpret the content of each cookie header yourself.

To set a cookie in an HTTP response use the "Set-cookie" HTTP header. For example:

work.setAttribute("http.Set-Cookie", "myname=myvalue; expires=Sat, 15-Jan-2011 13:23:56 GMT; path=/; domain=.ibm.com");

To set a cookie in an HTTP request use the "Cookie" HTTP header. For example:

work.setAttribute("http.Cookie", "myname=myvalue; myname2=myvalue2");

See also

Character Encoding conversion
HTTP Client Connector,
HTTP Server Connector.