Apache
/
httpcomponents-client
mirror of https://github.com/apache/httpcomponents-client.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Removed HttpClient 4.x tutorial source

This commit is contained in:
Oleg Kalnichevski 2018-10-23 15:09:39 +02:00
parent 9058b1b8e7
commit f3ae401ecf
17 changed files with 0 additions and 4055 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
pom.xml
View File

@ -245,60 +245,6 @@
</configuration>
</plugin>
<!--
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<dependencies>
<dependency>
<groupId>org.docbook</groupId>
<artifactId>docbook-xml</artifactId>
<version>4.4</version>
<scope>runtime</scope>
</dependency>
</dependencies>
<executions>
<execution>
<id>tutorial-site</id>
<goals>
<goal>generate-html</goal>
<goal>generate-pdf</goal>
</goals>
<phase>pre-site</phase>
</execution>
</executions>
<configuration>
<includes>index.xml</includes>
<chunkedOutput>true</chunkedOutput>
<xincludeSupported>true</xincludeSupported>
<foCustomization>src/docbkx/resources/xsl/fopdf.xsl</foCustomization>
<htmlCustomization>src/docbkx/resources/xsl/html_chunk.xsl</htmlCustomization>
<htmlStylesheet>css/hc-tutorial.css</htmlStylesheet>
<entities>
<entity>
<name>version</name>
<value>${project.version}</value>
</entity>
</entities>
<postProcess>
<copy todir="target/site/tutorial/html" failonerror="false">
<fileset dir="target/docbkx/html/index">
<include name="**/*.html" />
</fileset>
</copy>
<copy todir="target/site/tutorial/html" failonerror="false">
<fileset dir="src/docbkx/resources">
<include name="**/*.css" />
<include name="**/*.png" />
<include name="**/*.gif" />
<include name="**/*.jpg" />
</fileset>
</copy>
<copy file="target/docbkx/pdf/index.pdf" tofile="target/site/tutorial/pdf/httpclient-tutorial.pdf" failonerror="false" />
</postProcess>
</configuration>
</plugin>
-->
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<executions>

275
src/docbkx/advanced.xml
View File

@ -1,275 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
====================================================================
-->
<chapter id="advanced">
<title>Advanced topics</title>
<section>
<title>Custom client connections</title>
<para>In certain situations it may be necessary to customize the way HTTP messages get
transmitted across the wire beyond what is possible using HTTP parameters in
order to be able to deal non-standard, non-compliant behaviours. For instance, for web
crawlers it may be necessary to force HttpClient into accepting malformed response heads
in order to salvage the content of the messages. </para>
<para>Usually the process of plugging in a custom message parser or a custom connection
implementation involves several steps:</para>
<itemizedlist>
<listitem>
<para>Provide a custom <interfacename>LineParser</interfacename> /
<interfacename>LineFormatter</interfacename> interface implementation.
Implement message parsing / formatting logic as required.</para>
<programlisting><![CDATA[
class MyLineParser extends BasicLineParser {
@Override
public Header parseHeader(
CharArrayBuffer buffer) throws ParseException {
try {
return super.parseHeader(buffer);
} catch (ParseException ex) {
// Suppress ParseException exception
return new BasicHeader(buffer.toString(), null);
}
}
}
]]></programlisting>
</listitem>
<listitem>
<para>Provide a custom <interfacename>HttpConnectionFactory</interfacename>
implementation. Replace default request writer and / or response parser
with custom ones as required. </para>
<programlisting><![CDATA[
HttpConnectionFactory<HttpRoute, ManagedHttpClientConnection> connFactory =
new ManagedHttpClientConnectionFactory(
new DefaultHttpRequestWriterFactory(),
new DefaultHttpResponseParserFactory(
new MyLineParser(), new DefaultHttpResponseFactory()));
]]></programlisting>
</listitem>
<listitem>
<para>Configure HttpClient to use the custom connection factory.</para>
<programlisting><![CDATA[
PoolingHttpClientConnectionManager cm = new PoolingHttpClientConnectionManager(
connFactory);
CloseableHttpClient httpclient = HttpClients.custom()
.setConnectionManager(cm)
.build();
]]></programlisting>
</listitem>
</itemizedlist>
</section>
<section id="stateful_conn">
<title>Stateful HTTP connections</title>
<para>While HTTP specification assumes that session state information is always embedded in
HTTP messages in the form of HTTP cookies and therefore HTTP connections are always
stateless, this assumption does not always hold true in real life. There are cases when
HTTP connections are created with a particular user identity or within a particular
security context and therefore cannot be shared with other users and can be reused by
the same user only. Examples of such stateful HTTP connections are
<literal>NTLM</literal> authenticated connections and SSL connections with client
certificate authentication.</para>
<section>
<title>User token handler</title>
<para>HttpClient relies on <interfacename>UserTokenHandler</interfacename> interface to
determine if the given execution context is user specific or not. The token object
returned by this handler is expected to uniquely identify the current user if the
context is user specific or to be null if the context does not contain any resources
or details specific to the current user. The user token will be used to ensure that
user specific resources will not be shared with or reused by other users.</para>
<para>The default implementation of the <interfacename>UserTokenHandler</interfacename>
interface uses an instance of Principal class to represent a state object for HTTP
connections, if it can be obtained from the given execution context.
<classname>DefaultUserTokenHandler</classname> will use the user principal of
connection based authentication schemes such as <literal>NTLM</literal> or that of
the SSL session with client authentication turned on. If both are unavailable, null
token will be returned.</para>
<programlisting><![CDATA[
CloseableHttpClient httpclient = HttpClients.createDefault();
HttpClientContext context = HttpClientContext.create();
HttpGet httpget = new HttpGet("http://localhost:8080/");
CloseableHttpResponse response = httpclient.execute(httpget, context);
try {
Principal principal = context.getUserToken(Principal.class);
System.out.println(principal);
} finally {
response.close();
}
]]></programlisting>
<para>Users can provide a custom implementation if the default one does not satisfy
their needs:</para>
<programlisting><![CDATA[
UserTokenHandler userTokenHandler = new UserTokenHandler() {
public Object getUserToken(HttpContext context) {
return context.getAttribute("my-token");
}
};
CloseableHttpClient httpclient = HttpClients.custom()
.setUserTokenHandler(userTokenHandler)
.build();
]]></programlisting>
</section>
<section>
<title>Persistent stateful connections</title>
<para>Please note that a persistent connection that carries a state object can be reused
only if the same state object is bound to the execution context when requests
are executed. So, it is really important to ensure the either same context is
reused for execution of subsequent HTTP requests by the same user or the user
token is bound to the context prior to request execution.</para>
<programlisting><![CDATA[
CloseableHttpClient httpclient = HttpClients.createDefault();
HttpClientContext context1 = HttpClientContext.create();
HttpGet httpget1 = new HttpGet("http://localhost:8080/");
CloseableHttpResponse response1 = httpclient.execute(httpget1, context1);
try {
HttpEntity entity1 = response1.getEntity();
} finally {
response1.close();
}
Principal principal = context1.getUserToken(Principal.class);
HttpClientContext context2 = HttpClientContext.create();
context2.setUserToken(principal);
HttpGet httpget2 = new HttpGet("http://localhost:8080/");
CloseableHttpResponse response2 = httpclient.execute(httpget2, context2);
try {
HttpEntity entity2 = response2.getEntity();
} finally {
response2.close();
}
]]></programlisting>
</section>
</section>
<section>
<title>Using the FutureRequestExecutionService</title>
<para>Using the FutureRequestExecutionService, you can schedule http calls and treat the response
as a Future. This is useful when e.g. making multiple calls to a web service. The advantage of using
the FutureRequestExecutionService is that you can use multiple threads to schedule requests concurrently, set timeouts on
the tasks, or cancel them when a response is no longer necessary.
</para>
<para>FutureRequestExecutionService wraps the request with a HttpRequestFutureTask, which extends FutureTask. This
class allows you to cancel the task as well as keep track of various metrics such as request duration.</para>
<section>
<title>Creating the FutureRequestExecutionService</title>
<para>The constructor for the futureRequestExecutionService takes any existing httpClient instance and an ExecutorService
instance. When configuring both, it is important to align the maximum number of connections with the number of threads
you are going to use. When there are more threads than connections, the connections may start timing out because there are no
available connections. When there are more connections than threads, the futureRequestExecutionService will not use all of them</para>
<programlisting><![CDATA[
HttpClient httpClient = HttpClientBuilder.create().setMaxConnPerRoute(5).build();
ExecutorService executorService = Executors.newFixedThreadPool(5);
FutureRequestExecutionService futureRequestExecutionService =
new FutureRequestExecutionService(httpClient, executorService);
]]></programlisting>
</section>
<section>
<title>Scheduling requests</title>
<para>To schedule a request, simply provide a HttpUriRequest, HttpContext, and a ResponseHandler. Because
the request is processed by the executor service, a ResponseHandler is mandatory.</para>
<programlisting><![CDATA[
private final class OkidokiHandler implements ResponseHandler<Boolean> {
public Boolean handleResponse(
final HttpResponse response) throws ClientProtocolException, IOException {
return response.getStatusLine().getStatusCode() == 200;
}
}
HttpRequestFutureTask<Boolean> task = futureRequestExecutionService.execute(
new HttpGet("http://www.google.com"), HttpClientContext.create(),
new OkidokiHandler());
// blocks until the request complete and then returns true if you can connect to Google
boolean ok=task.get();
]]></programlisting>
</section>
<section>
<title>Canceling tasks</title>
<para>Scheduled tasks may be cancelled. If the task is not yet executing but merely queued for execution, it simply will never execute. If it is executing and the mayInterruptIfRunning parameter is set to true, abort() will be called on the request; otherwise the response will simply be ignored but the request will be allowed to complete normally. Any subsequent calls to task.get() will fail with an IllegalStateException. It should be noticed that canceling tasks merely frees up the client side resources. The request may actually be handled normally on the server side. </para>
<programlisting><![CDATA[
task.cancel(true)
task.get() // throws an Exception
]]></programlisting>
</section>
<section>
<title>Callbacks</title>
<para>Instead of manually calling task.get(), you can also use a FutureCallback instance that gets callbacks when the request completes. This is the
same interface as is used in HttpAsyncClient</para>
<programlisting><![CDATA[
private final class MyCallback implements FutureCallback<Boolean> {
public void failed(final Exception ex) {
// do something
}
public void completed(final Boolean result) {
// do something
}
public void cancelled() {
// do something
}
}
HttpRequestFutureTask<Boolean> task = futureRequestExecutionService.execute(
new HttpGet("http://www.google.com"), HttpClientContext.create(),
new OkidokiHandler(), new MyCallback());
]]></programlisting>
</section>
<section>
<title>Metrics</title>
<para>FutureRequestExecutionService is typically used in applications that make large amounts of
web service calls. To facilitate e.g. monitoring or configuration tuning, the FutureRequestExecutionService keeps
track of several metrics.</para>
<para>Each HttpRequestFutureTask provides methods to get the time the task was scheduled,
started, and ended. Additionally, request and task duration are available as well. These
metrics are aggregated in the FutureRequestExecutionService in a FutureRequestExecutionMetrics
instance that may be accessed through FutureRequestExecutionService.metrics().</para>
<programlisting><![CDATA[
task.scheduledTime() // returns the timestamp the task was scheduled
task.startedTime() // returns the timestamp when the task was started
task.endedTime() // returns the timestamp when the task was done executing
task.requestDuration // returns the duration of the http request
task.taskDuration // returns the duration of the task from the moment it was scheduled
FutureRequestExecutionMetrics metrics = futureRequestExecutionService.metrics()
metrics.getActiveConnectionCount() // currently active connections
metrics.getScheduledConnectionCount(); // currently scheduled connections
metrics.getSuccessfulConnectionCount(); // total number of successful requests
metrics.getSuccessfulConnectionAverageDuration(); // average request duration
metrics.getFailedConnectionCount(); // total number of failed tasks
metrics.getFailedConnectionAverageDuration(); // average duration of failed tasks
metrics.getTaskCount(); // total number of tasks scheduled
metrics.getRequestCount(); // total number of requests
metrics.getRequestAverageDuration(); // average request duration
metrics.getTaskAverageDuration(); // average task duration
]]></programlisting>
</section>
</section>
</chapter>

522
src/docbkx/authentication.xml
View File

@ -1,522 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
====================================================================
-->
<chapter id="authentication">
<title>HTTP authentication</title>
<para>HttpClient provides full support for authentication schemes defined by the HTTP standard
specification as well as a number of widely used non-standard authentication schemes such
as <literal>NTLM</literal> and <literal>SPNEGO</literal>.</para>
<section>
<title>User credentials</title>
<para>Any process of user authentication requires a set of credentials that can be used to
establish user identity. In the simplest form user credentials can be just a user name /
password pair. <classname>UsernamePasswordCredentials</classname> represents a set of
credentials consisting of a security principal and a password in clear text. This
implementation is sufficient for standard authentication schemes defined by the HTTP
standard specification.</para>
<programlisting><![CDATA[
UsernamePasswordCredentials creds = new UsernamePasswordCredentials("user", "pwd");
System.out.println(creds.getUserPrincipal().getName());
System.out.println(creds.getPassword());
]]></programlisting>
<para>stdout &gt;</para>
<programlisting><![CDATA[
user
pwd
]]></programlisting>
<para><classname>NTCredentials</classname> is a Microsoft Windows specific implementation
that includes in addition to the user name / password pair a set of additional Windows
specific attributes such as the name of the user domain. In a Microsoft Windows network
the same user can belong to multiple domains each with a different set of
authorizations.</para>
<programlisting><![CDATA[
NTCredentials creds = new NTCredentials("user", "pwd", "workstation", "domain");
System.out.println(creds.getUserPrincipal().getName());
System.out.println(creds.getPassword());
]]></programlisting>
<para>stdout &gt;</para>
<programlisting><![CDATA[
DOMAIN/user
pwd
]]></programlisting>
</section>
<section>
<title>Authentication schemes</title>
<para>The <interfacename>AuthScheme</interfacename> interface represents an abstract
challenge-response oriented authentication scheme. An authentication scheme is expected
to support the following functions:</para>
<itemizedlist>
<listitem>
<para>Parse and process the challenge sent by the target server in response to
request for a protected resource.</para>
</listitem>
<listitem>
<para>Provide properties of the processed challenge: the authentication scheme type
and its parameters, such the realm this authentication scheme is applicable to,
if available</para>
</listitem>
<listitem>
<para>Generate the authorization string for the given set of credentials and the HTTP
request in response to the actual authorization challenge.</para>
</listitem>
</itemizedlist>
<para>Please note that authentication schemes may be stateful involving a series of
challenge-response exchanges.</para>
<para>HttpClient ships with several <interfacename>AuthScheme</interfacename>
implementations:</para>
<itemizedlist>
<listitem>
<formalpara>
<title>Basic:</title>
<para>Basic authentication scheme as defined in RFC 2617. This authentication
scheme is insecure, as the credentials are transmitted in clear text.
Despite its insecurity Basic authentication scheme is perfectly adequate if
used in combination with the TLS/SSL encryption.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Digest</title>
<para>Digest authentication scheme as defined in RFC 2617. Digest authentication
scheme is significantly more secure than Basic and can be a good choice for
those applications that do not want the overhead of full transport security
through TLS/SSL encryption.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>NTLM:</title>
<para>NTLM is a proprietary authentication scheme developed by Microsoft and
optimized for Windows platforms. NTLM is believed to be more secure than
Digest.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>SPNEGO:</title>
<para><literal>SPNEGO</literal> (<emphasis>S</emphasis>imple and
<emphasis>P</emphasis>rotected <literal>GSSAPI</literal>
<emphasis>Nego</emphasis>tiation Mechanism) is a <literal>GSSAPI</literal>
"pseudo mechanism" that is used to negotiate one of a number of possible
real mechanisms. SPNEGO's most visible use is in Microsoft's <literal>HTTP
Negotiate</literal> authentication extension. The negotiable
sub-mechanisms include NTLM and Kerberos supported by Active Directory.
At present HttpClient only supports the Kerberos sub-mechanism. </para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Kerberos:</title>
<para>Kerberos authentication implementation. </para>
</formalpara>
</listitem>
</itemizedlist>
</section>
<section>
<title>Credentials provider</title>
<para>Credentials providers are intended to maintain a set of user credentials and to be
able to produce user credentials for a particular authentication scope. Authentication
scope consists of a host name, a port number, a realm name and an authentication scheme
name. When registering credentials with the credentials provider one can provide a wild
card (any host, any port, any realm, any scheme) instead of a concrete attribute value.
The credentials provider is then expected to be able to find the closest match for a
particular scope if the direct match cannot be found.</para>
<para>HttpClient can work with any physical representation of a credentials provider that
implements the <interfacename>CredentialsProvider</interfacename> interface. The default
<interfacename>CredentialsProvider</interfacename> implementation called
<classname>BasicCredentialsProvider</classname> is a simple implementation backed by
a <classname>java.util.HashMap</classname>.</para>
<programlisting><![CDATA[
CredentialsProvider credsProvider = new BasicCredentialsProvider();
credsProvider.setCredentials(
new AuthScope("somehost", AuthScope.ANY_PORT),
new UsernamePasswordCredentials("u1", "p1"));
credsProvider.setCredentials(
new AuthScope("somehost", 8080),
new UsernamePasswordCredentials("u2", "p2"));
credsProvider.setCredentials(
new AuthScope("otherhost", 8080, AuthScope.ANY_REALM, "ntlm"),
new UsernamePasswordCredentials("u3", "p3"));
System.out.println(credsProvider.getCredentials(
new AuthScope("somehost", 80, "realm", "basic")));
System.out.println(credsProvider.getCredentials(
new AuthScope("somehost", 8080, "realm", "basic")));
System.out.println(credsProvider.getCredentials(
new AuthScope("otherhost", 8080, "realm", "basic")));
System.out.println(credsProvider.getCredentials(
new AuthScope("otherhost", 8080, null, "ntlm")));
]]></programlisting>
<para>stdout &gt;</para>
<programlisting><![CDATA[
[principal: u1]
[principal: u2]
null
[principal: u3]
]]></programlisting>
</section>
<section>
<title>HTTP authentication and execution context</title>
<para>HttpClient relies on the <classname>AuthState</classname> class to keep track of
detailed information about the state of the authentication process. HttpClient creates
two instances of <classname>AuthState</classname> in the course of HTTP request
execution: one for target host authentication and another one for proxy authentication.
In case the target server or the proxy require user authentication the respective
<classname>AuthScope</classname> instance will be populated with the
<classname>AuthScope</classname>, <interfacename>AuthScheme</interfacename> and
<interfacename>Crednetials</interfacename> used during the authentication process.
The <classname>AuthState</classname> can be examined in order to find out what kind of
authentication was requested, whether a matching
<interfacename>AuthScheme</interfacename> implementation was found and whether the
credentials provider managed to find user credentials for the given authentication
scope.</para>
<para>In the course of HTTP request execution HttpClient adds the following authentication
related objects to the execution context:</para>
<itemizedlist>
<listitem>
<formalpara>
<para><interfacename>Lookup</interfacename> instance representing the actual
authentication scheme registry. The value of this attribute set in the local
context takes precedence over the default one.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<para><interfacename>CredentialsProvider</interfacename> instance representing
the actual credentials provider. The value of this attribute set in the
local context takes precedence over the default one.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<para><classname>AuthState</classname> instance representing the actual target
authentication state. The value of this attribute set in the local context
takes precedence over the default one.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<para><classname>AuthState</classname> instance representing the actual proxy
authentication state. The value of this attribute set in the local context
takes precedence over the default one.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<para><interfacename>AuthCache</interfacename> instance representing the actual
authentication data cache. The value of this attribute set in the local
context takes precedence over the default one.</para>
</formalpara>
</listitem>
</itemizedlist>
<para>The local <interfacename>HttpContext</interfacename> object can be used to customize
the HTTP authentication context prior to request execution, or to examine its state after
the request has been executed:</para>
<programlisting><![CDATA[
CloseableHttpClient httpclient = <...>
CredentialsProvider credsProvider = <...>
Lookup<AuthSchemeProvider> authRegistry = <...>
AuthCache authCache = <...>
HttpClientContext context = HttpClientContext.create();
context.setCredentialsProvider(credsProvider);
context.setAuthSchemeRegistry(authRegistry);
context.setAuthCache(authCache);
HttpGet httpget = new HttpGet("http://somehost/");
CloseableHttpResponse response1 = httpclient.execute(httpget, context);
<...>
AuthState proxyAuthState = context.getProxyAuthState();
System.out.println("Proxy auth state: " + proxyAuthState.getState());
System.out.println("Proxy auth scheme: " + proxyAuthState.getAuthScheme());
System.out.println("Proxy auth credentials: " + proxyAuthState.getCredentials());
AuthState targetAuthState = context.getTargetAuthState();
System.out.println("Target auth state: " + targetAuthState.getState());
System.out.println("Target auth scheme: " + targetAuthState.getAuthScheme());
System.out.println("Target auth credentials: " + targetAuthState.getCredentials());
]]></programlisting>
</section>
<section>
<title>Caching of authentication data</title>
<para>As of version 4.1 HttpClient automatically caches information about hosts it has
successfully authenticated with. Please note that one must use the same execution
context to execute logically related requests in order for cached authentication data
to propagate from one request to another. Authentication data will be lost as soon as
the execution context goes out of scope.</para>
</section>
<section>
<title>Preemptive authentication</title>
<para>HttpClient does not support preemptive authentication out of the box, because if
misused or used incorrectly the preemptive authentication can lead to significant
security issues, such as sending user credentials in clear text to an unauthorized third
party. Therefore, users are expected to evaluate potential benefits of preemptive
authentication versus security risks in the context of their specific application
environment.</para>
<para>Nonetheless one can configure HttpClient to authenticate preemptively by prepopulating
the authentication data cache.</para>
<programlisting><![CDATA[
CloseableHttpClient httpclient = <...>
HttpHost targetHost = new HttpHost("localhost", 80, "http");
CredentialsProvider credsProvider = new BasicCredentialsProvider();
credsProvider.setCredentials(
new AuthScope(targetHost.getHostName(), targetHost.getPort()),
new UsernamePasswordCredentials("username", "password"));
// Create AuthCache instance
AuthCache authCache = new BasicAuthCache();
// Generate BASIC scheme object and add it to the local auth cache
BasicScheme basicAuth = new BasicScheme();
authCache.put(targetHost, basicAuth);
// Add AuthCache to the execution context
HttpClientContext context = HttpClientContext.create();
context.setCredentialsProvider(credsProvider);
context.setAuthCache(authCache);
HttpGet httpget = new HttpGet("/");
for (int i = 0; i < 3; i++) {
CloseableHttpResponse response = httpclient.execute(
targetHost, httpget, context);
try {
HttpEntity entity = response.getEntity();
} finally {
response.close();
}
}
]]></programlisting>
</section>
<section id="ntlm">
<title>NTLM Authentication</title>
<para>As of version 4.1 HttpClient provides full support for NTLMv1, NTLMv2, and NTLM2
Session authentication out of the box. One can still continue using an external
<literal>NTLM</literal> engine such as <ulink url="http://jcifs.samba.org/">JCIFS
</ulink> library developed by the <ulink url="http://www.samba.org/">Samba</ulink>
project as a part of their Windows interoperability suite of programs.
</para>
<section>
<title>NTLM connection persistence</title>
<para>The <literal>NTLM</literal> authentication scheme is significantly more expensive
in terms of computational overhead and performance impact than the standard
<literal>Basic</literal> and <literal>Digest</literal> schemes. This is likely to be
one of the main reasons why Microsoft chose to make <literal>NTLM</literal>
authentication scheme stateful. That is, once authenticated, the user identity is
associated with that connection for its entire life span. The stateful nature of
<literal>NTLM</literal> connections makes connection persistence more complex, as
for the obvious reason persistent <literal>NTLM</literal> connections may not be
re-used by users with a different user identity. The standard connection managers
shipped with HttpClient are fully capable of managing stateful connections. However,
it is critically important that logically related requests within the same session
use the same execution context in order to make them aware of the current user
identity. Otherwise, HttpClient will end up creating a new HTTP connection for each
HTTP request against <literal>NTLM</literal> protected resources. For detailed
discussion on stateful HTTP connections please refer to
<link linkend="stateful_conn">this </link> section. </para>
<!-- Note: the stateful_conn anchor is in the file advanced.xml -->
<para>As <literal>NTLM</literal> connections are stateful it is generally recommended
to trigger <literal>NTLM</literal> authentication using a relatively cheap method,
such as <literal>GET</literal> or <literal>HEAD</literal>, and re-use the same
connection to execute more expensive methods, especially those enclose a request
entity, such as <literal>POST</literal> or <literal>PUT</literal>. </para>
<programlisting><![CDATA[
CloseableHttpClient httpclient = <...>
CredentialsProvider credsProvider = new BasicCredentialsProvider();
credsProvider.setCredentials(AuthScope.ANY,
new NTCredentials("user", "pwd", "myworkstation", "microsoft.com"));
HttpHost target = new HttpHost("www.microsoft.com", 80, "http");
// Make sure the same context is used to execute logically related requests
HttpClientContext context = HttpClientContext.create();
context.setCredentialsProvider(credsProvider);
// Execute a cheap method first. This will trigger NTLM authentication
HttpGet httpget = new HttpGet("/ntlm-protected/info");
CloseableHttpResponse response1 = httpclient.execute(target, httpget, context);
try {
HttpEntity entity1 = response1.getEntity();
} finally {
response1.close();
}
// Execute an expensive method next reusing the same context (and connection)
HttpPost httppost = new HttpPost("/ntlm-protected/form");
httppost.setEntity(new StringEntity("lots and lots of data"));
CloseableHttpResponse response2 = httpclient.execute(target, httppost, context);
try {
HttpEntity entity2 = response2.getEntity();
} finally {
response2.close();
}
]]></programlisting>
</section>
</section>
<section id="spnego">
<title><literal>SPNEGO</literal>/Kerberos Authentication</title>
<para>The <literal>SPNEGO</literal> (<emphasis>S</emphasis>imple and
<emphasis>P</emphasis>rotected <literal>GSSAPI</literal>
<emphasis>Nego</emphasis>tiation Mechanism) is designed to allow for authentication to
services when neither end knows what the other can use/provide. It is most commonly used
to do Kerberos authentication. It can wrap other mechanisms, however the current version
in HttpClient is designed solely with Kerberos in mind. </para>
<sidebar>
<orderedlist numeration="arabic">
<listitem>
<para>Client Web Browser does HTTP GET for resource.</para>
</listitem>
<listitem>
<para>Web server returns HTTP 401 status and a header:
<literal>WWW-Authenticate: Negotiate</literal></para>
</listitem>
<listitem>
<para>Client generates a <literal>NegTokenInit</literal>, base64 encodes it, and
resubmits the <literal>GET</literal> with an Authorization header:
<literal>Authorization: Negotiate &lt;base64
encoding&gt;</literal>.</para>
</listitem>
<listitem>
<para>Server decodes the <literal>NegTokenInit</literal>, extracts the supported
<literal>MechTypes</literal> (only Kerberos V5 in our case), ensures it
is one of the expected ones, and then extracts the
<literal>MechToken</literal> (Kerberos Token) and authenticates
it.</para>
<para>If more processing is required another HTTP 401 is returned to the client
with more data in the the <literal>WWW-Authenticate</literal> header. Client
takes the info and generates another token passing this back in the
<literal>Authorization</literal> header until complete.</para>
</listitem>
<listitem>
<para>When the client has been authenticated the Web server should return the
HTTP 200 status, a final <literal>WWW-Authenticate</literal> header and the
page content.</para>
</listitem>
</orderedlist>
</sidebar>
<section>
<title><literal>SPNEGO</literal> support in HttpClient</title>
<para>The <literal>SPNEGO</literal> authentication scheme is compatible with Sun Java
versions 1.5 and up. However the use of Java >= 1.6 is strongly recommended as it
supports <literal>SPNEGO</literal> authentication more completely.</para>
<para>The Sun JRE provides the supporting classes to do nearly all the Kerberos and
<literal>SPNEGO</literal> token handling. This means that a lot of the setup is
for the GSS classes. The <classname>SPNegoScheme</classname> is a simple class to
handle marshalling the tokens and reading and writing the correct headers.</para>
<para>The best way to start is to grab the <literal>KerberosHttpClient.java</literal>
file in examples and try and get it to work. There are a lot of issues that can
happen but if lucky it'll work without too much of a problem. It should also provide some
output to debug with.</para>
<para>In Windows it should default to using the logged in credentials; this can be
overridden by using 'kinit' e.g. <literal>$JAVA_HOME\bin\kinit
testuser@AD.EXAMPLE.NET</literal>, which is very helpful for testing and
debugging issues. Remove the cache file created by kinit to revert back to the windows
Kerberos cache.</para>
<para>Make sure to list <literal>domain_realms</literal> in the
<literal>krb5.conf</literal> file. This is a major source of problems.</para>
</section>
<section>
<title>GSS/Java Kerberos Setup</title>
<para>This documentation assumes you are using Windows but much of the information
applies to Unix as well.</para>
<para>The <classname>org.ietf.jgss</classname> classes have lots of possible
configuration parameters, mainly in the
<literal>krb5.conf</literal>/<literal>krb5.ini</literal> file. Some more info on
the format at <ulink
url="http://web.mit.edu/kerberos/krb5-1.4/krb5-1.4.1/doc/krb5-admin/krb5.conf.html"
>http://web.mit.edu/kerberos/krb5-1.4/krb5-1.4.1/doc/krb5-admin/krb5.conf.html</ulink>.</para>
</section>
<section>
<title><literal>login.conf</literal> file</title>
<para>The following configuration is a basic setup that works in Windows XP against both
<literal>IIS</literal> and <literal>JBoss Negotiation</literal> modules.</para>
<para>The system property <literal>java.security.auth.login.config</literal> can be used
to point at the <literal>login.conf</literal> file.</para>
<para><literal>login.conf</literal> content may look like the following:</para>
<programlisting><![CDATA[
com.sun.security.jgss.login {
com.sun.security.auth.module.Krb5LoginModule required client=TRUE useTicketCache=true;
};
com.sun.security.jgss.initiate {
com.sun.security.auth.module.Krb5LoginModule required client=TRUE useTicketCache=true;
};
com.sun.security.jgss.accept {
com.sun.security.auth.module.Krb5LoginModule required client=TRUE useTicketCache=true;
};
]]>
</programlisting>
</section>
<section>
<title><literal>krb5.conf</literal> / <literal>krb5.ini</literal> file</title>
<para>If unspecified, the system default will be used. Override if needed by setting the
system property <literal>java.security.krb5.conf</literal> to point to a custom
<literal>krb5.conf</literal> file.</para>
<para><literal>krb5.conf</literal> content may look like the following:</para>
<programlisting><![CDATA[
[libdefaults]
default_realm = AD.EXAMPLE.NET
udp_preference_limit = 1
[realms]
AD.EXAMPLE.NET = {
kdc = KDC.AD.EXAMPLE.NET
}
[domain_realms]
.ad.example.net=AD.EXAMPLE.NET
ad.example.net=AD.EXAMPLE.NET
]]>
</programlisting>
</section>
<section>
<title>Windows Specific configuration</title>
<para>To allow Windows to use the current user's tickets, the system property
<literal>javax.security.auth.useSubjectCredsOnly</literal> must be set to
<literal>false</literal> and the Windows registry key
<literal>allowtgtsessionkey</literal> should be added and set correctly to allow
session keys to be sent in the Kerberos Ticket-Granting Ticket.</para>
<para>On the Windows Server 2003 and Windows 2000 SP4, here is the required registry
setting:</para>
<programlisting><![CDATA[
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos\Parameters
Value Name: allowtgtsessionkey
Value Type: REG_DWORD
Value: 0x01
]]>
</programlisting>
<para>Here is the location of the registry setting on Windows XP SP2:</para>
<programlisting><![CDATA[
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos\
Value Name: allowtgtsessionkey
Value Type: REG_DWORD
Value: 0x01
]]>
</programlisting>
</section>
</section>
</chapter>

253
src/docbkx/caching.xml
View File

@ -1,253 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
====================================================================
-->
<chapter id="caching">
<title>HTTP Caching</title>
<section id="generalconcepts">
<title>General Concepts</title>
<para>HttpClient Cache provides an HTTP/1.1-compliant caching layer to be
used with HttpClient--the Java equivalent of a browser cache. The
implementation follows the Chain of Responsibility design pattern, where the
caching HttpClient implementation can serve a drop-in replacement for
the default non-caching HttpClient implementation; requests that can be
satisfied entirely from the cache will not result in actual origin requests.
Stale cache entries are automatically validated with the origin where possible,
using conditional GETs and the If-Modified-Since and/or If-None-Match request
headers.
</para>
<para>
HTTP/1.1 caching in general is designed to be <emphasis>semantically
transparent</emphasis>; that is, a cache should not change the meaning of
the request-response exchange between client and server. As such, it should
be safe to drop a caching HttpClient into an existing compliant client-server
relationship. Although the caching module is part of the client from an
HTTP protocol point of view, the implementation aims to be compatible with
the requirements placed on a transparent caching proxy.
</para>
<para>Finally, caching HttpClient includes support the Cache-Control
extensions specified by RFC 5861 (stale-if-error and stale-while-revalidate).
</para>
<para>When caching HttpClient executes a request, it goes through the
following flow:</para>
<orderedlist>
<listitem>
<para>Check the request for basic compliance with the HTTP 1.1
protocol and attempt to correct the request.</para>
</listitem>
<listitem>
<para>Flush any cache entries which would be invalidated by this
request.</para>
</listitem>
<listitem>
<para>Determine if the current request would be servable from cache.
If not, directly pass through the request to the origin server and
return the response, after caching it if appropriate.</para>
</listitem>
<listitem>
<para>If it was a a cache-servable request, it will attempt to read it
from the cache. If it is not in the cache, call the origin server and
cache the response, if appropriate.</para>
</listitem>
<listitem>
<para>If the cached response is suitable to be served as a response,
construct a BasicHttpResponse containing a ByteArrayEntity and return
it. Otherwise, attempt to revalidate the cache entry against the
origin server.</para>
</listitem>
<listitem>
<para>In the case of a cached response which cannot be revalidated,
call the origin server and cache the response, if appropriate.</para>
</listitem>
</orderedlist>
<para>When caching HttpClient receives a response, it goes through the
following flow:</para>
<orderedlist>
<listitem>
<para>Examining the response for protocol compliance</para>
</listitem>
<listitem>
<para>Determine whether the response is cacheable</para>
</listitem>
<listitem>
<para>If it is cacheable, attempt to read up to the maximum size
allowed in the configuration and store it in the cache.</para>
</listitem>
<listitem>
<para>If the response is too large for the cache, reconstruct the
partially consumed response and return it directly without caching
it.</para>
</listitem>
</orderedlist>
<para>It is important to note that caching HttpClient is not, itself,
a different implementation of HttpClient, but that it works by inserting
itself as an additonal processing component to the request execution
pipeline.</para>
</section>
<section id="rfc2616compliance">
<title>RFC-2616 Compliance</title>
<para>We believe HttpClient Cache is <emphasis>unconditionally
compliant</emphasis> with <ulink
url="http://www.ietf.org/rfc/rfc2616.txt">RFC-2616</ulink>. That is,
wherever the specification indicates MUST, MUST NOT, SHOULD, or SHOULD NOT
for HTTP caches, the caching layer attempts to behave in a way that satisfies
those requirements. This means the caching module won't produce incorrect
behavior when you drop it in. </para>
</section>
<section>
<title>Example Usage</title>
<para>This is a simple example of how to set up a basic caching HttpClient.
As configured, it will store a maximum of 1000 cached objects, each of
which may have a maximum body size of 8192 bytes. The numbers selected
here are for example only and not intended to be prescriptive or
considered as recommendations.</para>
<programlisting><![CDATA[
CacheConfig cacheConfig = CacheConfig.custom()
.setMaxCacheEntries(1000)
.setMaxObjectSize(8192)
.build();
RequestConfig requestConfig = RequestConfig.custom()
.setConnectTimeout(30000)
.setSocketTimeout(30000)
.build();
CloseableHttpClient cachingClient = CachingHttpClients.custom()
.setCacheConfig(cacheConfig)
.setDefaultRequestConfig(requestConfig)
.build();
HttpCacheContext context = HttpCacheContext.create();
HttpGet httpget = new HttpGet("http://www.mydomain.com/content/");
CloseableHttpResponse response = cachingClient.execute(httpget, context);
try {
CacheResponseStatus responseStatus = context.getCacheResponseStatus();
switch (responseStatus) {
case CACHE_HIT:
System.out.println("A response was generated from the cache with " +
"no requests sent upstream");
break;
case CACHE_MODULE_RESPONSE:
System.out.println("The response was generated directly by the " +
"caching module");
break;
case CACHE_MISS:
System.out.println("The response came from an upstream server");
break;
case VALIDATED:
System.out.println("The response was generated from the cache " +
"after validating the entry with the origin server");
break;
}
} finally {
response.close();
}
]]>
</programlisting>
</section>
<section id="configuration">
<title>Configuration</title>
<para>The caching HttpClient inherits all configuration options and parameters
of the default non-caching implementation (this includes setting options like
timeouts and connection pool sizes). For caching-specific configuration, you can
provide a <classname>CacheConfig</classname> instance to customize behavior
across the following areas:</para>
<para><emphasis>Cache size.</emphasis> If the backend storage supports these limits,
you can specify the maximum number of cache entries as well as the maximum cacheable
response body size.</para>
<para><emphasis>Public/private caching.</emphasis> By default, the caching module
considers itself to be a shared (public) cache, and will not, for example, cache
responses to requests with Authorization headers or responses marked with
"Cache-Control: private". If, however, the cache is only going to be used by one
logical "user" (behaving similarly to a browser cache), then you will want to turn
off the shared cache setting.</para>
<para><emphasis>Heuristic caching.</emphasis>Per RFC2616, a cache MAY cache
certain cache entries even if no explicit cache control headers are set by the
origin. This behavior is off by default, but you may want to turn this on if you
are working with an origin that doesn't set proper headers but where you still
want to cache the responses. You will want to enable heuristic caching, then
specify either a default freshness lifetime and/or a fraction of the time since
the resource was last modified. See Sections 13.2.2 and 13.2.4 of the HTTP/1.1
RFC for more details on heuristic caching.</para>
<para><emphasis>Background validation.</emphasis> The cache module supports the
stale-while-revalidate directive of RFC5861, which allows certain cache entry
revalidations to happen in the background. You may want to tweak the settings
for the minimum and maximum number of background worker threads, as well as the
maximum time they can be idle before being reclaimed. You can also control the
size of the queue used for revalidations when there aren't enough workers to
keep up with demand.</para>
</section>
<section id="storage">
<title>Storage Backends</title>
<para>The default implementation of caching HttpClient stores cache entries and
cached response bodies in memory in the JVM of your application. While this
offers high performance, it may not be appropriate for your application due to
the limitation on size or because the cache entries are ephemeral and don't
survive an application restart. The current release includes support for storing
cache entries using EhCache and memcached implementations, which allow for
spilling cache entries to disk or storing them in an external process.</para>
<para>If none of those options are suitable for your application, it is
possible to provide your own storage backend by implementing the HttpCacheStorage
interface and then supplying that to caching HttpClient at construction time. In
this case, the cache entries will be stored using your scheme but you will get to
reuse all of the logic surrounding HTTP/1.1 compliance and cache handling.
Generally speaking, it should be possible to create an HttpCacheStorage
implementation out of anything that supports a key/value store (similar to the
Java Map interface) with the ability to apply atomic updates.</para>
<para>Finally, with some extra efforts it's entirely possible to set up
a multi-tier caching hierarchy; for example, wrapping an in-memory caching
HttpClient around one that stores cache entries on disk or remotely in memcached,
following a pattern similar to virtual memory, L1/L2 processor caches, etc.
</para>
</section>
</chapter>

560
src/docbkx/connmgmt.xml
View File

@ -1,560 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
====================================================================
-->
<chapter id="connmgmt">
<title>Connection management</title>
<section>
<title>Connection persistence</title>
<para>The process of establishing a connection from one host to another is quite complex and
involves multiple packet exchanges between two endpoints, which can be quite time
consuming. The overhead of connection handshaking can be significant, especially for
small HTTP messages. One can achieve a much higher data throughput if open connections
can be re-used to execute multiple requests.</para>
<para>HTTP/1.1 states that HTTP connections can be re-used for multiple requests per
default. HTTP/1.0 compliant endpoints can also use a mechanism to explicitly
communicate their preference to keep connection alive and use it for multiple requests.
HTTP agents can also keep idle connections alive for a certain period time in case a
connection to the same target host is needed for subsequent requests. The ability to
keep connections alive is usually refered to as connection persistence. HttpClient fully
supports connection persistence.</para>
</section>
<section>
<title>HTTP connection routing</title>
<para>HttpClient is capable of establishing connections to the target host either directly
or via a route that may involve multiple intermediate connections - also referred to as
hops. HttpClient differentiates connections of a route into plain, tunneled and layered.
The use of multiple intermediate proxies to tunnel connections to the target host is
referred to as proxy chaining.</para>
<para>Plain routes are established by connecting to the target or the first and only proxy.
Tunnelled routes are established by connecting to the first and tunnelling through a
chain of proxies to the target. Routes without a proxy cannot be tunnelled. Layered
routes are established by layering a protocol over an existing connection. Protocols can
only be layered over a tunnel to the target, or over a direct connection without
proxies.</para>
<section>
<title>Route computation</title>
<para>The <interfacename>RouteInfo</interfacename> interface represents information
about a definitive route to a target host involving one or more intermediate steps
or hops. <classname>HttpRoute</classname> is a concrete implementation of
the <interfacename>RouteInfo</interfacename>, which cannot be changed (is
immutable). <classname>HttpTracker</classname> is a mutable
<interfacename>RouteInfo</interfacename> implementation used internally by
HttpClient to track the remaining hops to the ultimate route target.
<classname>HttpTracker</classname> can be updated after a successful execution
of the next hop towards the route target. <classname>HttpRouteDirector</classname>
is a helper class that can be used to compute the next step in a route. This class
is used internally by HttpClient.</para>
<para><interfacename>HttpRoutePlanner</interfacename> is an interface representing a
strategy to compute a complete route to a given target based on the execution
context. HttpClient ships with two default
<interfacename>HttpRoutePlanner</interfacename> implementations.
<classname>SystemDefaultRoutePlanner</classname> is based on
<classname>java.net.ProxySelector</classname>. By default, it will pick up the
proxy settings of the JVM, either from system properties or from the browser running
the application. The <classname>DefaultProxyRoutePlanner</classname> implementation
does not make use of any Java system properties, nor any system or browser proxy
settings. It always computes routes via the same default proxy.</para>
</section>
<section>
<title>Secure HTTP connections</title>
<para>HTTP connections can be considered secure if information transmitted between two
connection endpoints cannot be read or tampered with by an unauthorized third party.
The SSL/TLS protocol is the most widely used technique to ensure HTTP transport
security. However, other encryption techniques could be employed as well. Usually,
HTTP transport is layered over the SSL/TLS encrypted connection.</para>
</section>
</section>
<section>
<title>HTTP connection managers</title>
<section>
<title>Managed connections and connection managers</title>
<para>HTTP connections are complex, stateful, thread-unsafe objects which need to be
properly managed to function correctly. HTTP connections can only be used by one
execution thread at a time. HttpClient employs a special entity to manage access to
HTTP connections called HTTP connection manager and represented by the
<interfacename>HttpClientConnectionManager</interfacename> interface. The purpose of
an HTTP connection manager is to serve as a factory for new HTTP connections,
to manage life cycle of persistent connections and to synchronize access to
persistent connections making sure that only one thread can have access
to a connection at a time. Internally HTTP connection managers work with instances
of <interfacename>ManagedHttpClientConnection</interfacename> acting as a proxy
for a real connection that manages connection state and controls execution
of I/O operations. If a managed connection is released or get explicitly closed
by its consumer the underlying connection gets detached from its proxy and is
returned back to the manager. Even though the service consumer still holds
a reference to the proxy instance, it is no longer able to execute any
I/O operations or change the state of the real connection either intentionally
or unintentionally.</para>
<para>This is an example of acquiring a connection from a connection manager:</para>
<programlisting><![CDATA[
HttpClientContext context = HttpClientContext.create();
HttpClientConnectionManager connMrg = new BasicHttpClientConnectionManager();
HttpRoute route = new HttpRoute(new HttpHost("localhost", 80));
// Request new connection. This can be a long process
ConnectionRequest connRequest = connMrg.requestConnection(route, null);
// Wait for connection up to 10 sec
HttpClientConnection conn = connRequest.get(10, TimeUnit.SECONDS);
try {
// If not open
if (!conn.isOpen()) {
// establish connection based on its route info
connMrg.connect(conn, route, 1000, context);
// and mark it as route complete
connMrg.routeComplete(conn, route, context);
}
// Do useful things with the connection.
} finally {
connMrg.releaseConnection(conn, null, 1, TimeUnit.MINUTES);
}
]]></programlisting>
<para>The connection request can be terminated prematurely by calling
<methodname>ConnectionRequest#cancel()</methodname> if necessary. This will unblock
the thread blocked in the <methodname>ConnectionRequest#get()</methodname>
method.</para>
</section>
<section>
<title>Simple connection manager</title>
<para><classname>BasicHttpClientConnectionManager</classname> is a simple connection
manager that maintains only one connection at a time. Even though this class
is thread-safe it ought to be used by one execution thread only.
<classname>BasicHttpClientConnectionManager</classname> will make an effort to reuse
the connection for subsequent requests with the same route. It will, however, close
the existing connection and re-open it for the given route, if the route of the
persistent connection does not match that of the connection request.
If the connection has been already been allocated, then <exceptionname>
java.lang.IllegalStateException</exceptionname> is thrown.</para>
<para>This connection manager implementation should be used inside an EJB
container.</para>
</section>
<section>
<title>Pooling connection manager</title>
<para><classname>PoolingHttpClientConnectionManager</classname> is a more complex
implementation that manages a pool of client connections and is able to service
connection requests from multiple execution threads. Connections are pooled on a per
route basis. A request for a route for which the manager already has a persistent
connection available in the pool will be serviced by leasing a connection from
the pool rather than creating a brand new connection.</para>
<para><classname>PoolingHttpClientConnectionManager</classname> maintains a maximum
limit of connections on a per route basis and in total. Per default this
implementation will create no more than 2 concurrent connections per given route
and no more 20 connections in total. For many real-world applications these limits
may prove too constraining, especially if they use HTTP as a transport protocol for
their services.</para>
<para>This example shows how the connection pool parameters can be adjusted:</para>
<programlisting><![CDATA[
PoolingHttpClientConnectionManager cm = new PoolingHttpClientConnectionManager();
// Increase max total connection to 200
cm.setMaxTotal(200);
// Increase default max connection per route to 20
cm.setDefaultMaxPerRoute(20);
// Increase max connections for localhost:80 to 50
HttpHost localhost = new HttpHost("locahost", 80);
cm.setMaxPerRoute(new HttpRoute(localhost), 50);
CloseableHttpClient httpClient = HttpClients.custom()
.setConnectionManager(cm)
.build();
]]></programlisting>
</section>
<section>
<title>Connection manager shutdown</title>
<para>When an HttpClient instance is no longer needed and is about to go out of scope it
is important to shut down its connection manager to ensure that all connections kept
alive by the manager get closed and system resources allocated by those connections
are released.</para>
<programlisting><![CDATA[
CloseableHttpClient httpClient = <...>
httpClient.close();
]]></programlisting>
</section>
</section>
<section>
<title>Multithreaded request execution</title>
<para>When equipped with a pooling connection manager such as <classname>
PoolingClientConnectionManager</classname>, HttpClient can be used to execute multiple
requests simultaneously using multiple threads of execution.</para>
<para>The <classname>PoolingClientConnectionManager</classname> will allocate connections
based on its configuration. If all connections for a given route have already been
leased, a request for a connection will block until a connection is released back to
the pool. One can ensure the connection manager does not block indefinitely in the
connection request operation by setting <literal>'http.conn-manager.timeout'</literal>
to a positive value. If the connection request cannot be serviced within the given time
period <exceptionname>ConnectionPoolTimeoutException</exceptionname> will be thrown.
</para>
<programlisting><![CDATA[
PoolingHttpClientConnectionManager cm = new PoolingHttpClientConnectionManager();
CloseableHttpClient httpClient = HttpClients.custom()
.setConnectionManager(cm)
.build();
// URIs to perform GETs on
String[] urisToGet = {
"http://www.domain1.com/",
"http://www.domain2.com/",
"http://www.domain3.com/",
"http://www.domain4.com/"
};
// create a thread for each URI
GetThread[] threads = new GetThread[urisToGet.length];
for (int i = 0; i < threads.length; i++) {
HttpGet httpget = new HttpGet(urisToGet[i]);
threads[i] = new GetThread(httpClient, httpget);
}
// start the threads
for (int j = 0; j < threads.length; j++) {
threads[j].start();
}
// join the threads
for (int j = 0; j < threads.length; j++) {
threads[j].join();
}
]]></programlisting>
<para>While <interfacename>HttpClient</interfacename> instances are thread safe and can be
shared between multiple threads of execution, it is highly recommended that each
thread maintains its own dedicated instance of <interfacename>HttpContext
</interfacename>.</para>
<programlisting><![CDATA[
static class GetThread extends Thread {
private final CloseableHttpClient httpClient;
private final HttpContext context;
private final HttpGet httpget;
public GetThread(CloseableHttpClient httpClient, HttpGet httpget) {
this.httpClient = httpClient;
this.context = HttpClientContext.create();
this.httpget = httpget;
}
@Override
public void run() {
try {
CloseableHttpResponse response = httpClient.execute(
httpget, context);
try {
HttpEntity entity = response.getEntity();
} finally {
response.close();
}
} catch (ClientProtocolException ex) {
// Handle protocol errors
} catch (IOException ex) {
// Handle I/O errors
}
}
}
]]></programlisting>
</section>
<section>
<title>Connection eviction policy</title>
<para>One of the major shortcomings of the classic blocking I/O model is that the network
socket can react to I/O events only when blocked in an I/O operation. When a connection
is released back to the manager, it can be kept alive however it is unable to monitor
the status of the socket and react to any I/O events. If the connection gets closed on
the server side, the client side connection is unable to detect the change in the
connection state (and react appropriately by closing the socket on its end).</para>
<para>HttpClient tries to mitigate the problem by testing whether the connection is 'stale',
that is no longer valid because it was closed on the server side, prior to using the
connection for executing an HTTP request. The stale connection check is not 100%
reliable. The only feasible solution that does not involve a one thread per socket
model for idle connections is a dedicated monitor thread used to evict connections
that are considered expired due to a long period of inactivity. The monitor thread can
periodically call
<methodname>ClientConnectionManager#closeExpiredConnections()</methodname> method to
close all expired connections and evict closed connections from the pool. It can also
optionally call <methodname>ClientConnectionManager#closeIdleConnections()</methodname>
method to close all connections that have been idle over a given period of time.</para>
<programlisting><![CDATA[
public static class IdleConnectionMonitorThread extends Thread {
private final HttpClientConnectionManager connMgr;
private volatile boolean shutdown;
public IdleConnectionMonitorThread(HttpClientConnectionManager connMgr) {
super();
this.connMgr = connMgr;
}
@Override
public void run() {
try {
while (!shutdown) {
synchronized (this) {
wait(5000);
// Close expired connections
connMgr.closeExpiredConnections();
// Optionally, close connections
// that have been idle longer than 30 sec
connMgr.closeIdleConnections(30, TimeUnit.SECONDS);
}
}
} catch (InterruptedException ex) {
// terminate
}
}
public void shutdown() {
shutdown = true;
synchronized (this) {
notifyAll();
}
}
}
]]></programlisting>
</section>
<section>
<title>Connection keep alive strategy</title>
<para>The HTTP specification does not specify how long a persistent connection may be and
should be kept alive. Some HTTP servers use a non-standard <literal>Keep-Alive</literal>
header to communicate to the client the period of time in seconds they intend to keep
the connection alive on the server side. HttpClient makes use of this information if
available. If the <literal>Keep-Alive</literal> header is not present in the response,
HttpClient assumes the connection can be kept alive indefinitely. However, many HTTP
servers in general use are configured to drop persistent connections after a certain period
of inactivity in order to conserve system resources, quite often without informing the
client. In case the default strategy turns out to be too optimistic, one may want to
provide a custom keep-alive strategy.</para>
<programlisting><![CDATA[
ConnectionKeepAliveStrategy myStrategy = new ConnectionKeepAliveStrategy() {
public long getKeepAliveDuration(HttpResponse response, HttpContext context) {
// Honor 'keep-alive' header
HeaderElementIterator it = new BasicHeaderElementIterator(
response.headerIterator(HTTP.CONN_KEEP_ALIVE));
while (it.hasNext()) {
HeaderElement he = it.nextElement();
String param = he.getName();
String value = he.getValue();
if (value != null && param.equalsIgnoreCase("timeout")) {
try {
return Long.parseLong(value) * 1000;
} catch(NumberFormatException ignore) {
}
}
}
HttpHost target = (HttpHost) context.getAttribute(
HttpClientContext.HTTP_TARGET_HOST);
if ("www.naughty-server.com".equalsIgnoreCase(target.getHostName())) {
// Keep alive for 5 seconds only
return 5 * 1000;
} else {
// otherwise keep alive for 30 seconds
return 30 * 1000;
}
}
};
CloseableHttpClient client = HttpClients.custom()
.setKeepAliveStrategy(myStrategy)
.build();
]]></programlisting>
</section>
<section>
<title>Connection socket factories</title>
<para>HTTP connections make use of a <classname>java.net.Socket</classname> object
internally to handle transmission of data across the wire. However they rely on
the <interfacename>ConnectionSocketFactory</interfacename> interface to create,
initialize and connect sockets. This enables the users of HttpClient to provide
application specific socket initialization code at runtime. <classname>
PlainConnectionSocketFactory</classname> is the default factory for creating and
initializing plain (unencrypted) sockets.</para>
<para>The process of creating a socket and that of connecting it to a host are decoupled, so
that the socket could be closed while being blocked in the connect operation.</para>
<programlisting><![CDATA[
HttpClientContext clientContext = HttpClientContext.create();
PlainConnectionSocketFactory sf = PlainConnectionSocketFactory.getSocketFactory();
Socket socket = sf.createSocket(clientContext);
int timeout = 1000; //ms
HttpHost target = new HttpHost("localhost");
InetSocketAddress remoteAddress = new InetSocketAddress(
InetAddress.getByAddress(new byte[] {127,0,0,1}), 80);
sf.connectSocket(timeout, socket, target, remoteAddress, null, clientContext);
]]></programlisting>
<section>
<title>Secure socket layering</title>
<para><interfacename>LayeredConnectionSocketFactory</interfacename> is an extension of
the <interfacename>ConnectionSocketFactory</interfacename> interface. Layered socket
factories are capable of creating sockets layered over an existing plain socket.
Socket layering is used primarily for creating secure sockets through proxies.
HttpClient ships with <classname>SSLSocketFactory</classname> that implements
SSL/TLS layering. Please note HttpClient does not use any custom encryption
functionality. It is fully reliant on standard Java Cryptography (JCE) and Secure
Sockets (JSEE) extensions.</para>
</section>
<section>
<title>Integration with connection manager</title>
<para>Custom connection socket factories can be associated with a particular
protocol scheme as as HTTP or HTTPS and then used to create a custom connection
manager.</para>
<programlisting><![CDATA[
ConnectionSocketFactory plainsf = <...>
LayeredConnectionSocketFactory sslsf = <...>
Registry<ConnectionSocketFactory> r = RegistryBuilder.<ConnectionSocketFactory>create()
.register("http", plainsf)
.register("https", sslsf)
.build();
HttpClientConnectionManager cm = new PoolingHttpClientConnectionManager(r);
HttpClients.custom()
.setConnectionManager(cm)
.build();
]]></programlisting>
</section>
<section>
<title>SSL/TLS customization</title>
<para>HttpClient makes use of <classname>SSLConnectionSocketFactory</classname>
to create SSL connections. <classname>SSLConnectionSocketFactory</classname> allows
for a high degree of customization. It can take an instance of
<interfacename>javax.net.ssl.SSLContext</interfacename> as a parameter and use
it to create custom configured SSL connections.</para>
<programlisting><![CDATA[
KeyStore myTrustStore = <...>
SSLContext sslContext = SSLContexts.custom()
.loadTrustMaterial(myTrustStore)
.build();
SSLConnectionSocketFactory sslsf = new SSLConnectionSocketFactory(sslContext);
]]></programlisting>
<para>Customization of <classname>SSLConnectionSocketFactory</classname> implies
a certain degree of familiarity with the concepts of the SSL/TLS protocol,
a detailed explanation of which is out of scope for this document. Please refer
to the <ulink
url="http://docs.oracle.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html">
Java&#x2122; Secure Socket Extension (JSSE) Reference Guide</ulink> for a detailed description of
<interfacename>javax.net.ssl.SSLContext</interfacename> and related
tools.</para>
</section>
<section>
<title>Hostname verification</title>
<para>In addition to the trust verification and the client authentication performed on
the SSL/TLS protocol level, HttpClient can optionally verify whether the target
hostname matches the names stored inside the server's X.509 certificate, once the
connection has been established. This verification can provide additional guarantees
of authenticity of the server trust material.
The <interfacename>javax.net.ssl.HostnameVerifier</interfacename> interface
represents a strategy for hostname verification. HttpClient ships with two
<interfacename>javax.net.ssl.HostnameVerifier</interfacename> implementations.
Important: hostname verification should not be confused with
SSL trust verification.</para>
<itemizedlist>
<listitem>
<formalpara>
<title><classname>DefaultHostnameVerifier</classname>:</title>
<para>The default implementation used by HttpClient is expected to be
compliant with RFC 2818. The hostname must match any of alternative
names specified by the certificate, or in case no alternative
names are given the most specific CN of the certificate subject. A
wildcard can occur in the CN, and in any of the subject-alts.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title><classname>NoopHostnameVerifier</classname>:</title>
<para>This hostname verifier essentially turns hostname verification off.
It accepts any SSL session as valid and matching the target host.
</para>
</formalpara>
</listitem>
</itemizedlist>
<para>Per default HttpClient uses the <classname>DefaultHostnameVerifier</classname>
implementation. One can specify a different hostname verifier implementation if
desired</para>
<programlisting><![CDATA[
SSLContext sslContext = SSLContexts.createSystemDefault();
SSLConnectionSocketFactory sslsf = new SSLConnectionSocketFactory(
sslContext,
NoopHostnameVerifier.INSTANCE);
]]></programlisting>
<para>As of version 4.4 HttpClient uses the public suffix list kindly maintained
by Mozilla Foundation to make sure that wildcards in SSL certificates cannot be
misused to apply to multiple domains with a common top-level domain. HttpClient
ships with a copy of the list retrieved at the time of the release. The latest
revision of the list can found at
<ulink url="https://publicsuffix.org/list/effective_tld_names.dat">
https://publicsuffix.org/list/</ulink>. It is highly adviseable to make a local
copy of the list and download the list no more than once per day from its original
location.
</para>
<programlisting><![CDATA[
PublicSuffixMatcher publicSuffixMatcher = PublicSuffixMatcherLoader.load(
PublicSuffixMatcher.class.getResource("my-copy-effective_tld_names.dat"));
DefaultHostnameVerifier hostnameVerifier = new DefaultHostnameVerifier(publicSuffixMatcher);
]]></programlisting>
<para>One can disable verification against the public suffic list by using
<code>null</code> matcher.
</para>
<programlisting><![CDATA[
DefaultHostnameVerifier hostnameVerifier = new DefaultHostnameVerifier(null);
]]></programlisting>
</section>
</section>
<section>
<title>HttpClient proxy configuration</title>
<para>Even though HttpClient is aware of complex routing schemes and proxy chaining, it
supports only simple direct or one hop proxy connections out of the box.</para>
<para>The simplest way to tell HttpClient to connect to the target host via a proxy is by
setting the default proxy parameter:</para>
<programlisting><![CDATA[
HttpHost proxy = new HttpHost("someproxy", 8080);
DefaultProxyRoutePlanner routePlanner = new DefaultProxyRoutePlanner(proxy);
CloseableHttpClient httpclient = HttpClients.custom()
.setRoutePlanner(routePlanner)
.build();
]]></programlisting>
<para>One can also instruct HttpClient to use the standard JRE proxy selector to obtain proxy
information:</para>
<programlisting><![CDATA[
SystemDefaultRoutePlanner routePlanner = new SystemDefaultRoutePlanner(
ProxySelector.getDefault());
CloseableHttpClient httpclient = HttpClients.custom()
.setRoutePlanner(routePlanner)
.build();
]]></programlisting>
<para>Alternatively, one can provide a custom <interfacename>RoutePlanner</interfacename>
implementation in order to have a complete control over the process of HTTP route
computation:</para>
<programlisting><![CDATA[
HttpRoutePlanner routePlanner = new HttpRoutePlanner() {
public HttpRoute determineRoute(
HttpHost target,
HttpRequest request,
HttpContext context) throws HttpException {
return new HttpRoute(target, null, new HttpHost("someproxy", 8080),
"https".equalsIgnoreCase(target.getName()));
}
};
CloseableHttpClient httpclient = HttpClients.custom()
.setRoutePlanner(routePlanner)
.build();
}
}
]]></programlisting>
</section>
</chapter>

131
src/docbkx/fluent.xml
View File

@ -1,131 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
====================================================================
-->
<chapter id="fluent">
<title>Fluent API</title>
<section>
<title>Easy to use facade API</title>
<para>
As of version of 4.2 HttpClient comes with an easy to use facade API based on the concept
of a fluent interface. Fluent facade API exposes only the most fundamental functions of
HttpClient and is intended for simple use cases that do not require the full flexibility of
HttpClient. For instance, fluent facade API relieves the users from having to deal with
connection management and resource deallocation.
</para>
<para>Here are several examples of HTTP requests executed through the HC fluent API</para>
<programlisting><![CDATA[
// Execute a GET with timeout settings and return response content as String.
Request.Get("http://somehost/")
.connectTimeout(1000)
.socketTimeout(1000)
.execute().returnContent().asString();
]]>
</programlisting>
<programlisting><![CDATA[
// Execute a POST with the 'expect-continue' handshake, using HTTP/1.1,
// containing a request body as String and return response content as byte array.
Request.Post("http://somehost/do-stuff")
.useExpectContinue()
.version(HttpVersion.HTTP_1_1)
.bodyString("Important stuff", ContentType.DEFAULT_TEXT)
.execute().returnContent().asBytes();
]]>
</programlisting>
<programlisting><![CDATA[
// Execute a POST with a custom header through the proxy containing a request body
// as an HTML form and save the result to the file
Request.Post("http://somehost/some-form")
.addHeader("X-Custom-header", "stuff")
.viaProxy(new HttpHost("myproxy", 8080))
.bodyForm(Form.form().add("username", "vip").add("password", "secret").build())
.execute().saveContent(new File("result.dump"));
]]>
</programlisting>
<para>One can also use <classname>Executor</classname> directly in order to execute requests in
a specific security context whereby authentication details are cached and re-used for
subsequent requests.
</para>
<programlisting><![CDATA[
Executor executor = Executor.newInstance()
.auth(new HttpHost("somehost"), "username", "password")
.auth(new HttpHost("myproxy", 8080), "username", "password")
.authPreemptive(new HttpHost("myproxy", 8080));
executor.execute(Request.Get("http://somehost/"))
.returnContent().asString();
executor.execute(Request.Post("http://somehost/do-stuff")
.useExpectContinue()
.bodyString("Important stuff", ContentType.DEFAULT_TEXT))
.returnContent().asString();
]]>
</programlisting>
<section>
<title>Response handling</title>
<para>The fluent facade API generally relieves the users from having to deal with
connection management and resource deallocation. In most cases, though, this comes at
a price of having to buffer content of response messages in memory. It is highly
recommended to use <interfacename>ResponseHandler</interfacename> for HTTP response
processing in order to avoid having to buffer content in memory.</para>
<programlisting><![CDATA[
Document result = Request.Get("http://somehost/content")
.execute().handleResponse(new ResponseHandler<Document>() {
public Document handleResponse(final HttpResponse response) throws IOException {
StatusLine statusLine = response.getStatusLine();
HttpEntity entity = response.getEntity();
if (statusLine.getStatusCode() >= 300) {
throw new HttpResponseException(
statusLine.getStatusCode(),
statusLine.getReasonPhrase());
}
if (entity == null) {
throw new ClientProtocolException("Response contains no content");
}
DocumentBuilderFactory dbfac = DocumentBuilderFactory.newInstance();
try {
DocumentBuilder docBuilder = dbfac.newDocumentBuilder();
ContentType contentType = ContentType.getOrDefault(entity);
if (!contentType.equals(ContentType.APPLICATION_XML)) {
throw new ClientProtocolException("Unexpected content type:" +
contentType);
}
String charset = contentType.getCharset();
if (charset == null) {
charset = HTTP.DEFAULT_CONTENT_CHARSET;
}
return docBuilder.parse(entity.getContent(), charset);
} catch (ParserConfigurationException ex) {
throw new IllegalStateException(ex);
} catch (SAXException ex) {
throw new ClientProtocolException("Malformed XML document", ex);
}
}
});
]]>
</programlisting>
</section>
</section>
</chapter>

892
src/docbkx/fundamentals.xml
View File

@ -1,892 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
====================================================================
-->
<chapter id="fundamentals">
<title>Fundamentals</title>
<section>
<title>Request execution</title>
<para> The most essential function of HttpClient is to execute HTTP methods. Execution of an
HTTP method involves one or several HTTP request / HTTP response exchanges, usually
handled internally by HttpClient. The user is expected to provide a request object to
execute and HttpClient is expected to transmit the request to the target server return a
corresponding response object, or throw an exception if execution was unsuccessful. </para>
<para> Quite naturally, the main entry point of the HttpClient API is the HttpClient
interface that defines the contract described above. </para>
<para>Here is an example of request execution process in its simplest form:</para>
<programlisting><![CDATA[
CloseableHttpClient httpclient = HttpClients.createDefault();
HttpGet httpget = new HttpGet("http://localhost/");
CloseableHttpResponse response = httpclient.execute(httpget);
try {
<...>
} finally {
response.close();
}
]]></programlisting>
<section>
<title>HTTP request</title>
<para>All HTTP requests have a request line consisting a method name, a request URI and
an HTTP protocol version.</para>
<para>HttpClient supports out of the box all HTTP methods defined in the HTTP/1.1
specification: <literal>GET</literal>, <literal>HEAD</literal>,
<literal>POST</literal>, <literal>PUT</literal>, <literal>DELETE</literal>,
<literal>TRACE</literal> and <literal>OPTIONS</literal>. There is a specific
class for each method type.: <classname>HttpGet</classname>,
<classname>HttpHead</classname>, <classname>HttpPost</classname>,
<classname>HttpPut</classname>, <classname>HttpDelete</classname>,
<classname>HttpTrace</classname>, and <classname>HttpOptions</classname>.</para>
<para>The Request-URI is a Uniform Resource Identifier that identifies the resource upon
which to apply the request. HTTP request URIs consist of a protocol scheme, host
name, optional port, resource path, optional query, and optional fragment.</para>
<programlisting><![CDATA[
HttpGet httpget = new HttpGet(
"http://www.google.com/search?hl=en&q=httpclient&btnG=Google+Search&aq=f&oq=");
]]></programlisting>
<para>HttpClient provides <classname>URIBuilder</classname> utility class to simplify
creation and modification of request URIs.</para>
<programlisting><![CDATA[
URI uri = new URIBuilder()
.setScheme("http")
.setHost("www.google.com")
.setPath("/search")
.setParameter("q", "httpclient")
.setParameter("btnG", "Google Search")
.setParameter("aq", "f")
.setParameter("oq", "")
.build();
HttpGet httpget = new HttpGet(uri);
System.out.println(httpget.getURI());
]]></programlisting>
<para>stdout &gt;</para>
<programlisting><![CDATA[
http://www.google.com/search?q=httpclient&btnG=Google+Search&aq=f&oq=
]]></programlisting>
</section>
<section>
<title>HTTP response</title>
<para>HTTP response is a message sent by the server back to the client after having
received and interpreted a request message. The first line of that message consists
of the protocol version followed by a numeric status code and its associated textual
phrase.</para>
<programlisting><![CDATA[
HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1_1,
HttpStatus.SC_OK, "OK");
System.out.println(response.getProtocolVersion());
System.out.println(response.getStatusLine().getStatusCode());
System.out.println(response.getStatusLine().getReasonPhrase());
System.out.println(response.getStatusLine().toString());
]]></programlisting>
<para>stdout &gt;</para>
<programlisting><![CDATA[
HTTP/1.1
200
OK
HTTP/1.1 200 OK
]]></programlisting>
</section>
<section>
<title>Working with message headers</title>
<para>An HTTP message can contain a number of headers describing properties of the
message such as the content length, content type and so on. HttpClient provides
methods to retrieve, add, remove and enumerate headers.</para>
<programlisting><![CDATA[
HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1_1,
HttpStatus.SC_OK, "OK");
response.addHeader("Set-Cookie",
"c1=a; path=/; domain=localhost");
response.addHeader("Set-Cookie",
"c2=b; path=\"/\", c3=c; domain=\"localhost\"");
Header h1 = response.getFirstHeader("Set-Cookie");
System.out.println(h1);
Header h2 = response.getLastHeader("Set-Cookie");
System.out.println(h2);
Header[] hs = response.getHeaders("Set-Cookie");
System.out.println(hs.length);
]]></programlisting>
<para>stdout &gt;</para>
<programlisting><![CDATA[
Set-Cookie: c1=a; path=/; domain=localhost
Set-Cookie: c2=b; path="/", c3=c; domain="localhost"
2
]]></programlisting>
<para>The most efficient way to obtain all headers of a given type is by using the
<interfacename>HeaderIterator</interfacename> interface.</para>
<programlisting><![CDATA[
HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1_1,
HttpStatus.SC_OK, "OK");
response.addHeader("Set-Cookie",
"c1=a; path=/; domain=localhost");
response.addHeader("Set-Cookie",
"c2=b; path=\"/\", c3=c; domain=\"localhost\"");
HeaderIterator it = response.headerIterator("Set-Cookie");
while (it.hasNext()) {
System.out.println(it.next());
}
]]></programlisting>
<para>stdout &gt;</para>
<programlisting><![CDATA[
Set-Cookie: c1=a; path=/; domain=localhost
Set-Cookie: c2=b; path="/", c3=c; domain="localhost"
]]></programlisting>
<para>It also provides convenience methods to parse HTTP messages into individual header
elements.</para>
<programlisting><![CDATA[
HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1_1,
HttpStatus.SC_OK, "OK");
response.addHeader("Set-Cookie",
"c1=a; path=/; domain=localhost");
response.addHeader("Set-Cookie",
"c2=b; path=\"/\", c3=c; domain=\"localhost\"");
HeaderElementIterator it = new BasicHeaderElementIterator(
response.headerIterator("Set-Cookie"));
while (it.hasNext()) {
HeaderElement elem = it.nextElement();
System.out.println(elem.getName() + " = " + elem.getValue());
NameValuePair[] params = elem.getParameters();
for (int i = 0; i < params.length; i++) {
System.out.println(" " + params[i]);
}
}
]]></programlisting>
<para>stdout &gt;</para>
<programlisting><![CDATA[
c1 = a
path=/
domain=localhost
c2 = b
path=/
c3 = c
domain=localhost
]]></programlisting>
</section>
<section>
<title>HTTP entity</title>
<para>HTTP messages can carry a content entity associated with the request or response.
Entities can be found in some requests and in some responses, as they are optional.
Requests that use entities are referred to as entity enclosing requests. The HTTP
specification defines two entity enclosing request methods: <literal>POST</literal> and
<literal>PUT</literal>. Responses are usually expected to enclose a content
entity. There are exceptions to this rule such as responses to
<literal>HEAD</literal> method and <literal>204 No Content</literal>,
<literal>304 Not Modified</literal>, <literal>205 Reset Content</literal>
responses.</para>
<para>HttpClient distinguishes three kinds of entities, depending on where their content
originates:</para>
<itemizedlist>
<listitem>
<formalpara>
<title>streamed:</title>
<para>The content is received from a stream, or generated on the fly. In
particular, this category includes entities being received from HTTP
responses. Streamed entities are generally not repeatable.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>self-contained:</title>
<para>The content is in memory or obtained by means that are independent
from a connection or other entity. Self-contained entities are generally
repeatable. This type of entities will be mostly used for entity
enclosing HTTP requests.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>wrapping:</title>
<para>The content is obtained from another entity.</para>
</formalpara>
</listitem>
</itemizedlist>
<para>This distinction is important for connection management when streaming out content
from an HTTP response. For request entities that are created by an application and
only sent using HttpClient, the difference between streamed and self-contained is of
little importance. In that case, it is suggested to consider non-repeatable entities
as streamed, and those that are repeatable as self-contained.</para>
<section>
<title>Repeatable entities</title>
<para>An entity can be repeatable, meaning its content can be read more than once.
This is only possible with self contained entities (like
<classname>ByteArrayEntity</classname> or
<classname>StringEntity</classname>)</para>
</section>
<section>
<title>Using HTTP entities</title>
<para>Since an entity can represent both binary and character content, it has
support for character encodings (to support the latter, ie. character
content).</para>
<para>The entity is created when executing a request with enclosed content or when
the request was successful and the response body is used to send the result back
to the client.</para>
<para>To read the content from the entity, one can either retrieve the input stream
via the <methodname>HttpEntity#getContent()</methodname> method, which returns
an <classname>java.io.InputStream</classname>, or one can supply an output
stream to the <methodname>HttpEntity#writeTo(OutputStream)</methodname> method,
which will return once all content has been written to the given stream.</para>
<para>When the entity has been received with an incoming message, the methods
<methodname>HttpEntity#getContentType()</methodname> and
<methodname>HttpEntity#getContentLength()</methodname> methods can be used
for reading the common metadata such as <literal>Content-Type</literal> and
<literal>Content-Length</literal> headers (if they are available). Since the
<literal>Content-Type</literal> header can contain a character encoding for
text mime-types like text/plain or text/html, the
<methodname>HttpEntity#getContentEncoding()</methodname> method is used to
read this information. If the headers aren't available, a length of -1 will be
returned, and NULL for the content type. If the <literal>Content-Type</literal>
header is available, a <interfacename>Header</interfacename> object will be
returned.</para>
<para>When creating an entity for a outgoing message, this meta data has to be
supplied by the creator of the entity.</para>
<programlisting><![CDATA[
StringEntity myEntity = new StringEntity("important message",
ContentType.create("text/plain", "UTF-8"));
System.out.println(myEntity.getContentType());
System.out.println(myEntity.getContentLength());
System.out.println(EntityUtils.toString(myEntity));
System.out.println(EntityUtils.toByteArray(myEntity).length);]]></programlisting>
<para>stdout &gt;</para>
<programlisting><![CDATA[
Content-Type: text/plain; charset=utf-8
17
important message
17
]]></programlisting>
</section>
</section>
<section>
<title>Ensuring release of low level resources</title>
<para> In order to ensure proper release of system resources one must close either
the content stream associated with the entity or the response itself</para>
<programlisting><![CDATA[
CloseableHttpClient httpclient = HttpClients.createDefault();
HttpGet httpget = new HttpGet("http://localhost/");
CloseableHttpResponse response = httpclient.execute(httpget);
try {
HttpEntity entity = response.getEntity();
if (entity != null) {
InputStream instream = entity.getContent();
try {
// do something useful
} finally {
instream.close();
}
}
} finally {
response.close();
}
]]></programlisting>
<para>The difference between closing the content stream and closing the response
is that the former will attempt to keep the underlying connection alive
by consuming the entity content while the latter immediately shuts down
and discards the connection.</para>
<para>Please note that the <methodname>HttpEntity#writeTo(OutputStream)</methodname>
method is also required to ensure proper release of system resources once the
entity has been fully written out. If this method obtains an instance of
<classname>java.io.InputStream</classname> by calling
<methodname>HttpEntity#getContent()</methodname>, it is also expected to close
the stream in a finally clause.</para>
<para>When working with streaming entities, one can use the
<methodname>EntityUtils#consume(HttpEntity)</methodname> method to ensure that
the entity content has been fully consumed and the underlying stream has been
closed.</para>
<para>There can be situations, however, when only a small portion of the entire response
content needs to be retrieved and the performance penalty for consuming the
remaining content and making the connection reusable is too high, in which case
one can terminate the content stream by closing the response.</para>
<programlisting><![CDATA[
CloseableHttpClient httpclient = HttpClients.createDefault();
HttpGet httpget = new HttpGet("http://localhost/");
CloseableHttpResponse response = httpclient.execute(httpget);
try {
HttpEntity entity = response.getEntity();
if (entity != null) {
InputStream instream = entity.getContent();
int byteOne = instream.read();
int byteTwo = instream.read();
// Do not need the rest
}
} finally {
response.close();
}
]]></programlisting>
<para>The connection will not be reused, but all level resources held by it will be
correctly deallocated.</para>
</section>
<section>
<title>Consuming entity content</title>
<para>The recommended way to consume the content of an entity is by using its
<methodname>HttpEntity#getContent()</methodname> or
<methodname>HttpEntity#writeTo(OutputStream)</methodname> methods. HttpClient
also comes with the <classname>EntityUtils</classname> class, which exposes several
static methods to more easily read the content or information from an entity.
Instead of reading the <classname>java.io.InputStream</classname> directly, one can
retrieve the whole content body in a string / byte array by using the methods from
this class. However, the use of <classname>EntityUtils</classname> is
strongly discouraged unless the response entities originate from a trusted HTTP
server and are known to be of limited length.</para>
<programlisting><![CDATA[
CloseableHttpClient httpclient = HttpClients.createDefault();
HttpGet httpget = new HttpGet("http://localhost/");
CloseableHttpResponse response = httpclient.execute(httpget);
try {
HttpEntity entity = response.getEntity();
if (entity != null) {
long len = entity.getContentLength();
if (len != -1 && len < 2048) {
System.out.println(EntityUtils.toString(entity));
} else {
// Stream content out
}
}
} finally {
response.close();
}
]]></programlisting>
<para>In some situations it may be necessary to be able to read entity content more than
once. In this case entity content must be buffered in some way, either in memory or
on disk. The simplest way to accomplish that is by wrapping the original entity with
the <classname>BufferedHttpEntity</classname> class. This will cause the content of
the original entity to be read into a in-memory buffer. In all other ways the entity
wrapper will be have the original one.</para>
<programlisting><![CDATA[
CloseableHttpResponse response = <...>
HttpEntity entity = response.getEntity();
if (entity != null) {
entity = new BufferedHttpEntity(entity);
}
]]></programlisting>
</section>
<section>
<title>Producing entity content</title>
<para>HttpClient provides several classes that can be used to efficiently stream out
content throught HTTP connections. Instances of those classes can be associated with
entity enclosing requests such as <literal>POST</literal> and <literal>PUT</literal>
in order to enclose entity content into outgoing HTTP requests. HttpClient provides
several classes for most common data containers such as string, byte array, input
stream, and file: <classname>StringEntity</classname>,
<classname>ByteArrayEntity</classname>,
<classname>InputStreamEntity</classname>, and
<classname>FileEntity</classname>.</para>
<programlisting><![CDATA[
File file = new File("somefile.txt");
FileEntity entity = new FileEntity(file,
ContentType.create("text/plain", "UTF-8"));
HttpPost httppost = new HttpPost("http://localhost/action.do");
httppost.setEntity(entity);
]]></programlisting>
<para>Please note <classname>InputStreamEntity</classname> is not repeatable, because it
can only read from the underlying data stream once. Generally it is recommended to
implement a custom <interfacename>HttpEntity</interfacename> class which is
self-contained instead of using the generic <classname>InputStreamEntity</classname>.
<classname>FileEntity</classname> can be a good starting point.</para>
<section>
<title>HTML forms</title>
<para>Many applications need to simulate the process of submitting an
HTML form, for instance, in order to log in to a web application or submit input
data. HttpClient provides the entity class
<classname>UrlEncodedFormEntity</classname> to facilitate the
process.</para>
<programlisting><![CDATA[
List<NameValuePair> formparams = new ArrayList<NameValuePair>();
formparams.add(new BasicNameValuePair("param1", "value1"));
formparams.add(new BasicNameValuePair("param2", "value2"));
UrlEncodedFormEntity entity = new UrlEncodedFormEntity(formparams, Consts.UTF_8);
HttpPost httppost = new HttpPost("http://localhost/handler.do");
httppost.setEntity(entity);
]]></programlisting>
<para>The <classname>UrlEncodedFormEntity</classname> instance will use the so
called URL encoding to encode parameters and produce the following
content:</para>
<programlisting><![CDATA[
param1=value1&param2=value2
]]></programlisting>
</section>
<section>
<title>Content chunking</title>
<para>Generally it is recommended to let HttpClient choose the most appropriate
transfer encoding based on the properties of the HTTP message being transferred.
It is possible, however, to inform HttpClient that chunk coding is preferred
by setting <methodname>HttpEntity#setChunked()</methodname> to true. Please note
that HttpClient will use this flag as a hint only. This value will be ignored
when using HTTP protocol versions that do not support chunk coding, such as
HTTP/1.0.</para>
<programlisting><![CDATA[
StringEntity entity = new StringEntity("important message",
ContentType.create("plain/text", Consts.UTF_8));
entity.setChunked(true);
HttpPost httppost = new HttpPost("http://localhost/acrtion.do");
httppost.setEntity(entity);
]]></programlisting>
</section>
</section>
<section>
<title>Response handlers</title>
<para>The simplest and the most convenient way to handle responses is by using
the <interfacename>ResponseHandler</interfacename> interface, which includes
the <methodname>handleResponse(HttpResponse response)</methodname> method.
This method completely
relieves the user from having to worry about connection management. When using a
<interfacename>ResponseHandler</interfacename>, HttpClient will automatically
take care of ensuring release of the connection back to the connection manager
regardless whether the request execution succeeds or causes an exception.</para>
<programlisting><![CDATA[
CloseableHttpClient httpclient = HttpClients.createDefault();
HttpGet httpget = new HttpGet("http://localhost/json");
ResponseHandler<MyJsonObject> rh = new ResponseHandler<MyJsonObject>() {
@Override
public JsonObject handleResponse(
final HttpResponse response) throws IOException {
StatusLine statusLine = response.getStatusLine();
HttpEntity entity = response.getEntity();
if (statusLine.getStatusCode() >= 300) {
throw new HttpResponseException(
statusLine.getStatusCode(),
statusLine.getReasonPhrase());
}
if (entity == null) {
throw new ClientProtocolException("Response contains no content");
}
Gson gson = new GsonBuilder().create();
ContentType contentType = ContentType.getOrDefault(entity);
Charset charset = contentType.getCharset();
Reader reader = new InputStreamReader(entity.getContent(), charset);
return gson.fromJson(reader, MyJsonObject.class);
}
};
MyJsonObject myjson = client.execute(httpget, rh);
]]></programlisting>
</section>
</section>
<section>
<title>HttpClient interface</title>
<para><interfacename>HttpClient</interfacename> interface represents the most essential
contract for HTTP request execution. It imposes no restrictions or particular details on
the request execution process and leaves the specifics of connection management, state
management, authentication and redirect handling up to individual implementations. This
should make it easier to decorate the interface with additional functionality such as
response content caching.</para>
<para>Generally <interfacename>HttpClient</interfacename> implementations act as a facade
to a number of special purpose handler or strategy interface implementations
responsible for handling of a particular aspect of the HTTP protocol such as redirect
or authentication handling or making decision about connection persistence and keep
alive duration. This enables the users to selectively replace default implementation
of those aspects with custom, application specific ones.</para>
<programlisting><![CDATA[
ConnectionKeepAliveStrategy keepAliveStrat = new DefaultConnectionKeepAliveStrategy() {
@Override
public long getKeepAliveDuration(
HttpResponse response,
HttpContext context) {
long keepAlive = super.getKeepAliveDuration(response, context);
if (keepAlive == -1) {
// Keep connections alive 5 seconds if a keep-alive value
// has not be explicitly set by the server
keepAlive = 5000;
}
return keepAlive;
}
};
CloseableHttpClient httpclient = HttpClients.custom()
.setKeepAliveStrategy(keepAliveStrat)
.build();
]]></programlisting>
<section>
<title>HttpClient thread safety</title>
<para><interfacename>HttpClient</interfacename> implementations are expected to be
thread safe. It is recommended that the same instance of this class is reused for
multiple request executions.</para>
</section>
<section>
<title>HttpClient resource deallocation</title>
<para>When an instance <classname>CloseableHttpClient</classname> is no longer needed
and is about to go out of scope the connection manager associated with it must
be shut down by calling the <methodname>CloseableHttpClient#close()</methodname>
method.</para>
<programlisting><![CDATA[
CloseableHttpClient httpclient = HttpClients.createDefault();
try {
<...>
} finally {
httpclient.close();
}
]]></programlisting>
</section>
</section>
<section>
<title>HTTP execution context</title>
<para>Originally HTTP has been designed as a stateless, response-request oriented protocol.
However, real world applications often need to be able to persist state information
through several logically related request-response exchanges. In order to enable
applications to maintain a processing state HttpClient allows HTTP requests to be
executed within a particular execution context, referred to as HTTP context. Multiple
logically related requests can participate in a logical session if the same context is
reused between consecutive requests. HTTP context functions similarly to
a <interfacename>java.util.Map&lt;String, Object&gt;</interfacename>. It is
simply a collection of arbitrary named values. An application can populate context
attributes prior to request execution or examine the context after the execution has
been completed.</para>
<para><interfacename>HttpContext</interfacename> can contain arbitrary objects and
therefore may be unsafe to share between multiple threads. It is recommended that
each thread of execution maintains its own context.</para>
<para>In the course of HTTP request execution HttpClient adds the following attributes to
the execution context:</para>
<itemizedlist>
<listitem>
<formalpara>
<para><interfacename>HttpConnection</interfacename> instance representing the
actual connection to the target server.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<para><classname>HttpHost</classname> instance representing the connection
target.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<para><classname>HttpRoute</classname> instance representing the complete
connection route</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<para><interfacename>HttpRequest</interfacename> instance representing the
actual HTTP request. The final HttpRequest object in the execution context
always represents the state of the message <emphasis>exactly</emphasis>
as it was sent to the target server. Per default HTTP/1.0 and HTTP/1.1
use relative request URIs. However if the request is sent via a proxy
in a non-tunneling mode then the URI will be absolute.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<para><interfacename>HttpResponse</interfacename> instance representing the
actual HTTP response.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<para><classname>java.lang.Boolean</classname> object representing the flag
indicating whether the actual request has been fully transmitted to the
connection target.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<para><classname>RequestConfig</classname> object representing the actual
request configuation.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<para><classname>java.util.List&lt;URI&gt;</classname> object representing a collection
of all redirect locations received in the process of request
execution.</para>
</formalpara>
</listitem>
</itemizedlist>
<para>One can use <classname>HttpClientContext</classname> adaptor class to simplify
interractions with the context state.</para>
<programlisting><![CDATA[
HttpContext context = <...>
HttpClientContext clientContext = HttpClientContext.adapt(context);
HttpHost target = clientContext.getTargetHost();
HttpRequest request = clientContext.getRequest();
HttpResponse response = clientContext.getResponse();
RequestConfig config = clientContext.getRequestConfig();
]]></programlisting>
<para>Multiple request sequences that represent a logically related session should be
executed with the same <interfacename>HttpContext</interfacename> instance to ensure
automatic propagation of conversation context and state information between
requests.</para>
<para>In the following example the request configuration set by the initial request will be
kept in the execution context and get propagated to the consecutive requests sharing
the same context.</para>
<programlisting><![CDATA[
CloseableHttpClient httpclient = HttpClients.createDefault();
RequestConfig requestConfig = RequestConfig.custom()
.setSocketTimeout(1000)
.setConnectTimeout(1000)
.build();
HttpGet httpget1 = new HttpGet("http://localhost/1");
httpget1.setConfig(requestConfig);
CloseableHttpResponse response1 = httpclient.execute(httpget1, context);
try {
HttpEntity entity1 = response1.getEntity();
} finally {
response1.close();
}
HttpGet httpget2 = new HttpGet("http://localhost/2");
CloseableHttpResponse response2 = httpclient.execute(httpget2, context);
try {
HttpEntity entity2 = response2.getEntity();
} finally {
response2.close();
}
]]></programlisting>
</section>
<section id="protocol_interceptors">
<title>HTTP protocol interceptors</title>
<para>The HTTP protocol interceptor is a routine that implements a specific aspect of the HTTP
protocol. Usually protocol interceptors are expected to act upon one specific header or
a group of related headers of the incoming message, or populate the outgoing message with
one specific header or a group of related headers. Protocol interceptors can also
manipulate content entities enclosed with messages - transparent content compression /
decompression being a good example. Usually this is accomplished by using the
'Decorator' pattern where a wrapper entity class is used to decorate the original
entity. Several protocol interceptors can be combined to form one logical unit.</para>
<para>Protocol interceptors can collaborate by sharing information - such as a processing
state - through the HTTP execution context. Protocol interceptors can use HTTP context
to store a processing state for one request or several consecutive requests.</para>
<para>Usually the order in which interceptors are executed should not matter as long as they
do not depend on a particular state of the execution context. If protocol interceptors
have interdependencies and therefore must be executed in a particular order, they should
be added to the protocol processor in the same sequence as their expected execution
order.</para>
<para>Protocol interceptors must be implemented as thread-safe. Similarly to servlets,
protocol interceptors should not use instance variables unless access to those variables
is synchronized.</para>
<para>This is an example of how local context can be used to persist a processing state
between consecutive requests:</para>
<programlisting><![CDATA[
CloseableHttpClient httpclient = HttpClients.custom()
.addInterceptorLast(new HttpRequestInterceptor() {
public void process(
final HttpRequest request,
final HttpContext context) throws HttpException, IOException {
AtomicInteger count = (AtomicInteger) context.getAttribute("count");
request.addHeader("Count", Integer.toString(count.getAndIncrement()));
}
})
.build();
AtomicInteger count = new AtomicInteger(1);
HttpClientContext localContext = HttpClientContext.create();
localContext.setAttribute("count", count);
HttpGet httpget = new HttpGet("http://localhost/");
for (int i = 0; i < 10; i++) {
CloseableHttpResponse response = httpclient.execute(httpget, localContext);
try {
HttpEntity entity = response.getEntity();
} finally {
response.close();
}
}
]]></programlisting>
</section>
<section>
<title>Exception handling</title>
<para>HTTP protocol processors can throw two types of exceptions:
<exceptionname>java.io.IOException</exceptionname> in case of an I/O failure such as
socket timeout or an socket reset and <exceptionname>HttpException</exceptionname> that
signals an HTTP failure such as a violation of the HTTP protocol. Usually I/O errors are
considered non-fatal and recoverable, whereas HTTP protocol errors are considered fatal
and cannot be automatically recovered from. Please note that <interfacename>HttpClient
</interfacename> implementations re-throw <exceptionname>HttpException</exceptionname>s
as <exceptionname>ClientProtocolException</exceptionname>, which is a subclass
of <exceptionname>java.io.IOException</exceptionname>. This enables the users
of <interfacename>HttpClient</interfacename> to handle both I/O errors and protocol
violations from a single catch clause.</para>
<section>
<title>HTTP transport safety</title>
<para>It is important to understand that the HTTP protocol is not well suited to all
types of applications. HTTP is a simple request/response oriented protocol which was
initially designed to support static or dynamically generated content retrieval. It
has never been intended to support transactional operations. For instance, the HTTP
server will consider its part of the contract fulfilled if it succeeds in receiving
and processing the request, generating a response and sending a status code back to
the client. The server will make no attempt to roll back the transaction if the
client fails to receive the response in its entirety due to a read timeout, a
request cancellation or a system crash. If the client decides to retry the same
request, the server will inevitably end up executing the same transaction more than
once. In some cases this may lead to application data corruption or inconsistent
application state.</para>
<para>Even though HTTP has never been designed to support transactional processing, it
can still be used as a transport protocol for mission critical applications provided
certain conditions are met. To ensure HTTP transport layer safety the system must
ensure the idempotency of HTTP methods on the application layer.</para>
</section>
<section>
<title>Idempotent methods</title>
<para>HTTP/1.1 specification defines an idempotent method as</para>
<para>
<citation>Methods can also have the property of &quot;idempotence&quot; in
that (aside from error or expiration issues) the side-effects of N &gt; 0
identical requests is the same as for a single request</citation>
</para>
<para>In other words the application ought to ensure that it is prepared to deal with
the implications of multiple execution of the same method. This can be achieved, for
instance, by providing a unique transaction id and by other means of avoiding
execution of the same logical operation.</para>
<para>Please note that this problem is not specific to HttpClient. Browser based
applications are subject to exactly the same issues related to HTTP methods
non-idempotency.</para>
<para>By default HttpClient assumes only non-entity enclosing methods such as
<literal>GET</literal> and <literal>HEAD</literal> to be idempotent and entity
enclosing methods such as <literal>POST</literal> and <literal>PUT</literal> to be
not for compatibility reasons.</para>
</section>
<section>
<title>Automatic exception recovery</title>
<para>By default HttpClient attempts to automatically recover from I/O exceptions. The
default auto-recovery mechanism is limited to just a few exceptions that are known
to be safe.</para>
<itemizedlist>
<listitem>
<para>HttpClient will make no attempt to recover from any logical or HTTP
protocol errors (those derived from
<exceptionname>HttpException</exceptionname> class).</para>
</listitem>
<listitem>
<para>HttpClient will automatically retry those methods that are assumed to be
idempotent.</para>
</listitem>
<listitem>
<para>HttpClient will automatically retry those methods that fail with a
transport exception while the HTTP request is still being transmitted to the
target server (i.e. the request has not been fully transmitted to the
server).</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Request retry handler</title>
<para>In order to enable a custom exception recovery mechanism one should provide an
implementation of the <interfacename>HttpRequestRetryHandler</interfacename>
interface.</para>
<programlisting><![CDATA[
HttpRequestRetryHandler myRetryHandler = new HttpRequestRetryHandler() {
public boolean retryRequest(
IOException exception,
int executionCount,
HttpContext context) {
if (executionCount >= 5) {
// Do not retry if over max retry count
return false;
}
if (exception instanceof InterruptedIOException) {
// Timeout
return false;
}
if (exception instanceof UnknownHostException) {
// Unknown host
return false;
}
if (exception instanceof ConnectTimeoutException) {
// Connection refused
return false;
}
if (exception instanceof SSLException) {
// SSL handshake exception
return false;
}
HttpClientContext clientContext = HttpClientContext.adapt(context);
HttpRequest request = clientContext.getRequest();
boolean idempotent = !(request instanceof HttpEntityEnclosingRequest);
if (idempotent) {
// Retry if the request is considered idempotent
return true;
}
return false;
}
};
CloseableHttpClient httpclient = HttpClients.custom()
.setRetryHandler(myRetryHandler)
.build();
]]></programlisting>
<para>Please note that one can use <classname>StandardHttpRequestRetryHandler</classname>
instead of the one used by default in order to treat those request methods defined
as idempotent by RFC-2616 as safe to retry automatically: <literal>GET</literal>,
<literal>HEAD</literal>, <literal>PUT</literal>, <literal>DELETE</literal>, <literal>
OPTIONS</literal>, and <literal>TRACE</literal>.</para>
</section>
</section>
<section>
<title>Aborting requests</title>
<para>In some situations HTTP request execution fails to complete within the expected time
frame due to high load on the target server or too many concurrent requests issued on
the client side. In such cases it may be necessary to terminate the request prematurely
and unblock the execution thread blocked in a I/O operation. HTTP requests being
executed by HttpClient can be aborted at any stage of execution by invoking
<methodname>HttpUriRequest#abort()</methodname> method. This method is thread-safe
and can be called from any thread. When an HTTP request is aborted its execution thread
- even if currently blocked in an I/O operation - is guaranteed to unblock by throwing a
<exceptionname>InterruptedIOException</exceptionname></para>
</section>
<section>
<title>Redirect handling</title>
<para>HttpClient handles all types of redirects automatically, except those explicitly
prohibited by the HTTP specification as requiring user intervention. <literal>See
Other</literal> (status code 303) redirects on <literal>POST</literal> and
<literal>PUT</literal> requests are converted to <literal>GET</literal> requests as
required by the HTTP specification. One can use a custom redirect strategy to relaxe
restrictions on automatic redirection of POST methods imposed by the HTTP
specification.</para>
<programlisting><![CDATA[
LaxRedirectStrategy redirectStrategy = new LaxRedirectStrategy();
CloseableHttpClient httpclient = HttpClients.custom()
.setRedirectStrategy(redirectStrategy)
.build();
]]></programlisting>
<para>HttpClient often has to rewrite the request message in the process of its execution.
Per default HTTP/1.0 and HTTP/1.1 generally use relative request URIs. Likewise,
original request may get redirected from location to another multiple times. The final
interpreted absolute HTTP location can be built using the original request and
the context. The utility method <classname>URIUtils#resolve</classname> can be used
to build the interpreted absolute URI used to generate the final request. This method
includes the last fragment identifier from the redirect requests or the original
request.</para>
<programlisting><![CDATA[
CloseableHttpClient httpclient = HttpClients.createDefault();
HttpClientContext context = HttpClientContext.create();
HttpGet httpget = new HttpGet("http://localhost:8080/");
CloseableHttpResponse response = httpclient.execute(httpget, context);
try {
HttpHost target = context.getTargetHost();
List<URI> redirectLocations = context.getRedirectLocations();
URI location = URIUtils.resolve(httpget.getURI(), target, redirectLocations);
System.out.println("Final HTTP location: " + location.toASCIIString());
// Expected to be an absolute URI
} finally {
response.close();
}
]]></programlisting>
</section>
</chapter>

80
src/docbkx/index.xml
View File

@ -1,80 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
====================================================================
-->
<book xmlns:xi="http://www.w3.org/2001/XInclude">
<bookinfo>
<title>HttpClient Tutorial</title>
<releaseinfo>&version;</releaseinfo>
<authorgroup>
<author>
<firstname>Oleg</firstname>
<surname>Kalnichevski</surname>
</author>
<author>
<firstname>Jonathan</firstname>
<surname>Moore</surname>
</author>
<author>
<firstname>Jilles</firstname>
<surname>van Gurp</surname>
</author>
</authorgroup>
<legalnotice>
<formalpara>
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
</formalpara>
<formalpara>
<ulink url="http://www.apache.org/licenses/LICENSE-2.0"/>
</formalpara>
<formalpara>
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
</formalpara>
</legalnotice>
</bookinfo>
<toc/>
<xi:include href="preface.xml"/>
<xi:include href="fundamentals.xml"/>
<xi:include href="connmgmt.xml"/>
<xi:include href="statemgmt.xml"/>
<xi:include href="authentication.xml"/>
<xi:include href="fluent.xml"/>
<xi:include href="caching.xml"/>
<xi:include href="advanced.xml"/>
</book>

81
src/docbkx/preface.xml
View File

@ -1,81 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
====================================================================
-->
<preface id="preface">
<title>Preface</title>
<para>
The Hyper-Text Transfer Protocol (HTTP) is perhaps the most significant protocol used on the
Internet today. Web services, network-enabled appliances and the growth of network computing
continue to expand the role of the HTTP protocol beyond user-driven web browsers, while
increasing the number of applications that require HTTP support.
</para>
<para>
Although the java.net package provides basic functionality for accessing resources via HTTP,
it doesn't provide the full flexibility or functionality needed by many applications.
HttpClient seeks to fill this void by providing an efficient, up-to-date, and feature-rich
package implementing the client side of the most recent HTTP standards and recommendations.
</para>
<para>
Designed for extension while providing robust support for the base HTTP protocol, HttpClient
may be of interest to anyone building HTTP-aware client applications such as web browsers, web
service clients, or systems that leverage or extend the HTTP protocol for distributed
communication.
</para>
<section>
<title>HttpClient scope</title>
<itemizedlist>
<listitem>
<para>
Client-side HTTP transport library based on <ulink
url="http://hc.apache.org/httpcomponents-core/index.html">HttpCore</ulink>
</para>
</listitem>
<listitem>
<para>
Based on classic (blocking) I/O
</para>
</listitem>
<listitem>
<para>
Content agnostic
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>What HttpClient is NOT</title>
<itemizedlist>
<listitem>
<para>
HttpClient is NOT a browser. It is a client side HTTP transport library.
HttpClient's purpose is to transmit and receive HTTP messages. HttpClient will not
attempt to process content, execute javascript embedded in HTML pages, try to guess
content type, if not explicitly set, or reformat request / rewrite location URIs,
or other functionality unrelated to the HTTP transport.
</para>
</listitem>
</itemizedlist>
</section>
</preface>

309
src/docbkx/resources/css/hc-tutorial.css
View File

@ -1,309 +0,0 @@
/*
====================================================================
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
====================================================================
This software consists of voluntary contributions made by many
individuals on behalf of the Apache Software Foundation. For more
information on the Apache Software Foundation, please see
<http://www.apache.org/>.
====================================================================
Based on the CSS file for the Spring Reference Documentation.
*/
body {
text-align: justify;
margin-right: 2em;
margin-left: 2em;
}
a:active {
color: #003399;
}
a:visited {
color: #888888;
}
p {
font-family: Verdana, Arial, sans-serif;
}
dt {
font-family: Verdana, Arial, sans-serif;
font-size: 12px;
}
p, dl, dt, dd, blockquote {
color: #000000;
margin-bottom: 3px;
margin-top: 3px;
padding-top: 0px;
}
ol, ul, p {
margin-top: 6px;
margin-bottom: 6px;
}
p, blockquote {
font-size: 90%;
}
p.releaseinfo {
font-size: 100%;
font-weight: bold;
font-family: Verdana, Arial, helvetica, sans-serif;
padding-top: 10px;
}
p.pubdate {
font-size: 120%;
font-weight: bold;
font-family: Verdana, Arial, helvetica, sans-serif;
}
td {
font-size: 80%;
}
td, th, span {
color: #000000;
}
blockquote {
margin-right: 0px;
}
h1, h2, h3, h4, h6, H6 {
color: #000000;
font-weight: 500;
margin-top: 0px;
padding-top: 14px;
font-family: Verdana, Arial, helvetica, sans-serif;
margin-bottom: 0px;
}
h2.title {
font-weight: 800;
margin-bottom: 8px;
}
h2.subtitle {
font-weight: 800;
margin-bottom: 20px;
}
.firstname, .surname {
font-size: 12px;
font-family: Verdana, Arial, helvetica, sans-serif;
}
table {
border-collapse: collapse;
border-spacing: 0;
border: 1px black;
empty-cells: hide;
margin: 10px 0px 30px 50px;
width: 90%;
}
div.table {
margin: 30px 0px 30px 0px;
border: 1px dashed gray;
padding: 10px;
}
div .table-contents table {
border: 1px solid black;
}
div.table > p.title {
padding-left: 10px;
}
td {
padding: 4pt;
font-family: Verdana, Arial, helvetica, sans-serif;
}
div.warning TD {
text-align: justify;
}
h1 {
font-size: 150%;
}
h2 {
font-size: 110%;
}
h3 {
font-size: 100%;
font-weight: bold;
}
h4 {
font-size: 90%;
font-weight: bold;
}
h5 {
font-size: 90%;
font-style: italic;
}
h6 {
font-size: 100%;
font-style: italic;
}
tt {
font-size: 110%;
font-family: "Courier New", Courier, monospace;
color: #000000;
}
.navheader, .navfooter {
border: none;
}
pre {
font-size: 110%;
padding: 5px;
border-style: solid;
border-width: 1px;
border-color: #CCCCCC;
background-color: #f3f5e9;
}
ul, ol, li {
list-style: disc;
}
hr {
width: 100%;
height: 1px;
background-color: #CCCCCC;
border-width: 0px;
padding: 0px;
}
.variablelist {
padding-top: 10px;
padding-bottom: 10px;
margin: 0;
}
.term {
font-weight: bold;
}
.mediaobject {
padding-top: 30px;
padding-bottom: 30px;
}
.legalnotice {
font-family: Verdana, Arial, helvetica, sans-serif;
font-size: 12px;
font-style: italic;
}
.sidebar {
float: right;
margin: 10px 0px 10px 30px;
padding: 10px 20px 20px 20px;
width: 33%;
border: 1px solid black;
background-color: #F4F4F4;
font-size: 14px;
}
.property {
font-family: "Courier New", Courier, monospace;
}
a code {
font-family: Verdana, Arial, monospace;
font-size: 12px;
}
td code {
font-size: 110%;
}
div.note * td,
div.tip * td,
div.warning * td,
div.calloutlist * td {
text-align: justify;
font-size: 100%;
}
.programlisting .interfacename,
.programlisting .literal,
.programlisting .classname {
font-size: 95%;
}
.title .interfacename,
.title .literal,
.title .classname {
font-size: 130%;
}
.programlisting * .lineannotation,
.programlisting * .lineannotation * {
color: blue;
}
.bannerLeft, .bannerRight {
font-size: xx-large;
font-weight: bold;
}
.bannerLeft img, .bannerRight img {
margin: 0px;
}
.bannerLeft img {
float:left;
text-shadow: #7CFC00;
}
.bannerRight img {
float:right;
text-shadow: #7CFC00;
}
.banner {
padding: 0px;
}
.banner img {
border: none;
}
.clear {
clear:both;
visibility: hidden;
}

1
src/docbkx/resources/images/SPNEGO.svg
View File

File diff suppressed because one or more lines are too long
Side by Side

Before

Width:  |  Height:  |  Size: 68 KiB

BIN
src/docbkx/resources/images/asf_logo_wide.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 5.7 KiB

BIN
src/docbkx/resources/images/hc_logo.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.4 KiB

381
src/docbkx/resources/xsl/fopdf.xsl
View File

@ -1,381 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
====================================================================
This software consists of voluntary contributions made by many
individuals on behalf of the Apache Software Foundation. For more
information on the Apache Software Foundation, please see
<http://www.apache.org />.
====================================================================
Based on XSL FO (PDF) stylesheet for the Spring reference
documentation.
Thanks are due to Christian Bauer of the Hibernate project
team for writing the original stylesheet upon which this one
is based.
-->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:fo="http://www.w3.org/1999/XSL/Format"
version="1.0">
<xsl:import href="urn:docbkx:stylesheet"/>
<!-- Prevent blank pages in output -->
<xsl:template name="book.titlepage.before.verso">
</xsl:template>
<xsl:template name="book.titlepage.verso">
</xsl:template>
<xsl:template name="book.titlepage.separator">
</xsl:template>
<!--###################################################
Header
################################################### -->
<!-- More space in the center header for long text -->
<xsl:attribute-set name="header.content.properties">
<xsl:attribute name="font-family">
<xsl:value-of select="$body.font.family"/>
</xsl:attribute>
<xsl:attribute name="margin-left">-5em</xsl:attribute>
<xsl:attribute name="margin-right">-5em</xsl:attribute>
</xsl:attribute-set>
<!--###################################################
Custom Footer
################################################### -->
<xsl:template name="footer.content">
<xsl:param name="pageclass" select="''"/>
<xsl:param name="sequence" select="''"/>
<xsl:param name="position" select="''"/>
<xsl:param name="gentext-key" select="''"/>
<xsl:variable name="Version">
<xsl:if test="//releaseinfo">
<xsl:text>HttpClient (</xsl:text>
<xsl:value-of select="//releaseinfo"/>
<xsl:text>)</xsl:text>
</xsl:if>
</xsl:variable>
<xsl:choose>
<xsl:when test="$sequence='blank'">
<xsl:if test="$position = 'center'">
<xsl:value-of select="$Version"/>
</xsl:if>
</xsl:when>
<!-- for double sided printing, print page numbers on alternating sides (of the page) -->
<xsl:when test="$double.sided != 0">
<xsl:choose>
<xsl:when test="$sequence = 'even' and $position='left'">
<fo:page-number/>
</xsl:when>
<xsl:when test="$sequence = 'odd' and $position='right'">
<fo:page-number/>
</xsl:when>
<xsl:when test="$position='center'">
<xsl:value-of select="$Version"/>
</xsl:when>
</xsl:choose>
</xsl:when>
<!-- for single sided printing, print all page numbers on the right (of the page) -->
<xsl:when test="$double.sided = 0">
<xsl:choose>
<xsl:when test="$position='center'">
<xsl:value-of select="$Version"/>
</xsl:when>
<xsl:when test="$position='right'">
<fo:page-number/>
</xsl:when>
</xsl:choose>
</xsl:when>
</xsl:choose>
</xsl:template>
<!--###################################################
Table Of Contents
################################################### -->
<!-- Generate the TOCs for named components only -->
<xsl:param name="generate.toc">
book toc
</xsl:param>
<!-- Show only Sections up to level 3 in the TOCs -->
<xsl:param name="toc.section.depth">2</xsl:param>
<!-- Show titles in bookmarks pane -->
<xsl:param name="fop1.extensions">1</xsl:param>
<!-- Dot and Whitespace as separator in TOC between Label and Title-->
<xsl:param name="autotoc.label.separator" select="'. '"/>
<!--###################################################
Paper & Page Size
################################################### -->
<!-- Paper type, no headers on blank pages, no double sided printing -->
<xsl:param name="paper.type" select="'A4'"/>
<xsl:param name="double.sided">0</xsl:param>
<xsl:param name="headers.on.blank.pages">0</xsl:param>
<xsl:param name="footers.on.blank.pages">0</xsl:param>
<!-- Space between paper border and content (chaotic stuff, don't touch) -->
<xsl:param name="page.margin.top">5mm</xsl:param>
<xsl:param name="region.before.extent">10mm</xsl:param>
<xsl:param name="body.margin.top">10mm</xsl:param>
<xsl:param name="body.margin.bottom">15mm</xsl:param>
<xsl:param name="region.after.extent">10mm</xsl:param>
<xsl:param name="page.margin.bottom">0mm</xsl:param>
<xsl:param name="page.margin.outer">18mm</xsl:param>
<xsl:param name="page.margin.inner">18mm</xsl:param>
<!-- No intendation of Titles -->
<xsl:param name="title.margin.left">0pc</xsl:param>
<!--###################################################
Fonts & Styles
################################################### -->
<!-- Left aligned text and no hyphenation -->
<xsl:param name="alignment">justify</xsl:param>
<xsl:param name="hyphenate">false</xsl:param>
<!-- Default Font size -->
<xsl:param name="body.font.master">11</xsl:param>
<xsl:param name="body.font.small">8</xsl:param>
<!-- Line height in body text -->
<xsl:param name="line-height">1.4</xsl:param>
<!-- Monospaced fonts are smaller than regular text -->
<xsl:attribute-set name="monospace.properties">
<xsl:attribute name="font-family">
<xsl:value-of select="$monospace.font.family"/>
</xsl:attribute>
<xsl:attribute name="font-size">0.8em</xsl:attribute>
</xsl:attribute-set>
<!--###################################################
Tables
################################################### -->
<!-- The table width should be adapted to the paper size -->
<xsl:param name="default.table.width">17.4cm</xsl:param>
<!-- Some padding inside tables -->
<xsl:attribute-set name="table.cell.padding">
<xsl:attribute name="padding-left">4pt</xsl:attribute>
<xsl:attribute name="padding-right">4pt</xsl:attribute>
<xsl:attribute name="padding-top">4pt</xsl:attribute>
<xsl:attribute name="padding-bottom">4pt</xsl:attribute>
</xsl:attribute-set>
<!-- Only hairlines as frame and cell borders in tables -->
<xsl:param name="table.frame.border.thickness">0.1pt</xsl:param>
<xsl:param name="table.cell.border.thickness">0.1pt</xsl:param>
<!--###################################################
Labels
################################################### -->
<!-- Label Chapters and Sections (numbering) -->
<xsl:param name="chapter.autolabel">1</xsl:param>
<xsl:param name="section.autolabel" select="1"/>
<xsl:param name="section.label.includes.component.label" select="1"/>
<!--###################################################
Titles
################################################### -->
<!-- Chapter title size -->
<xsl:attribute-set name="chapter.titlepage.recto.style">
<xsl:attribute name="text-align">left</xsl:attribute>
<xsl:attribute name="font-weight">bold</xsl:attribute>
<xsl:attribute name="font-size">
<xsl:value-of select="$body.font.master * 1.8"/>
<xsl:text>pt</xsl:text>
</xsl:attribute>
</xsl:attribute-set>
<!-- Why is the font-size for chapters hardcoded in the XSL FO templates?
Let's remove it, so this sucker can use our attribute-set only... -->
<xsl:template match="title" mode="chapter.titlepage.recto.auto.mode">
<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"
xsl:use-attribute-sets="chapter.titlepage.recto.style">
<xsl:call-template name="component.title">
<xsl:with-param name="node" select="ancestor-or-self::chapter[1]"/>
</xsl:call-template>
</fo:block>
</xsl:template>
<!-- Sections 1, 2 and 3 titles have a small bump factor and padding -->
<xsl:attribute-set name="section.title.level1.properties">
<xsl:attribute name="space-before.optimum">0.8em</xsl:attribute>
<xsl:attribute name="space-before.minimum">0.8em</xsl:attribute>
<xsl:attribute name="space-before.maximum">0.8em</xsl:attribute>
<xsl:attribute name="font-size">
<xsl:value-of select="$body.font.master * 1.5"/>
<xsl:text>pt</xsl:text>
</xsl:attribute>
<xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
</xsl:attribute-set>
<xsl:attribute-set name="section.title.level2.properties">
<xsl:attribute name="space-before.optimum">0.6em</xsl:attribute>
<xsl:attribute name="space-before.minimum">0.6em</xsl:attribute>
<xsl:attribute name="space-before.maximum">0.6em</xsl:attribute>
<xsl:attribute name="font-size">
<xsl:value-of select="$body.font.master * 1.25"/>
<xsl:text>pt</xsl:text>
</xsl:attribute>
<xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
</xsl:attribute-set>
<xsl:attribute-set name="section.title.level3.properties">
<xsl:attribute name="space-before.optimum">0.4em</xsl:attribute>
<xsl:attribute name="space-before.minimum">0.4em</xsl:attribute>
<xsl:attribute name="space-before.maximum">0.4em</xsl:attribute>
<xsl:attribute name="font-size">
<xsl:value-of select="$body.font.master * 1.0"/>
<xsl:text>pt</xsl:text>
</xsl:attribute>
<xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
</xsl:attribute-set>
<!-- Titles of formal objects (tables, examples, ...) -->
<xsl:attribute-set name="formal.title.properties" use-attribute-sets="normal.para.spacing">
<xsl:attribute name="font-weight">bold</xsl:attribute>
<xsl:attribute name="font-size">
<xsl:value-of select="$body.font.master"/>
<xsl:text>pt</xsl:text>
</xsl:attribute>
<xsl:attribute name="hyphenate">false</xsl:attribute>
<xsl:attribute name="space-after.minimum">0.4em</xsl:attribute>
<xsl:attribute name="space-after.optimum">0.6em</xsl:attribute>
<xsl:attribute name="space-after.maximum">0.8em</xsl:attribute>
</xsl:attribute-set>
<!--###################################################
Programlistings
################################################### -->
<!-- Verbatim text formatting (programlistings) -->
<xsl:attribute-set name="monospace.verbatim.properties">
<xsl:attribute name="font-size">
<xsl:value-of select="$body.font.small * 1.0"/>
<xsl:text>pt</xsl:text>
</xsl:attribute>
</xsl:attribute-set>
<xsl:attribute-set name="verbatim.properties">
<xsl:attribute name="space-before.minimum">1em</xsl:attribute>
<xsl:attribute name="space-before.optimum">1em</xsl:attribute>
<xsl:attribute name="space-before.maximum">1em</xsl:attribute>
<xsl:attribute name="border-color">#444444</xsl:attribute>
<xsl:attribute name="border-style">solid</xsl:attribute>
<xsl:attribute name="border-width">0.1pt</xsl:attribute>
<xsl:attribute name="padding-top">0.5em</xsl:attribute>
<xsl:attribute name="padding-left">0.5em</xsl:attribute>
<xsl:attribute name="padding-right">0.5em</xsl:attribute>
<xsl:attribute name="padding-bottom">0.5em</xsl:attribute>
<xsl:attribute name="margin-left">0.5em</xsl:attribute>
<xsl:attribute name="margin-right">0.5em</xsl:attribute>
</xsl:attribute-set>
<!-- Shade (background) programlistings -->
<xsl:param name="shade.verbatim">1</xsl:param>
<xsl:attribute-set name="shade.verbatim.style">
<xsl:attribute name="background-color">#F0F0F0</xsl:attribute>
</xsl:attribute-set>
<!--###################################################
Callouts
################################################### -->
<!-- Use images for callouts instead of (1) (2) (3) -->
<xsl:param name="callout.graphics">0</xsl:param>
<xsl:param name="callout.unicode">1</xsl:param>
<!-- Place callout marks at this column in annotated areas -->
<xsl:param name="callout.defaultcolumn">90</xsl:param>
<!--###################################################
Admonitions
################################################### -->
<!-- Use nice graphics for admonitions -->
<xsl:param name="admon.graphics">'1'</xsl:param>
<!-- <xsl:param name="admon.graphics.path">&admon_gfx_path;</xsl:param> -->
<!--###################################################
Misc
################################################### -->
<!-- Placement of titles -->
<xsl:param name="formal.title.placement">
figure after
example before
equation before
table before
procedure before
</xsl:param>
<!-- Format Variable Lists as Blocks (prevents horizontal overflow) -->
<xsl:param name="variablelist.as.blocks">1</xsl:param>
<!-- The horrible list spacing problems -->
<xsl:attribute-set name="list.block.spacing">
<xsl:attribute name="space-before.optimum">0.8em</xsl:attribute>
<xsl:attribute name="space-before.minimum">0.8em</xsl:attribute>
<xsl:attribute name="space-before.maximum">0.8em</xsl:attribute>
<xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
</xsl:attribute-set>
<!--###################################################
colored and hyphenated links
################################################### -->
<xsl:template match="ulink">
<fo:basic-link external-destination="{@url}"
xsl:use-attribute-sets="xref.properties"
text-decoration="underline"
color="blue">
<xsl:choose>
<xsl:when test="count(child::node())=0">
<xsl:value-of select="@url"/>
</xsl:when>
<xsl:otherwise>
<xsl:apply-templates/>
</xsl:otherwise>
</xsl:choose>
</fo:basic-link>
</xsl:template>
</xsl:stylesheet>

115
src/docbkx/resources/xsl/html.xsl
View File

@ -1,115 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
====================================================================
This software consists of voluntary contributions made by many
individuals on behalf of the Apache Software Foundation. For more
information on the Apache Software Foundation, please see
<http://www.apache.org />.
====================================================================
Based on the XSL HTML configuration file for the Spring
Reference Documentation.
-->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:import href="urn:docbkx:stylesheet"/>
<!--###################################################
HTML Settings
################################################### -->
<xsl:param name="html.stylesheet">html.css</xsl:param>
<!-- These extensions are required for table printing and other stuff -->
<xsl:param name="use.extensions">1</xsl:param>
<xsl:param name="tablecolumns.extension">0</xsl:param>
<xsl:param name="callout.extensions">1</xsl:param>
<xsl:param name="graphicsize.extension">0</xsl:param>
<!--###################################################
Table Of Contents
################################################### -->
<!-- Generate the TOCs for named components only -->
<xsl:param name="generate.toc">
book toc
</xsl:param>
<!-- Show only Sections up to level 3 in the TOCs -->
<xsl:param name="toc.section.depth">3</xsl:param>
<!--###################################################
Labels
################################################### -->
<!-- Label Chapters and Sections (numbering) -->
<xsl:param name="chapter.autolabel">1</xsl:param>
<xsl:param name="section.autolabel" select="1"/>
<xsl:param name="section.label.includes.component.label" select="1"/>
<!--###################################################
Callouts
################################################### -->
<!-- Use images for callouts instead of (1) (2) (3) -->
<xsl:param name="callout.graphics">0</xsl:param>
<!-- Place callout marks at this column in annotated areas -->
<xsl:param name="callout.defaultcolumn">90</xsl:param>
<!--###################################################
Admonitions
################################################### -->
<!-- Use nice graphics for admonitions -->
<xsl:param name="admon.graphics">0</xsl:param>
<!--###################################################
Misc
################################################### -->
<!-- Placement of titles -->
<xsl:param name="formal.title.placement">
figure after
example before
equation before
table before
procedure before
</xsl:param>
<xsl:template match="author" mode="titlepage.mode">
<xsl:if test="name(preceding-sibling::*[1]) = 'author'">
<xsl:text>, </xsl:text>
</xsl:if>
<span class="{name(.)}">
<xsl:call-template name="person.name"/>
<xsl:apply-templates mode="titlepage.mode" select="./contrib"/>
<xsl:apply-templates mode="titlepage.mode" select="./affiliation"/>
</span>
</xsl:template>
<xsl:template match="authorgroup" mode="titlepage.mode">
<div class="{name(.)}">
<h2>Authors</h2>
<p/>
<xsl:apply-templates mode="titlepage.mode"/>
</div>
</xsl:template>
</xsl:stylesheet>

112
src/docbkx/resources/xsl/html_chunk.xsl
View File

@ -1,112 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
====================================================================
This software consists of voluntary contributions made by many
individuals on behalf of the Apache Software Foundation. For more
information on the Apache Software Foundation, please see
<http://www.apache.org />.
====================================================================
Based on the XSL HTML configuration file for the Spring
Reference Documentation.
-->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:import href="urn:docbkx:stylesheet"/>
<!--###################################################
HTML Settings
################################################### -->
<xsl:param name="chunk.section.depth">'5'</xsl:param>
<xsl:param name="use.id.as.filename">'1'</xsl:param>
<!-- These extensions are required for table printing and other stuff -->
<xsl:param name="use.extensions">1</xsl:param>
<xsl:param name="tablecolumns.extension">0</xsl:param>
<xsl:param name="callout.extensions">1</xsl:param>
<xsl:param name="graphicsize.extension">0</xsl:param>
<!--###################################################
Table Of Contents
################################################### -->
<!-- Generate the TOCs for named components only -->
<xsl:param name="generate.toc">
book toc
</xsl:param>
<!-- Show only Sections up to level 3 in the TOCs -->
<xsl:param name="toc.section.depth">3</xsl:param>
<!--###################################################
Labels
################################################### -->
<!-- Label Chapters and Sections (numbering) -->
<xsl:param name="chapter.autolabel">1</xsl:param>
<xsl:param name="section.autolabel" select="1"/>
<xsl:param name="section.label.includes.component.label" select="1"/>
<!--###################################################
Callouts
################################################### -->
<!-- Place callout marks at this column in annotated areas -->
<xsl:param name="callout.graphics">1</xsl:param>
<xsl:param name="callout.defaultcolumn">90</xsl:param>
<!--###################################################
Misc
################################################### -->
<!-- Placement of titles -->
<xsl:param name="formal.title.placement">
figure after
example before
equation before
table before
procedure before
</xsl:param>
<xsl:template match="author" mode="titlepage.mode">
<xsl:if test="name(preceding-sibling::*[1]) = 'author'">
<xsl:text>, </xsl:text>
</xsl:if>
<span class="{name(.)}">
<xsl:call-template name="person.name"/>
<xsl:apply-templates mode="titlepage.mode" select="./contrib"/>
<xsl:apply-templates mode="titlepage.mode" select="./affiliation"/>
</span>
</xsl:template>
<xsl:template match="authorgroup" mode="titlepage.mode">
<div class="{name(.)}">
<h2>Authors</h2>
<p/>
<xsl:apply-templates mode="titlepage.mode"/>
</div>
</xsl:template>
<!--###################################################
Headers and Footers
################################################### -->
<xsl:template name="user.header.navigation">
<div class="banner">
<a class="bannerLeft" href="http://www.apache.org/"
title="Apache Software Foundation">
<img style="border:none;" src="images/asf_logo_wide.gif"/>
</a>
<a class="bannerRight" href="http://hc.apache.org/httpcomponents-client-ga/"
title="Apache HttpComponents Client">
<img style="border:none;" src="images/hc_logo.png"/>
</a>
<div class="clear"/>
</div>
</xsl:template>
</xsl:stylesheet>

289
src/docbkx/statemgmt.xml
View File

@ -1,289 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
====================================================================
-->
<chapter id="statemgmt">
<title>HTTP state management</title>
<para>Originally HTTP was designed as a stateless, request / response oriented protocol that
made no special provisions for stateful sessions spanning across several logically related
request / response exchanges. As HTTP protocol grew in popularity and adoption more and more
systems began to use it for applications it was never intended for, for instance as a
transport for e-commerce applications. Thus, the support for state management became a
necessity.</para>
<para>Netscape Communications, at that time a leading developer of web client and server
software, implemented support for HTTP state management in their products based on a
proprietary specification. Later, Netscape tried to standardise the mechanism by publishing
a specification draft. Those efforts contributed to the formal specification defined through
the RFC standard track. However, state management in a significant number of applications is
still largely based on the Netscape draft and is incompatible with the official
specification. All major developers of web browsers felt compelled to retain compatibility
with those applications greatly contributing to the fragmentation of standards
compliance.</para>
<section>
<title>HTTP cookies</title>
<para>An HTTP cookie is a token or short packet of state information that the HTTP agent and the
target server can exchange to maintain a session. Netscape engineers used to refer to it
as a "magic cookie" and the name stuck.</para>
<para>HttpClient uses the <interfacename>Cookie</interfacename> interface to represent an
abstract cookie token. In its simplest form an HTTP cookie is merely a name / value pair.
Usually an HTTP cookie also contains a number of attributes such a domain for which is
valid, a path that specifies the subset of URLs on the origin server to which this
cookie applies, and the maximum period of time for which the cookie is valid.</para>
<para>The <interfacename>SetCookie</interfacename> interface represents a
<literal>Set-Cookie</literal> response header sent by the origin server to the HTTP
agent in order to maintain a conversational state.</para>
<para>The <interfacename>ClientCookie</interfacename> interface extends <interfacename>
Cookie</interfacename> interface with additional client specific functionality such
as the ability to retrieve original cookie attributes exactly as they were specified
by the origin server. This is important for generating the <literal>Cookie</literal>
header because some cookie specifications require that the <literal>Cookie</literal>
header should include certain attributes only if they were specified in the
<literal>Set-Cookie</literal> header.</para>
<para>Here is an example of creating a client-side cookie object:</para>
<programlisting><![CDATA[
BasicClientCookie cookie = new BasicClientCookie("name", "value");
// Set effective domain and path attributes
cookie.setDomain(".mycompany.com");
cookie.setPath("/");
// Set attributes exactly as sent by the server
cookie.setAttribute(ClientCookie.PATH_ATTR, "/");
cookie.setAttribute(ClientCookie.DOMAIN_ATTR, ".mycompany.com");
]]></programlisting>
</section>
<section>
<title>Cookie specifications</title>
<para>The <interfacename>CookieSpec</interfacename> interface represents a cookie management
specification. The cookie management specification is expected to enforce:</para>
<itemizedlist>
<listitem>
<para>rules of parsing <literal>Set-Cookie</literal> headers.</para>
</listitem>
<listitem>
<para>rules of validation of parsed cookies.</para>
</listitem>
<listitem>
<para>formatting of <literal>Cookie</literal> header for a given host, port and path
of origin.</para>
</listitem>
</itemizedlist>
<para>HttpClient ships with several <interfacename>CookieSpec</interfacename>
implementations:</para>
<itemizedlist>
<listitem>
<formalpara>
<title>Standard strict:</title>
<para>State management policy compliant with the syntax and semantics of
the well-behaved profile defined by RFC 6265, section 4.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Standard:</title>
<para>State management policy compliant with a more relaxed profile defined
by RFC 6265, section 4 intended for interoperability with existing servers
that do not conform to the well behaved profile.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Netscape draft (obsolete):</title>
<para>This policy conforms to the original draft specification published
by Netscape Communications. It should be avoided unless absolutely necessary
for compatibility with legacy code.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>RFC 2965 (obsolete):</title>
<para>State management policy compliant with the obsolete state management
specification defined by RFC 2965. Please do not use in new applications.
</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>RFC 2109 (obsolete):</title>
<para>State management policy compliant with the obsolete state management
specification defined by RFC 2109. Please do not use in new applications.
</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Browser compatibility (obsolete):</title>
<para>This policy strives to closely mimic the (mis)behavior of older versions
of browser applications such as Microsoft Internet Explorer and Mozilla
FireFox. Please do not use in new applications.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Default:</title>
<para>Default cookie policy is a synthetic policy that picks up either RFC 2965,
RFC 2109 or Netscape draft compliant implementation based on properties of
cookies sent with the HTTP response (such as version attribute,
now obsolete). This policy will be deprecated in favor of the
standard (RFC 6265 compliant) implementation in the next minor release
of HttpClient.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Ignore cookies:</title>
<para>All cookies are ignored.</para>
</formalpara>
</listitem>
</itemizedlist>
<para>It is strongly recommended to use either <literal>Standard</literal> or
<literal>Standard strict</literal> policy in new applications. Obsolete specifications
should be used for compatibility with legacy systems only. Support for obsolete
specifications will be removed in the next major release of HttpClient.
</para>
</section>
<section>
<title>Choosing cookie policy</title>
<para>Cookie policy can be set at the HTTP client and overridden on the HTTP request level
if required.</para>
<programlisting><![CDATA[
RequestConfig globalConfig = RequestConfig.custom()
.setCookieSpec(CookieSpecs.DEFAULT)
.build();
CloseableHttpClient httpclient = HttpClients.custom()
.setDefaultRequestConfig(globalConfig)
.build();
RequestConfig localConfig = RequestConfig.copy(globalConfig)
.setCookieSpec(CookieSpecs.STANDARD_STRICT)
.build();
HttpGet httpGet = new HttpGet("/");
httpGet.setConfig(localConfig);
]]></programlisting>
</section>
<section>
<title>Custom cookie policy</title>
<para>In order to implement a custom cookie policy one should create a custom implementation
of the <interfacename>CookieSpec</interfacename> interface, create a
<interfacename>CookieSpecProvider</interfacename> implementation to create and
initialize instances of the custom specification and register the factory with
HttpClient. Once the custom specification has been registered, it can be activated the
same way as a standard cookie specification.</para>
<programlisting><![CDATA[
PublicSuffixMatcher publicSuffixMatcher = PublicSuffixMatcherLoader.getDefault();
Registry<CookieSpecProvider> r = RegistryBuilder.<CookieSpecProvider>create()
.register(CookieSpecs.DEFAULT,
new DefaultCookieSpecProvider(publicSuffixMatcher))
.register(CookieSpecs.STANDARD,
new RFC6265CookieSpecProvider(publicSuffixMatcher))
.register("easy", new EasySpecProvider())
.build();
RequestConfig requestConfig = RequestConfig.custom()
.setCookieSpec("easy")
.build();
CloseableHttpClient httpclient = HttpClients.custom()
.setDefaultCookieSpecRegistry(r)
.setDefaultRequestConfig(requestConfig)
.build();
]]></programlisting>
</section>
<section>
<title>Cookie persistence</title>
<para>HttpClient can work with any physical representation of a persistent cookie store that
implements the <interfacename>CookieStore</interfacename> interface. The default
<interfacename>CookieStore</interfacename> implementation called
<classname>BasicCookieStore</classname> is a simple implementation backed by a
<classname>java.util.ArrayList</classname>. Cookies stored in an
<classname>BasicClientCookie</classname> object are lost when the container object
get garbage collected. Users can provide more complex implementations if
necessary.</para>
<programlisting><![CDATA[
// Create a local instance of cookie store
CookieStore cookieStore = new BasicCookieStore();
// Populate cookies if needed
BasicClientCookie cookie = new BasicClientCookie("name", "value");
cookie.setDomain(".mycompany.com");
cookie.setPath("/");
cookieStore.addCookie(cookie);
// Set the store
CloseableHttpClient httpclient = HttpClients.custom()
.setDefaultCookieStore(cookieStore)
.build();
]]></programlisting>
</section>
<section>
<title>HTTP state management and execution context</title>
<para>In the course of HTTP request execution HttpClient adds the following state management
related objects to the execution context:</para>
<itemizedlist>
<listitem>
<formalpara>
<para><interfacename>Lookup</interfacename> instance representing the actual
cookie specification registry. The value of this attribute set in the local
context takes precedence over the default one.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<para><interfacename>CookieSpec</interfacename> instance representing the actual
cookie specification.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<para><classname>CookieOrigin</classname> instance representing the actual
details of the origin server.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<para><interfacename>CookieStore</interfacename> instance representing the actual
cookie store. The value of this attribute set in the local context takes
precedence over the default one.</para>
</formalpara>
</listitem>
</itemizedlist>
<para>The local <interfacename>HttpContext</interfacename> object can be used to customize
the HTTP state management context prior to request execution, or to examine its state after
the request has been executed. One can also use separate execution contexts in order
to implement per user (or per thread) state management. A cookie specification registry
and cookie store defined in the local context will take precedence over the default
ones set at the HTTP client level</para>
<programlisting><![CDATA[
CloseableHttpClient httpclient = <...>
Lookup<CookieSpecProvider> cookieSpecReg = <...>
CookieStore cookieStore = <...>
HttpClientContext context = HttpClientContext.create();
context.setCookieSpecRegistry(cookieSpecReg);
context.setCookieStore(cookieStore);
HttpGet httpget = new HttpGet("http://somehost/");
CloseableHttpResponse response1 = httpclient.execute(httpget, context);
<...>
// Cookie origin details
CookieOrigin cookieOrigin = context.getCookieOrigin();
// Cookie spec used
CookieSpec cookieSpec = context.getCookieSpec();
]]></programlisting>
</section>
</chapter>