You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by mb...@apache.org on 2004/09/15 04:50:12 UTC
cvs commit: jakarta-commons/httpclient/xdocs preference-api.xml navigation.xml userguide.xml
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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org