mbecke 2004/09/14 19:50:12
Modified: httpclient/xdocs navigation.xml userguide.xml
Added: httpclient/xdocs preference-api.xml
Log:
Adds preferences documentation.
PR: 29072
Submitted by: Oleg Kalnichevski
Reviewed by: Michael Becke
Revision Changes Path
1.12 +2 -1 jakarta-commons/httpclient/xdocs/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/navigation.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- navigation.xml 4 Sep 2004 17:02:04 -0000 1.11
+++ navigation.xml 15 Sep 2004 02:50:11 -0000 1.12
@@ -24,6 +24,7 @@
<item name="Exception Handling" href="/exception-handling.html"/>
<item name="Logging Guide" href="/logging.html"/>
<item name="Methods" href="/methods.html"/>
+ <item name="Preference Architecture" href="/preference-api.html"/>
<item name="Sample Code"
href="http://cvs.apache.org/viewcvs.cgi/jakarta-commons/httpclient/src/examples/"/>
<item name="SSL Guide" href="/sslguide.html"/>
<item name="Threading" href="/threading.html"/>
1.4 +12 -1 jakarta-commons/httpclient/xdocs/userguide.xml
Index: userguide.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/userguide.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- userguide.xml 3 Aug 2004 04:11:09 -0000 1.3
+++ userguide.xml 15 Sep 2004 02:50:11 -0000 1.4
@@ -40,6 +40,12 @@
across hosts.</td>
</tr>
<tr>
+ <td><a href="exception-handling.html">Exception Handling</a></td>
+ <td>This document outlines common types of errors that the users may
+ encounter and describes the exception handling framework used
+ by HttpClient.</td>
+ </tr>
+ <tr>
<td><a href="logging.html">Logging Guide</a></td>
<td>This document describes the logging mechanism used by HttpClient
and how to control what it outputs.</td>
@@ -48,6 +54,11 @@
<td><a href="methods.html">Methods</a></td>
<td>This document describes the various methods
that are provided by HttpClient and how to use them.</td>
+ </tr>
+ <tr>
+ <td><a href="preference-api.html">Preference Architecture</a></td>
+ <td>This document explains the preference architecture used by HttpClient
+ and enumerates standard HttpClient parameters.</td>
</tr>
<tr>
<td><a
href="http://cvs.apache.org/viewcvs.cgi/jakarta-commons/httpclient/src/examples/";>Sample
Code</a></td>
1.1 jakarta-commons/httpclient/xdocs/preference-api.xml
Index: preference-api.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>HttpClient preference architecture and configuration guide</title>
<author email="oleg -at- ural.ru">Oleg Kalnichevski</author>
<revision>$Id: preference-api.xml,v 1.1 2004/09/15 02:50:11 mbecke Exp
$</revision>
</properties>
<body>
<section name="Table of contents">
<ul>
<li>
<a href="#HttpClient preference architecture">HttpClient preference
architecture</a>
<ul>
<li><a href="#HTTP parameters">HTTP parameters</a></li>
<li><a href="#HTTP parameter hierarchy">HTTP parameter
hierarchy</a></li>
</ul>
</li>
<li>
<a href="#Supported parameters">Supported parameters</a>
<ul>
<li><a href="#HTTP method parameters">HTTP method
parameters</a></li>
<li><a href="#HTTP connection parameters">HTTP connection
parameters</a></li>
<li><a href="#HTTP connection manager parameters">HTTP
connection manager parameters</a></li>
<li><a href="#HTTP client parameters">HTTP client
parameters</a></li>
</ul>
</li>
</ul>
</section>
<section name="HttpClient preference architecture">
<p>
Quality and extent of the <a href="http://www.ietf.org/rfc/rfc1945.txt";>
<code>HTTP/1.0</code></a> and <a href="http://www.ietf.org/rfc/rfc2616.txt";>
<code>HTTP/1.1</code></a> spec compliance vary significantly among commonly
used HTTP agents and HTTP servers. That requires of HttpClient to be able to
<ul>
<li>mimic (mis-)behavior of widely used web browsers;</li>
<li>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;
</li>
<li>apply a different set of parameters to individual HTTP methods, hosts,
or
client instances using common interface;
</li>
</ul>
</p>
<subsection name="HTTP parameters">
<p>
As of version 3 HttpClient sports a new preference API based on
<a href="apidocs/org/apache/commons/httpclient/params/HttpParams.html">
HttpParams</a> 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.
<source><![CDATA[
HttpClient httpclient = new HttpClient();
HttpVersion ver =
(HttpVersion)httpclient.getParams().getParameter("http.protocol.version");]]></source>
</p>
<p>
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.
<source><![CDATA[
HttpClient httpclient = new HttpClient();
httpclient.getParams().setParameter("http.protocol.version", HttpVersion.HTTP_1_1);
httpclient.getParams().setParameter("http.socket.timeout", new Integer(1000));
httpclient.getParams().setParameter("http.protocol.content-charset", "UTF-8");
HostConfiguration hostconfig = new HostConfiguration();
hostconfig.setHost("www.yahoo.com");
hostconfig.getParams().setParameter("http.protocol.version", HttpVersion.HTTP_1_0);
GetMethod httpget = new GetMethod("/");
httpget.getParams().setParameter("http.socket.timeout", new Integer(5000));
try {
// Internally the parameter collections will be linked together
// by performing the following operations:
// hostconfig.getParams().setDefaults(httpclient.getParams());
// httpget.getParams().setDefaults(hostconfig.getParams());
httpclient.executeMethod(hostconfig, httpget);
System.out.println(httpget.getParams().getParameter("http.protocol.version"));
System.out.println(httpget.getParams().getParameter("http.socket.timeout"));
System.out.println(httpget.getParams().getParameter("http.protocol.content-charset"));
} finally {
httpget.releaseConnection();
}]]></source>
</p>
<p>
The code above will produce the following output:
<source><![CDATA[
HTTP/1.0
5000
UTF-8]]></source>
</p>
<p>
When resolving a parameter HttpClient uses the following algorithm:
<ul>
<li>start parameter lookup from the lowest level at which this parameter
applies</li>
<li>if the parameter is undefined at the current level, defer its
resolution to the
next level up in the hierarchy</li>
<li>return parameter value from the lowest level in the hierarchy the
parameter
defined at</li>
<li>return null if the parameter is undefined</li>
</ul>
</p>
<p>
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.
</p>
</subsection>
<subsection name="HTTP parameter hierarchy">
<p>
Presently HttpClient provides the following parameter hierarchy:
</p>
<source><![CDATA[
global--+ | DefaultHttpParams
| |
client | HttpClient
| |
+-- connection manager | HttpConnectionManager
| | |
| +-- connection | HttpConnection
| |
+-- host | HostConfiguration
| |
+-- method | HttpMethod
]]></source>
</subsection>
</section>
<section name="Supported parameters">
<subsection name="HTTP method parameters">
<p>
Applicable at the following levels: <b>global</b> -> <b>client</b> ->
<b>host</b> -> <b>method</b>
</p>
<table>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Default</th>
</tr>
<tr>
<td><p>http.useragent</p></td>
<td><p>String</p></td>
<td>
<p>
The content of the <code>User-Agent</code> header used by the HTTP
methods.
</p>
</td>
<td><p>official release name, e.g. "Jakarta
Commons-HttpClient/3.0"</p></td>
</tr>
<tr>
<td><p>http.protocol.version</p></td>
<td><p><a
href="apidocs/org/apache/commons/httpclient/HttpVersion.html">HttpVersion</a></p></td>
<td>
<p>
The HTTP protocol version used per default by the HTTP methods.
</p>
</td>
<td><p><a
href="apidocs/org/apache/commons/httpclient/HttpVersion.html#HTTP_1_1">
<code>HttpVersion.HTTP_1_1</code></a></p></td>
</tr>
<tr>
<td><p>http.protocol.unambiguous-statusline</p></td>
<td><p>Boolean</p></td>
<td>
<p>
Defines whether HTTP methods should reject ambiguous HTTP status line.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
<tr>
<td><p>http.protocol.single-cookie-header</p></td>
<td><p>Boolean</p></td>
<td>
<p>
Defines whether cookies should be put on a single response header.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
<tr>
<td><p>http.protocol.strict-transfer-encoding</p></td>
<td><p>Boolean</p></td>
<td>
<p>
Defines whether responses with an invalid <code>Transfer-Encoding</code>
header should be
rejected.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
<tr>
<td><p>http.protocol.reject-head-body</p></td>
<td><p>Boolean</p></td>
<td>
<p>
Defines whether the content body sent in response to <code>HEAD</code>
request should be
rejected.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
<tr>
<td><p>http.protocol.head-body-timeout</p></td>
<td><p>Integer</p></td>
<td>
<p>
Sets period of time in milliseconds to wait for a content body sent in
response to
<code>HEAD</code> response from a non-compliant server. If the parameter
is not set or set
to <code>-1</code> non-compliant response body check is disabled.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
<tr>
<td><p>http.protocol.expect-continue</p></td>
<td><p>Boolean</p></td>
<td>
<p>
Activates 'Expect: 100-Continue' handshake for the entity enclosing
methods. The 'Expect: 100-Continue'
handshake allows 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.
</p>
<p>
The use of the 'Expect: 100-continue' handshake can result in noticeable
performance improvement
for entity enclosing requests (such as <code>POST</code> and
<code>PUT</code>) that require the
target server's authentication.
</p>
<p>
'Expect: 100-continue' handshake should be used with caution, as it may
cause problems with HTTP
servers and proxies that do not support <code>HTTP/1.1</code> protocol.
</p>
<td><p><code><undefined></code></p></td>
</td>
</tr>
<tr>
<td><p>http.protocol.credential-charset</p></td>
<td><p>String</p></td>
<td>
<p>
The charset to be used when encoding credentials. If not defined then
the value of the
'http.protocol.element-charset' should be used.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
<tr>
<td><p>http.protocol.element-charset</p></td>
<td><p>String</p></td>
<td>
<p>
The charset to be used for encoding/decoding HTTP protocol elements
(status line and headers).
</p>
</td>
<td><p>'US-ASCII'</p></td>
</tr>
<tr>
<td><p>http.protocol.content-charset</p></td>
<td><p>String</p></td>
<td>
<p>
The charset to be used for encoding content body.
</p>
</td>
<td><p>'ISO-8859-1'</p></td>
</tr>
<tr>
<td><p>http.protocol.cookie-policy</p></td>
<td><p>String</p></td>
<td>
<p>
The cookie policy to be used for cookie management.
</p>
</td>
<td><p><a
href="apidocs/org/apache/commons/httpclient/cookie/CookiePolicy.html#RFC_2109">
<code>CookiePolicy.RFC_2109</code></a></p></td>
</tr>
<tr>
<td><p>http.protocol.warn-extra-input</p></td>
<td><p>Boolean</p></td>
<td>
<p>
Defines HttpClient's behavior when a response provides more bytes than
expected (specified
with <code>Content-Length</code> header, for example).
</p>
<p>
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.
</p>
<p>
If this parameter is set to <code>true</code>, any detection of extra
input data will generate
a warning in the log.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
<tr>
<td><p>http.protocol.status-line-garbage-limit</p></td>
<td><p>Integer</p></td>
<td>
<p>
Defines the maximum number of ignorable lines before we expect a HTTP
response's status code.
</p>
<p>
With HTTP/1.1 persistent connections, the problem arises that broken
scripts could return a
wrong <code>Content-Length</code> (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.
</p>
<p>
Set this to <code>0</code> to disallow any garbage/empty lines before
the status line.
To specify no limit, use <code>Integer#MAX_VALUE</code>.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
<tr>
<td><p>http.socket.timeout</p></td>
<td><p>Integer</p></td>
<td>
<p>
Sets the socket timeout (<code>SO_TIMEOUT</code>) in milliseconds to be
used when executing the
method. A timeout value of zero is interpreted as an infinite timeout.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
<tr>
<td><p>http.method.retry-handler</p></td>
<td><p><a
href="apidocs/org/apache/commons/httpclient/HttpMethodRetryHandler.html">
HttpMethodRetryHandler</a></p></td>
<td>
<p>
The method retry handler used for retrying failed methods. For details
see the
<a href ="exception-handling.html#Custom%20exception%20handler">Exception
handling guide</a>.
</p>
</td>
<td><p><a
href="apidocs/org/apache/commons/httpclient/DefaultHttpMethodRetryHandler.html">
default implementation</a></p></td>
</tr>
</table>
<p>
Whenever a parameter is left undefined (no value is explicitly set anywhere
in
the parameter hierarchy) HttpClient will use its best judgment to pick up a
value. This
default behavior is likely to provide the best compatibility with widely
used HTTP servers.
</p>
</subsection>
<subsection name="HTTP connection parameters">
<p>
Applicable at the following levels: <b>global</b> -> <b>client</b> ->
<b>connection manager</b> ->
<b>connection</b>
</p>
<table>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Default</th>
</tr>
<tr>
<td><p>http.socket.timeout</p></td>
<td><p>Integer</p></td>
<td>
<p>
The default socket timeout (<code>SO_TIMEOUT</code>) 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.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
<tr>
<td><p>http.tcp.nodelay</p></td>
<td><p>Boolean</p></td>
<td>
<p>
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 (by enabling
<code>TCP_NODELAY</code>). Data will be sent earlier, at the cost of an
increase
in bandwidth consumption.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
<tr>
<td><p>http.socket.sendbuffer</p></td>
<td><p>Integer</p></td>
<td>
<p>
The value to set on <a
href="http://java.sun.com/j2se/1.4.2/docs/api/java/net/Socket.html#setSendBufferSize(int)">
Socket.setSendBufferSize(int)</a>. 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.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
<tr>
<td><p>http.socket.receivebuffer</p></td>
<td><p>Integer</p></td>
<td>
<p>
The value to set on <a
href="http://java.sun.com/j2se/1.4.2/docs/api/java/net/Socket.html#setReceiveBufferSize(int)">
Socket.setReceiveBufferSize(int)</a>. 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.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
<tr>
<td><p>http.connection.timeout</p></td>
<td><p>Integer</p></td>
<td>
<p>
The timeout until a connection is established. A value of zero means the
timeout is not used.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
<tr>
<td><p>http.connection.stalecheck</p></td>
<td><p>Boolean</p></td>
<td>
<p>
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.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
</table>
<p>
Whenever a parameter is left undefined (no value is explicitly set anywhere
in
the parameter hierarchy) HttpClient will use its best judgment to pick up a
value. This
default behavior is likely to provide the best compatibility with widely
used HTTP servers.
</p>
</subsection>
<subsection name="HTTP connection manager parameters">
<p>
Applicable at the following levels: <b>global</b> -> <b>client</b> ->
<b>connection manager</b>
</p>
<table>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Default</th>
</tr>
<tr>
<td><p>http.connection-manager.max-per-host</p></td>
<td><p><a
href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Map.html";>Map</a></p></td>
<td>
<p>
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.
</p>
<p>
This parameter expects a value of type
<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Map.html";>
<code>Map</code></a>. The value should map instances of
<a href="apidocs/org/apache/commons/httpclient/HostConfiguration.html">
<code>HostConfiguration</code></a> to
<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Integer.html";>
<code>Integer</code></a>s. The default value can be specified using
<a
href="apidocs/org/apache/commons/httpclient/HostConfiguration.html#ANY_HOST_CONFIGURATION">
<code>ANY_HOST_CONFIGURATION</code></a>.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
<tr>
<td><p>http.connection-manager.max-total</p></td>
<td><p>Integer</p></td>
<td>
<p>
Defines the maximum number of connections allowed overall. This value
only applies
to the number of connections from a particular instance of
HttpConnectionManager.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
</table>
<p>
Whenever a parameter is left undefined (no value is explicitly set anywhere
in
the parameter hierarchy) HttpClient will use its best judgment to pick up a
value. This
default behavior is likely to provide the best compatibility with widely
used HTTP servers.
</p>
</subsection>
<subsection name="HTTP client parameters">
<p>
Applicable at the following levels: <b>client</b>
</p>
<table>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Default</th>
</tr>
<tr>
<td><p>http.connection-manager.timeout</p></td>
<td><p>Integer</p></td>
<td>
<p>
The timeout in milliseconds used when retrieving an HTTP connection from
the
HTTP connection manager.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
<tr>
<td><p>http.connection-manager.class</p></td>
<td><p>Class</p></td>
<td>
<p>
The default HTTP connection manager class.
</p>
</td>
<td><p>
<a
href="apidocs/org/apache/commons/httpclient/SimpleHttpConnectionManager.html">
<code>SimpleHttpConnectionManager</code></a> class</p></td>
</tr>
<tr>
<td><p>http.authentication.preemptive</p></td>
<td><p>Boolean</p></td>
<td>
<p>
Defines whether authentication should be attempted preemptively.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
<tr>
<td><p>http.protocol.reject-relative-redirect</p></td>
<td><p>Boolean</p></td>
<td>
<p>
Defines whether relative redirects should be rejected.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
<tr>
<td><p>http.protocol.max-redirects</p></td>
<td><p>Integer</p></td>
<td>
<p>
Defines the maximum number of redirects to be followed. The limit on
number of redirects
is intended to prevent infinite loops.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
<tr>
<td><p>http.protocol.allow-circular-redirects</p></td>
<td><p>Boolean</p></td>
<td>
<p>
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.
</p>
</td>
<td><p><code><undefined></code></p></td>
</tr>
</table>
<p>
Whenever a parameter is left undefined (no value is explicitly set anywhere
in
the parameter hierarchy) HttpClient will use its best judgment to pick up a
value. This
default behavior is likely to provide the best compatibility with widely
used HTTP servers.
</p>
</subsection>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
