Index: navigation.xml =================================================================== RCS file: /home/cvspublic/jakarta-commons/httpclient/xdocs/navigation.xml,v retrieving revision 1.11 diff -u -r1.11 navigation.xml --- navigation.xml 4 Sep 2004 17:02:04 -0000 1.11 +++ navigation.xml 9 Sep 2004 15:34:42 -0000 @@ -24,6 +24,7 @@ + Index: userguide.xml =================================================================== RCS file: /home/cvspublic/jakarta-commons/httpclient/xdocs/userguide.xml,v retrieving revision 1.3 diff -u -r1.3 userguide.xml --- userguide.xml 3 Aug 2004 04:11:09 -0000 1.3 +++ userguide.xml 9 Sep 2004 15:34:42 -0000 @@ -40,6 +40,12 @@ across hosts. + Exception Handling + This document outlines common types of errors that the users may + encounter and describes the exception handling framework used + by HttpClient. + + Logging Guide This document describes the logging mechanism used by HttpClient and how to control what it outputs. @@ -48,6 +54,11 @@ Methods This document describes the various methods that are provided by HttpClient and how to use them. + + + Preference Architecture + This document explains the preference architecture used by HttpClient + and enumerates standard HttpClient parameters. Sample Code Index: preference-api.xml =================================================================== RCS file: preference-api.xml diff -N preference-api.xml --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ preference-api.xml 1 Jan 1970 00:00:00 -0000 @@ -0,0 +1,567 @@ + + + + + + HttpClient preference architecture and configuration guide + Oleg Kalnichevski + $Id$ + + + +
+

+ Quality and extent of the + HTTP/1.0 and + HTTP/1.1 spec compliance vary significantly among commonly + used HTTP agents and HTTP servers. That requires of HttpClient to be able to +

    +
  • mimic (mis-)behavior of widely used web browsers;
  • +
  • support flexible and configurable level of leniency toward non-critical + protocol violations especially in those gray areas of the specification + subject to different, at times conflicting, interpretations; +
  • +
  • apply a different set of parameters to individual HTTP methods, hosts, or + client instances using common interface; +
  • +
+

+ +

+ As of version 3 HttpClient sports a new preference API based on + + HttpParams interface. All major components of the HttpClient toolkit + (agents, host configurations, methods, connections, connection managers) + contain a collection of HTTP parameters, which determine the runtime behavior + of those components. + +

+

+ In a nutshell HTTP parameters is a collection of name/object pairs that can be linked + with other collections to form a hierarchy. If a particular parameter value has not been + explicitly defined in the collection itself, its value will be drawn from the upper level + collection of parameters. + +

+

+ The code above will produce the following output: + +

+

+ When resolving a parameter HttpClient uses the following algorithm: +

    +
  • start parameter lookup from the lowest level at which this parameter applies
  • +
  • if the parameter is undefined at the current level, defer its resolution to the + next level up in the hierarchy
  • +
  • return parameter value from the lowest level in the hierarchy the parameter + defined at
  • +
  • return null if the parameter is undefined
  • +
+

+

+ This architecture enables the users to define generic parameters at a higher + level (for instance, at the agent level or host level) and selectively override + specific parameters at a lower level (for instance, at the method level). Whenever + a parameter is not explicitly defined at a given level, the defaults of the upper + levels will apply. +

+
+ +

+ Presently HttpClient provides the following parameter hierarchy: +

+ +
+
+
+ +

+ Applicable at the following levels: client -> host -> method +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault

http.useragent

String

+

+ The content of the User-Agent header used by the HTTP methods. +

+

official release name

http.protocol.version

HttpVersion

+

+ The HTTP protocol version used per default by the HTTP methods. +

+

+ HttpVersion.HTTP_1_1

http.protocol.unambiguous-statusline

Boolean

+

+ Defines whether HTTP methods should reject ambiguous HTTP status line. +

+

<undefined>

http.protocol.single-cookie-header

Boolean

+

+ Defines whether cookies should be put on a single response header. +

+

<undefined>

http.protocol.strict-transfer-encoding

Boolean

+

+ Defines whether responses with an invalid Transfer-Encoding header should be + rejected. +

+

<undefined>

http.protocol.reject-head-body

Boolean

+

+ Defines whether the content body sent in response to HEAD request should be + rejected. +

+

<undefined>

http.protocol.head-body-timeout

Integer

+

+ Sets period of time in milliseconds to wait for a content body sent in response to + HEAD response from a non-compliant server. If the parameter is not set or set + to -1 non-compliant response body check is disabled. +

+

<undefined>

http.protocol.expect-continue

Boolean

+

+ Activates 'Expect: 100-Continue' handshake for the entity enclosing methods}. The purpose of + the 'Expect: 100-Continue' handshake to allow a client that is sending a request message with + a request body to determine if the origin server is willing to accept the request (based on + the request headers) before the client sends the request body. +

+

+ The use of the 'Expect: 100-continue' handshake can result in noticeable performance improvement + for entity enclosing requests (such as POST and PUT) that require the + target server's authentication. +

+

+ 'Expect: 100-continue' handshake should be used with caution, as it may cause problems with HTTP + servers and proxies that do not support HTTP/1.1 protocol. +

+

<undefined>

http.protocol.credential-charset

String

+

+ The charset to be used when encoding credentials. If not defined then the value of the + 'http.protocol.element-charset' should be used. +

+

<undefined>

http.protocol.element-charset

String

+

+ The charset to be used for encoding HTTP protocol elements. +

+

'US-ASCII'

http.protocol.content-charset

String

+

+ The charset to be used for encoding content body. +

+

'ISO-8859-1'

http.protocol.cookie-policy

String

+

+ The cookie policy to be used for cookie management. +

+

+ CookiePolicy.RFC_2109

http.protocol.warn-extra-input

Boolean

+

+ Defines HttpClient's behavior when a response provides more bytes than expected (specified + with Content-Length header, for example). +

+

+ Such surplus data makes the HTTP connection unreliable for keep-alive requests, as malicious + response data (faked headers etc.) can lead to undesired results on the next request using + that connection. +

+

+ If this parameter is set to true, any detection of extra input data will generate + a warning in the log. +

+

<undefined>

http.protocol.status-line-garbage-limit

Integer

+

+ Defines the maximum number of ignorable lines before we expect a HTTP response's status code. +

+

+ With HTTP/1.1 persistent connections, the problem arises that broken scripts could return a + wrong Content-Length (there are more bytes sent than specified). Unfortunately, + in some cases, this is not possible after the bad response, but only before the next one. + So, HttpClient must be able to skip those surplus lines this way. +

+

+ Set this to 0 to disallow any garbage/empty lines before the status line. + To specify no limit, use Integer#MAX_VALUE. +

+

<undefined>

http.socket.timeout

Integer

+

+ Sets the socket timeout (SO_TIMEOUT) in milliseconds to be used when executing the + method. A timeout value of zero is interpreted as an infinite timeout. +

+

<undefined>

http.method.retry-handler

+ HttpMethodRetryHandler

+

+ The HTTP protocol version used per default by the HTTP methods. For details see + Exception handling guide. +

+

+ default implementation

+

+ Whenever a parameter is left undefined, that is there's no explicitly set value anywhere in + the parameter hierarchy, HttpClient will use its best judgment to pick up a value, which is + more likely to provide the best compatibility with the widely used HTTP servers. +

+
+ +

+ Applicable at the following levels: client -> connection manager -> + connection +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault

http.socket.timeout

Integer

+

+ The default socket timeout (SO_TIMEOUT) in milliseconds which is the timeout + for waiting for data. A timeout value of zero is interpreted as an infinite timeout. This + value is used when no socket timeout is set in the HTTP method parameters. +

+

<undefined>

http.tcp.nodelay

Boolean

+

+ Determines whether Nagle's algorithm is to be used. The Nagle's algorithm tries to conserve + bandwidth by minimizing the number of segments that are sent. When applications wish to + decrease network latency and increase performance, they can disable Nagle's algorithm (that + is enable TCP_NODELAY). Data will be sent earlier, at the cost of an increase + in bandwidth consumption. +

+

<undefined>

http.socket.sendbuffer

Integer

+

+ A hint size of the underlying buffers used by the platform for outgoing network I/O. This value + is a suggestion to the kernel from the application about the size of buffers to use for the + data to be sent over the socket. +

+

<undefined>

http.socket.receivebuffer

Integer

+

+ A hint size of the underlying buffers used by the platform for incoming network I/O. This value + is a suggestion to the kernel from the application about the size of buffers to use for the + data to be received over the socket. +

+

<undefined>

http.connection.timeout

Integer

+

+ The timeout until a connection is established. A value of zero means the timeout is not used. +

+

<undefined>

http.connection.stalecheck

Boolean

+

+ Determines whether stale connection check is to be used. Disabling stale connection check may + result in slight performance improvement at the risk of getting an I/O error when executing a + request over a connection that has been closed at the server side. +

+

<undefined>

+

+ Whenever a parameter is left undefined, that is there's no explicitly set value anywhere in + the parameter hierarchy, HttpClient will use its best judgment to pick up a value, which is + more likely to provide the best compatibility with the widely used HTTP servers. +

+
+ +

+ Applicable at the following levels: client -> connection manager +

+ + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault

http.connection-manager.max-per-host

Map

+

+ Defines the maximum number of connections allowed per host configuration. + These values only apply to the number of connections from a particular instance + of HttpConnectionManager. +

+

+ This parameter expects a value of type + + Map. The value should map instances of + + HostConfiguration to + + Integers. The default value can be specified using + + ANY_HOST_CONFIGURATION. +

+

<undefined>

http.connection-manager.max-total

Integer

+

+ Defines the maximum number of connections allowed overall. This value only applies + to the number of connections from a particular instance of HttpConnectionManager. +

+

<undefined>

+

+ Whenever a parameter is left undefined, that is there's no explicitly set value anywhere in + the parameter hierarchy, HttpClient will use its best judgment to pick up a value, which is + more likely to provide the best compatibility with the widely used HTTP servers. +

+
+ +

+ Applicable at the following levels: client +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault

http.connection-manager.timeout

Integer

+

+ The timeout in milliseconds used when retrieving an HTTP connection from the + HTTP connection manager. +

+

<undefined>

http.connection-manager.class

Class

+

+ The default HTTP connection manager class. +

+

+ + SimpleHttpConnectionManager class

http.authentication.preemptive

Boolean

+

+ Defines whether authentication should be attempted preemptively. +

+

<undefined>

http.protocol.reject-relative-redirect

Boolean

+

+ Defines whether relative redirects should be rejected. +

+

<undefined>

http.protocol.max-redirects

Integer

+

+ Defines the maximum number of redirects to be followed. The limit on number of redirects + is intended to prevent infinite loops. +

+

<undefined>

http.protocol.allow-circular-redirects

Boolean

+

+ Defines whether circular redirects (redirects to the same location) should be allowed. + The HTTP spec is not sufficiently clear whether circular redirects are permitted, + therefore optionally they can be enabled. +

+

<undefined>

+

+ Whenever a parameter is left undefined, that is there's no explicitly set value anywhere in + the parameter hierarchy, HttpClient will use its best judgment to pick up a value, which is + more likely to provide the best compatibility with the widely used HTTP servers. +

+
+
+ +