HTTPCLIENT-1168: updated tutorial to describe recommended application of HttpContext in multi-threaded execution

git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@1296623 13f79535-47bb-0310-9956-ffa450edef68

src/docbkx/connmgmt.xml

@@ -626,6 +626,10 @@ for (int j = 0; j < threads.length; j++) {
 }
 
 ]]></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 {
     

src/docbkx/fundamentals.xml

@@ -473,6 +473,9 @@ byte[] response = httpclient.execute(httpget, handler);
             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>