svn commit: r1443633 - in /hbase/trunk: hbase-server/src/main/java/org/apache/hadoop/hbase/client/package-info.java src/docbkx/book.xml

[st...@apache.org]

Author: stack
Date: Thu Feb  7 18:01:08 2013
New Revision: 1443633

URL: http://svn.apache.org/r1443633
Log:
Add doc on htablepool and the htable constructor that takes an executor -- text from LarsH

Modified:
    hbase/trunk/hbase-server/src/main/java/org/apache/hadoop/hbase/client/package-info.java
    hbase/trunk/src/docbkx/book.xml

Modified: hbase/trunk/hbase-server/src/main/java/org/apache/hadoop/hbase/client/package-info.java
URL: http://svn.apache.org/viewvc/hbase/trunk/hbase-server/src/main/java/org/apache/hadoop/hbase/client/package-info.java?rev=1443633&r1=1443632&r2=1443633&view=diff
==============================================================================
--- hbase/trunk/hbase-server/src/main/java/org/apache/hadoop/hbase/client/package-info.java (original)
+++ hbase/trunk/hbase-server/src/main/java/org/apache/hadoop/hbase/client/package-info.java Thu Feb  7 18:01:08 2013
@@ -179,6 +179,10 @@ public class MyLittleHBaseClient {
   more methods. Additionally, there are methods for managing tables in the
   HBaseAdmin class.</p>
 
+  <p>See also the section in the HBase Reference Guide where it discusses
+  <a href="http://hbase.apache.org/book.html#client">HBase Client</a>.  It
+  has section on how to access HBase from inside your multithreaded environtment
+  how to control resources consumed client-side, etc.</p>
 </body>
 </html>
 */

Modified: hbase/trunk/src/docbkx/book.xml
URL: http://svn.apache.org/viewvc/hbase/trunk/src/docbkx/book.xml?rev=1443633&r1=1443632&r2=1443633&view=diff
==============================================================================
--- hbase/trunk/src/docbkx/book.xml (original)
+++ hbase/trunk/src/docbkx/book.xml Thu Feb  7 18:01:08 2013
@@ -1488,8 +1488,9 @@ if (!b) {
 	   <section xml:id="client.connections"><title>Connections</title>
            <para>For connection configuration information, see <xref linkend="client_dependencies" />.
          </para>
-         <para><link xlink:href="http://hbase.apache.org/apidocs/org/apache/hadoop/hbase/client/HTable.html">HTable</link>
-instances are not thread-safe.  When creating HTable instances, it is advisable to use the same <link xlink:href="http://hbase.apache.org/apidocs/org/apache/hadoop/hbase/HBaseConfiguration">HBaseConfiguration</link>
+         <para><emphasis><link xlink:href="http://hbase.apache.org/apidocs/org/apache/hadoop/hbase/client/HTable.html">HTable</link>
+                 instances are not thread-safe</emphasis>.  Only one thread use an instance of HTable at any given
+             time.  When creating HTable instances, it is advisable to use the same <link xlink:href="http://hbase.apache.org/apidocs/org/apache/hadoop/hbase/HBaseConfiguration">HBaseConfiguration</link>
 instance.  This will ensure sharing of ZooKeeper and socket instances to the RegionServers
 which is usually what you want.  For example, this is preferred:
 		<programlisting>HBaseConfiguration conf = HBaseConfiguration.create();
@@ -1505,7 +1506,16 @@ HTable table2 = new HTable(conf2, "myTab
           </para>
           <section xml:id="client.connection.pooling"><title>Connection Pooling</title>
             <para>For applications which require high-end multithreaded access (e.g., web-servers or application servers that may serve many application threads
-            in a single JVM), see <link xlink:href="http://hbase.apache.org/apidocs/org/apache/hadoop/hbase/client/HTablePool.html">HTablePool</link>.
+            in a single JVM), one solution is <link xlink:href="http://hbase.apache.org/apidocs/org/apache/hadoop/hbase/client/HTablePool.html">HTablePool</link>.
+            But as written currently, it is difficult to control client resource consumption when using HTablePool.
+            </para>
+            <para>
+                Another solution is to precreate an <classname>HConnection</classname> using
+                <programlisting>HConnectionManager.createConnection(Configuration)</programlisting> as
+                well as an <classname>ExecutorService</classname>; then use the
+                <programlisting>HTable(byte[], HConnection, ExecutorService)</programlisting>
+                constructor to create <classname>HTable</classname> instances on demand.
+                This construction is very lightweight and resources are controlled/shared if you go this route.
             </para>
           </section>
    	  </section>