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 2010/11/03 17:09:08 UTC
svn commit: r1030511 - in /httpcomponents/httpclient/trunk/src/docbkx:
advanced.xml authentication.xml caching.xml connmgmt.xml fundamentals.xml
Author: olegk
Date: Wed Nov 3 16:09:07 2010
New Revision: 1030511
URL: http://svn.apache.org/viewvc?rev=1030511&view=rev
Log:
Updated HttpClient tutorial for the 4.1-beta1 release
Modified:
httpcomponents/httpclient/trunk/src/docbkx/advanced.xml
httpcomponents/httpclient/trunk/src/docbkx/authentication.xml
httpcomponents/httpclient/trunk/src/docbkx/caching.xml
httpcomponents/httpclient/trunk/src/docbkx/connmgmt.xml
httpcomponents/httpclient/trunk/src/docbkx/fundamentals.xml
Modified: httpcomponents/httpclient/trunk/src/docbkx/advanced.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/src/docbkx/advanced.xml?rev=1030511&r1=1030510&r2=1030511&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/src/docbkx/advanced.xml (original)
+++ httpcomponents/httpclient/trunk/src/docbkx/advanced.xml Wed Nov 3 16:09:07 2010
@@ -181,9 +181,7 @@ HttpContext localContext = new BasicHttp
HttpGet httpget = new HttpGet("http://localhost:8080/");
HttpResponse response = httpclient.execute(httpget, localContext);
HttpEntity entity = response.getEntity();
-if (entity != null) {
- entity.consumeContent();
-}
+EntityUtils.consume(entity);
Object userToken = localContext.getAttribute(ClientContext.USER_TOKEN);
System.out.println(userToken);
]]></programlisting>
@@ -200,9 +198,7 @@ HttpContext localContext1 = new BasicHtt
HttpGet httpget1 = new HttpGet("http://localhost:8080/");
HttpResponse response1 = httpclient.execute(httpget1, localContext1);
HttpEntity entity1 = response1.getEntity();
-if (entity1 != null) {
- entity1.consumeContent();
-}
+EntityUtils.consume(entity1);
Principal principal = (Principal) localContext1.getAttribute(
ClientContext.USER_TOKEN);
@@ -211,9 +207,7 @@ localContext2.setAttribute(ClientContext
HttpGet httpget2 = new HttpGet("http://localhost:8080/");
HttpResponse response2 = httpclient.execute(httpget2, localContext2);
HttpEntity entity2 = response2.getEntity();
-if (entity2 != null) {
- entity2.consumeContent();
-}
+EntityUtils.consume(entity2);
]]></programlisting>
</section>
</section>
Modified: httpcomponents/httpclient/trunk/src/docbkx/authentication.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/src/docbkx/authentication.xml?rev=1030511&r1=1030510&r2=1030511&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/src/docbkx/authentication.xml (original)
+++ httpcomponents/httpclient/trunk/src/docbkx/authentication.xml Wed Nov 3 16:09:07 2010
@@ -24,9 +24,8 @@
<chapter id="authentication">
<title>HTTP authentication</title>
<para>HttpClient provides full support for authentication schemes defined by the HTTP standard
- specification. HttpClient's authentication framework can also be extended to support
- non-standard authentication schemes such as <literal>NTLM</literal> and
- <literal>SPNEGO</literal>.</para>
+ 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
@@ -109,9 +108,7 @@ pwd
<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. This scheme is requires an external NTLM engine to be functional.
- For details please refer to the <literal>NTLM_SUPPORT.txt</literal> document
- included with HttpClient distributions.</para>
+ Digest.</para>
</formalpara>
</listitem>
<listitem>
@@ -194,23 +191,28 @@ httpclient.getParams().setParameter(Auth
<listitem>
<formalpara>
<title>Basic:</title>
- <para>Basic authentication scheme</para>
+ <para>Basic authentication</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Digest:</title>
- <para>Digest authentication scheme</para>
+ <para>Digest authentication</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>NTLM:</title>
+ <para>NTLMv1, NTLMv2, and NTLM2 Session authentication</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>SPNEGO:</title>
+ <para>SPNEGO/Kerberos authentication</para>
</formalpara>
</listitem>
</itemizedlist>
- <para>Please note <literal>NTLM</literal> and <literal>SPNEGO</literal> schemes are
- <emphasis>NOT</emphasis> registered per default. The <literal>NTLM</literal> cannot
- be enabled per default due to licensing and legal reasons. For details on how to
- enable <literal>NTLM</literal> support please see <link linkend="ntlm">this</link>
- section. <literal>SPNEGO</literal> setup tends to be system specific and must be
- properly configured in order to be functional. See <link linkend="spnego">this </link>
- section for details. </para>
</section>
<section>
<title>Credentials provider</title>
@@ -376,23 +378,18 @@ HttpGet httpget = new HttpGet("/");
for (int i = 0; i < 3; i++) {
HttpResponse response = httpclient.execute(targetHost, httpget, localcontext);
HttpEntity entity = response.getEntity();
- if (entity != null) {
- entity.consumeContent();
- }
+ EntityUtils.consume(entity);
}
]]></programlisting>
</section>
<section id="ntlm">
<title>NTLM Authentication</title>
- <para>Currently HttpClient does not provide support for the NTLM authentication scheme out
- of the box and probably never will. The reasons for that are legal rather than
- technical. However, NTLM authentication can be enabled by using an external
+ <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. For details
- please refer to the <literal>NTLM_SUPPORT.txt</literal> document included with
- HttpClient distributions.
+ project as a part of their Windows interoperability suite of programs.
</para>
<section>
<title>NTLM connection persistence</title>
@@ -432,18 +429,14 @@ HttpContext localContext = new BasicHttp
HttpGet httpget = new HttpGet("/ntlm-protected/info");
HttpResponse response1 = httpclient.execute(target, httpget, localContext);
HttpEntity entity1 = response1.getEntity();
-if (entity1 != null) {
- entity1.consumeContent();
-}
+EntityUtils.consume(entity1);
// 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"));
HttpResponse response2 = httpclient.execute(target, httppost, localContext);
HttpEntity entity2 = response2.getEntity();
-if (entity2 != null) {
- entity2.consumeContent();
-}
+EntityUtils.consume(entity2);
]]></programlisting>
</section>
</section>
@@ -590,11 +583,8 @@ Value: 0x01
</programlisting>
</section>
<section>
- <title>Activating and customizing <literal>SPNEGO</literal> authentication
- scheme</title>
- <para>Please note <literal>SPNEGO</literal> authentication scheme is NOT active per
- default! </para>
- <para>In order to activate <literal>SPNEGO</literal> support an instance of
+ <title>Customizing <literal>SPNEGO</literal> authentication scheme</title>
+ <para>In order to customize <literal>SPNEGO</literal> support a new instance of
<classname>NegotiateSchemeFactory</classname> class must be created and
registered with the authentication scheme registry of HttpClient. </para>
<programlisting><![CDATA[
Modified: httpcomponents/httpclient/trunk/src/docbkx/caching.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/src/docbkx/caching.xml?rev=1030511&r1=1030510&r2=1030511&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/src/docbkx/caching.xml (original)
+++ httpcomponents/httpclient/trunk/src/docbkx/caching.xml Wed Nov 3 16:09:07 2010
@@ -114,16 +114,6 @@
</section>
<section>
- <title>Cache Implementation</title>
-
- <para>The provided implementation for an HttpCache<T> is called
- BasicHttpCache. It uses an in-memory LinkedHashMap to provide basic
- least-recently-used (LRU) functionality. Because we provide the
- HttpCache<T> interface, other implementations of caching may be
- used, e.g. EHCache, memcached, etc.</para>
- </section>
-
- <section>
<title>Example Usage</title>
<para>This is a simple example of how to set up a basic CachingHttpClient.
@@ -132,13 +122,37 @@
here are for example only and not intended to be prescriptive or
considered as recommendations.</para>
- <programlisting>
-HttpClient client = new DefaultHttpClient();
-int maxCacheEntries = 1000;
-int maxCacheEntrySizeBytes = 8192;
-HttpCache<CacheEntry> cache = new
-BasicHttpCache(maxCacheEntries);
-HttpClient cachingClient = new CachingHttpClient(client, cache, maxCacheEntrySizeBytes);
-</programlisting>
+ <programlisting><![CDATA[
+CacheConfig cacheConfig = new CacheConfig();
+cacheConfig.setMaxCacheEntries(1000);
+cacheConfig.setMaxObjectSizeBytes(8192);
+
+HttpClient cachingClient = new CachingHttpClient(new DefaultHttpClient(), cacheConfig);
+
+HttpContext localContext = new BasicHttpContext();
+HttpGet httpget = new HttpGet("http://www.mydomain.com/content/");
+HttpResponse response = cachingClient.execute(httpget, localContext);
+HttpEntity entity = response.getEntity();
+EntityUtils.consume(entity);
+CacheResponseStatus responseStatus = (CacheResponseStatus) localContext.getAttribute(
+ CachingHttpClient.CACHE_RESPONSE_STATUS);
+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;
+}
+]]>
+ </programlisting>
</section>
</chapter>
Modified: httpcomponents/httpclient/trunk/src/docbkx/connmgmt.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/src/docbkx/connmgmt.xml?rev=1030511&r1=1030510&r2=1030511&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/src/docbkx/connmgmt.xml (original)
+++ httpcomponents/httpclient/trunk/src/docbkx/connmgmt.xml Wed Nov 3 16:09:07 2010
@@ -595,9 +595,7 @@ HttpGet httpget = new HttpGet("http://ww
HttpResponse response = httpclient.execute(httpget);
HttpEntity entity = response.getEntity();
System.out.println(response.getStatusLine());
-if (entity != null) {
- entity.consumeContent();
-}
+EntityUtils.consume(entity);
httpclient.getConnectionManager().shutdown();
]]></programlisting>
</section>
@@ -668,10 +666,9 @@ static class GetThread extends Thread {
HttpEntity entity = response.getEntity();
if (entity != null) {
// do something useful with the entity
- // ...
- // ensure the connection gets released to the manager
- entity.consumeContent();
}
+ // ensure the connection gets released to the manager
+ EntityUtils.consume(entity);
} catch (Exception ex) {
this.httpget.abort();
}
Modified: httpcomponents/httpclient/trunk/src/docbkx/fundamentals.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/src/docbkx/fundamentals.xml?rev=1030511&r1=1030510&r2=1030511&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/src/docbkx/fundamentals.xml (original)
+++ httpcomponents/httpclient/trunk/src/docbkx/fundamentals.xml Wed Nov 3 16:09:07 2010
@@ -576,8 +576,7 @@ HttpHost target = (HttpHost) localContex
System.out.println("Final target: " + target);
HttpEntity entity = response.getEntity();
-if (entity != null) {
-entity.consumeContent();
+EntityUtils.consume(entity);
}
]]></programlisting>
<para>stdout ></para>
@@ -765,9 +764,7 @@ for (int i = 0; i < 10; i++) {
HttpResponse response = httpclient.execute(httpget, localContext);
HttpEntity entity = response.getEntity();
- if (entity != null) {
- entity.consumeContent();
- }
+ EntityUtils.consume(entity);
}
]]></programlisting>
</section>