HBASE-11779 Document the new requirement to set JAVA_HOME before starting HBase (Misty Stanley-Jones)

src/main/docbkx/configuration.xml

@@ -62,6 +62,11 @@
         <para>Script for Windows and Linux / Unix environments to set up the working environment for
         HBase, including the location of Java, Java options, and other environment variables. The
         file contains many commented-out examples to provide guidance.</para>
+        <note>
+          <para>In HBase 0.98.5 and newer, you must set <envar>JAVA_HOME</envar> on each node of
+            your cluster. <filename>hbase-env.sh</filename> provides a handy mechanism to do
+            this.</para>
+        </note>
       </listitem>
     </varlistentry>
     <varlistentry>
@@ -177,6 +182,12 @@
       </tgroup>
     </table>
 
+    <note>
+      <para>In HBase 0.98.5 and newer, you must set <envar>JAVA_HOME</envar> on each node of
+        your cluster. <filename>hbase-env.sh</filename> provides a handy mechanism to do
+        this.</para>
+    </note>
+    
     <variablelist
       xml:id="os">
       <title>Operating System Utilities</title>
@@ -1187,27 +1198,17 @@ example9
         xml:id="hbase_env">
         <title><filename>hbase-env.sh</filename></title>
 
-        <para>Below we use a <command>diff</command> to show the differences from default in the
-            <filename>hbase-env.sh</filename> file. Here we are setting the HBase heap to be 4G
-          instead of the default 1G.</para>
+        <para>The following lines in the <filename>hbase-env.sh</filename> file show how to set the
+            <envar>JAVA_HOME</envar> environment variable (required for HBase 0.98.5 and newer) and
+          set the heap to 4 GB (rather than the default value of 1 GB). If you copy and paste this
+          example, be sure to adjust the <envar>JAVA_HOME</envar> to suit your environment.</para>
 
         <screen language="bourne">
+# The java implementation to use.
+export JAVA_HOME=/usr/java/jdk1.7.0/          
 
-$ git diff hbase-env.sh
-diff --git a/conf/hbase-env.sh b/conf/hbase-env.sh
-index e70ebc6..96f8c27 100644
---- a/conf/hbase-env.sh
-+++ b/conf/hbase-env.sh
-@@ -31,7 +31,7 @@ export JAVA_HOME=/usr/lib//jvm/java-6-sun/
- # export HBASE_CLASSPATH=
-
- # The maximum amount of heap to use, in MB. Default is 1000.
--# export HBASE_HEAPSIZE=1000
-+export HBASE_HEAPSIZE=4096
-
- # Extra Java runtime options.
- # Below are what we set by default.  May only work with SUN JVM.
-
+# The maximum amount of heap to use, in MB. Default is 1000.
+export HBASE_HEAPSIZE=4096
         </screen>
 
         <para>Use <command>rsync</command> to copy the content of the <filename>conf</filename>

src/main/docbkx/getting_started.xml

@@ -33,9 +33,9 @@
   <section>
     <title>Introduction</title>
 
-    <para><xref
-        linkend="quickstart" /> will get you up and running on a single-node, standalone instance of
-      HBase. </para>
+    <para><xref linkend="quickstart"/> will get you up and running on a single-node, standalone
+      instance of HBase, followed by a pseudo-distributed single-machine instance, and finally a
+      fully-distributed cluster. </para>
   </section>
 
   <section
@@ -116,6 +116,26 @@ $ tar xzvf hbase-<![CDATA[<?eval ${project.version}?>]]>-hadoop2-bin.tar.gz
 $ cd hbase-<![CDATA[<?eval ${project.version}?>]]>-hadoop2/
           </screen>
         </step>
+        <step>
+          <para>For HBase 0.98.5 and later, you are required to set the <envar>JAVA_HOME</envar>
+            environment variable before starting HBase. Prior to 0.98.5, HBase attempted to detect
+            the location of Java if the variables was not set. You can set the variable via your
+            operating system's usual mechanism, but HBase provides a central mechanism,
+              <filename>conf/hbase-env.sh</filename>. Edit this file, uncomment the line starting
+            with <literal>JAVA_HOME</literal>, and set it to the appropriate location for your
+            operating system. The <envar>JAVA_HOME</envar> variable should be set to a directory
+            which contains the executable file <filename>bin/java</filename>. Most modern Linux
+            operating systems provide a mechanism, such as /usr/bin/alternatives on RHEL or CentOS,
+            for transparently switching between versions of executables such as Java. In this case,
+            you can set <envar>JAVA_HOME</envar> to the directory containing the symbolic link to
+              <filename>bin/java</filename>, which is usually <filename>/usr</filename>.</para>
+          <screen>JAVA_HOME=/usr</screen>
+          <note>
+            <para>These instructions assume that each node of your cluster uses the same
+              configuration. If this is not the case, you may need to set <envar>JAVA_HOME</envar>
+              separately for each node.</para>
+          </note>
+        </step>
         <step>
           <para>Edit <filename>conf/hbase-site.xml</filename>, which is the main HBase configuration
             file. At this time, you only need to specify the directory on the local filesystem where