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

Updated HttpClient tutorial for the 4.1-beta1 release 

git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@1030511 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Oleg Kalnichevski 2010-11-03 16:09:07 +00:00
parent 31590950b5
commit b2ad050679
5 changed files with 65 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
src/docbkx/advanced.xml
View File

@ -181,9 +181,7 @@ HttpContext localContext = new BasicHttpContext();
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 BasicHttpContext();
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.USER_TOKEN, principal);
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>

60
src/docbkx/authentication.xml
View File

@ -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(AuthPNames.PROXY_AUTH_PREF, authpref);
<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 BasicHttpContext();
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[

50
src/docbkx/caching.xml
View File

@ -113,16 +113,6 @@
requirements.</para>
</section>
<section>
<title>Cache Implementation</title>
<para>The provided implementation for an HttpCache&lt;T&gt; is called
BasicHttpCache. It uses an in-memory LinkedHashMap to provide basic
least-recently-used (LRU) functionality. Because we provide the
HttpCache&lt;T&gt; interface, other implementations of caching may be
used, e.g. EHCache, memcached, etc.</para>
</section>
<section>
<title>Example Usage</title>
@ -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&lt;CacheEntry&gt; 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>

9
src/docbkx/connmgmt.xml
View File

@ -595,9 +595,7 @@ HttpGet httpget = new HttpGet("http://www.google.com/");
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();
}

7
src/docbkx/fundamentals.xml
View File

@ -576,8 +576,7 @@ HttpHost target = (HttpHost) localContext.getAttribute(
System.out.println("Final target: " + target);
HttpEntity entity = response.getEntity();
if (entity != null) {
entity.consumeContent();
EntityUtils.consume(entity);
}
]]></programlisting>
<para>stdout &gt;</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>