HBASE-3655 Revision to HBase book, more examples in data model, more metrics, more performance -- part one

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

src/docbkx/book.xml

@@ -319,7 +319,8 @@ Tables in HBase are initially created with one region by default.  For bulk impo
           <title>Get/Scan</title>
 
           <para>Gets are implemented on top of Scans. The below discussion of
-          Get applies equally to Scans.</para>
+            <link xlink:href="http://hbase.apache.org/docs/current/api/org/apache/hadoop/hbase/client/Get.html">Get</link> applies equally to <link
+            xlink:href="http://hbase.apache.org/docs/current/api/org/apache/hadoop/hbase/client/Scan.html">Scans</link>.</para>
 
           <para>By default, i.e. if you specify no explicit version, when
           doing a <literal>get</literal>, the cell whose version has the
@@ -343,6 +344,29 @@ Tables in HBase are initially created with one region by default.  For bulk impo
               desired version and set the max versions to 1.</para>
             </listitem>
           </itemizedlist>
+
+        </section>
+        <section>
+        <title>Default Get Example</title>
+        <para>The following Get will only retrieve the current version of the row
+        <programlisting>
+        Get get = new Get( Bytes.toBytes("row1") );
+        Result r = htable.get(get);
+        byte[] b = r.getValue( Bytes.toBytes("cf"), Bytes.toBytes("attr") );  // returns current version of value      
+        </programlisting>
+        </para>
+        </section>
+        <section>
+        <title>Versioned Get Example</title>
+        <para>The following Get will return the last 3 versions of the row.
+        <programlisting>
+        Get get = new Get( Bytes.toBytes("row1") );
+        get.setMaxVersions(3);  // will return last 3 versions of row
+        Result r = htable.get(get);
+        byte[] b = r.getValue( Bytes.toBytes("cf"), Bytes.toBytes("attr") );  // returns current version of value
+        List&lt;KeyValue&gt; kv = r.getColumn( Bytes.toBytes("cf"), Bytes.toBytes("attr") );  // returns all versions of this column       
+        </programlisting>
+        </para>
         </section>
 
         <section>
@@ -358,6 +382,27 @@ Tables in HBase are initially created with one region by default.  For bulk impo
           <para>To overwrite an existing value, do a put at exactly the same
           row, column, and version as that of the cell you would
           overshadow.</para>
+          <section>
+          <title>Implicit Version Example</title>
+          <para>The following Put will be implicitly versioned by HBase with the current time.
+          <programlisting>
+          Put put = new Put(Bytes.toBytes(row));
+          put.add(Bytes.toBytes("cf"), Bytes.toBytes("attr1"), Bytes.toBytes( data));
+          htable.put(put);
+          </programlisting>
+          </para>
+          </section>
+          <section>
+          <title>Explicit Version Example</title>
+          <para>The following Put has the version timestamp explicitly set.
+          <programlisting>
+          Put put = new Put( Bytes.toBytes( row ) );
+          long explicitTimeInMs = 555;  // just an example
+          put.add(Bytes.toBytes("cf"), Bytes.toBytes("attr1"), explicitTimeInMs, Bytes.toBytes( data));
+          htable.put(put);
+          </programlisting>
+          </para>
+          </section>
         </section>
 
         <section>

src/docbkx/configuration.xml

@@ -259,15 +259,21 @@ of all regions.
       <section xml:id="client_dependencies"><title>Client configuration and dependencies connecting to an HBase cluster</title>
 
       <para>
-        Since the HBase Master may move around, clients bootstrap by looking ZooKeeper.  Thus clients
+          Since the HBase Master may move around, clients bootstrap by looking to ZooKeeper for
-        require the ZooKeeper quorum information in a <filename>hbase-site.xml</filename> that
+          current critical locations.  ZooKeeper is where all these values are kept.  Thus clients
-        is on their <varname>CLASSPATH</varname>.</para>
+          require the location of the ZooKeeper ensemble information before they can do anything else.
+          Usually this the ensemble location is kept out in the <filename>hbase-site.xml</filename> and
+          is picked up by the client from the <varname>CLASSPATH</varname>.</para>
+
         <para>If you are configuring an IDE to run a HBase client, you should
-        include the <filename>conf/</filename> directory on your classpath.
+            include the <filename>conf/</filename> directory on your classpath so
+            <filename>hbase-site.xml</filename> settings can be found (or
+            add <filename>src/test/resources</filename> to pick up the hbase-site.xml
+            used by tests).
       </para>
       <para>
-      Minimally, a client of HBase needs the hbase, hadoop, log4j, commons-logging, and zookeeper jars
+          Minimally, a client of HBase needs the hbase, hadoop, log4j, commons-logging, commons-lang,
-      in its <varname>CLASSPATH</varname> connecting to a cluster.
+          and zookeeper jars in its <varname>CLASSPATH</varname> connecting to a cluster.
       </para>
         <para>
           An example basic <filename>hbase-site.xml</filename> for client only
@@ -283,9 +289,31 @@ of all regions.
     </description>
   </property>
 </configuration>
-]]>
+]]></programlisting>
-          </programlisting>
         </para>
+        <section>
+        <title>Java client configuration connecting to an HBase cluster</title>
+        <subtitle>How Java reads <filename>hbase-site.xml</filename> content</subtitle>
+        <para>The configuration used by a client is kept
+        in an <link xlink:href="http://hbase.apache.org/apidocs/org/apache/hadoop/hbase/HBaseConfiguration">HBaseConfiguration</link> instance.
+        Through the factory method on HBaseConfiguration...
+        <programlisting>Configuration config = HBaseConfiguration.create();</programlisting>        
+        .. a client will pick up a configuration sourced from the first <filename>hbase-site.xml</filename> found on
+        the client's <varname>CLASSPATH</varname>, if one is present
+        (We'll also factor in any <filename>hbase-default.xml</filename> found; an hbase-default.xml ships inside
+        the <filename>hbase.X.X.X.jar</filename>). 
+        It is also possible to specify configuration directly without having to read from a
+        <filename>hbase-site.xml</filename>.  For examplt to set the
+        <link linkend="zookeeper">zookeeper</link> ensemble for the cluster programmatically do as follows...
+        <programlisting>Configuration config = HBaseConfiguration.create();
+        config.set("hbase.zookeeper.quorum", "localhost");  // we are running zookeeper locally
+        </programlisting>    
+        If multiple <link linkend="zookeeper">zookeeper</link> instances make up your zookeeper ensemble,
+        they may be specified in a comma-list (just as in the <filename>hbase-site.xml</filename> file).
+        This populated Configuration instance can then be passed to an 
+        <link xlink:href="http://hbase.apache.org/apidocs/org/apache/hadoop/hbase/client/HTable.html">HTable</link> instance via the overloaded constructor.     
+        </para>
+        </section>
     </section>
 
   </chapter>