You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hc.apache.org by ol...@apache.org on 2018/10/23 13:33:17 UTC
[4/5] httpcomponents-client git commit: Removed HttpClient 4.x
tutorial source
Removed HttpClient 4.x tutorial source
Project: http://git-wip-us.apache.org/repos/asf/httpcomponents-client/repo
Commit: http://git-wip-us.apache.org/repos/asf/httpcomponents-client/commit/f3ae401e
Tree: http://git-wip-us.apache.org/repos/asf/httpcomponents-client/tree/f3ae401e
Diff: http://git-wip-us.apache.org/repos/asf/httpcomponents-client/diff/f3ae401e
Branch: refs/heads/master
Commit: f3ae401ecf33e5af1ab85a00602dbd0988eae43f
Parents: 9058b1b
Author: Oleg Kalnichevski <ol...@apache.org>
Authored: Tue Oct 23 15:09:39 2018 +0200
Committer: Oleg Kalnichevski <ol...@apache.org>
Committed: Tue Oct 23 15:09:39 2018 +0200
----------------------------------------------------------------------
pom.xml | 54 --
src/docbkx/advanced.xml | 275 -------
src/docbkx/authentication.xml | 522 ------------
src/docbkx/caching.xml | 253 ------
src/docbkx/connmgmt.xml | 560 -------------
src/docbkx/fluent.xml | 131 ---
src/docbkx/fundamentals.xml | 892 ---------------------
src/docbkx/index.xml | 80 --
src/docbkx/preface.xml | 81 --
src/docbkx/resources/css/hc-tutorial.css | 309 -------
src/docbkx/resources/images/SPNEGO.svg | 1 -
src/docbkx/resources/images/asf_logo_wide.gif | Bin 5866 -> 0 bytes
src/docbkx/resources/images/hc_logo.png | Bin 2451 -> 0 bytes
src/docbkx/resources/xsl/fopdf.xsl | 381 ---------
src/docbkx/resources/xsl/html.xsl | 115 ---
src/docbkx/resources/xsl/html_chunk.xsl | 112 ---
src/docbkx/statemgmt.xml | 289 -------
17 files changed, 4055 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/httpcomponents-client/blob/f3ae401e/pom.xml
----------------------------------------------------------------------
diff --git a/pom.xml b/pom.xml
index ff81dcd..2f9383f 100644
--- a/pom.xml
+++ b/pom.xml
@@ -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>
http://git-wip-us.apache.org/repos/asf/httpcomponents-client/blob/f3ae401e/src/docbkx/advanced.xml
----------------------------------------------------------------------
diff --git a/src/docbkx/advanced.xml b/src/docbkx/advanced.xml
deleted file mode 100644
index b97ca36..0000000
--- a/src/docbkx/advanced.xml
+++ /dev/null
@@ -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>
http://git-wip-us.apache.org/repos/asf/httpcomponents-client/blob/f3ae401e/src/docbkx/authentication.xml
----------------------------------------------------------------------
diff --git a/src/docbkx/authentication.xml b/src/docbkx/authentication.xml
deleted file mode 100644
index 175f3e6..0000000
--- a/src/docbkx/authentication.xml
+++ /dev/null
@@ -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 ></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 ></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 ></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 <base64
- encoding></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>
http://git-wip-us.apache.org/repos/asf/httpcomponents-client/blob/f3ae401e/src/docbkx/caching.xml
----------------------------------------------------------------------
diff --git a/src/docbkx/caching.xml b/src/docbkx/caching.xml
deleted file mode 100644
index aa13d27..0000000
--- a/src/docbkx/caching.xml
+++ /dev/null
@@ -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>