ZOOKEEPER-1703: Added instructions on how to run the example code

Author: Andor Molnar <andor@cloudera.com>

Reviewers: Patrick Hunt <phunt@apache.org>

Closes #400 from dolphy17/master and squashes the following commits:

16e26f92 [Andor Molnar] ZOOKEEPER-1703: Set classpath the way that the book suggests
45ff9816 [Andor Molnar] ZOOKEEPER-1703: Added instructions on how to run the example code

Change-Id: I08467785ae3cdd75fd38c1e6d82439e4718d83fe
(cherry picked from commit 98ff4f9dd9b67503ffa3f5852df499a46efd6241)
Signed-off-by: Patrick Hunt <phunt@apache.org>

docs/zookeeperAdmin.html

@@ -1145,11 +1145,15 @@ server.3=zoo3:2888:3888</pre>
 </dt>
 <dd>
 <p>(Java system property: <strong>zookeeper.snapCount</strong>)</p>
-<p>ZooKeeper logs transactions to a transaction
-              log. After snapCount transactions are written to a log
-              file a snapshot is started and a new transaction log
-              file is created. The default snapCount is
-              100,000.</p>
+<p>ZooKeeper records its transactions using snapshots and
+              a transaction log (think write-ahead log).The number of
+              transactions recorded in the transaction log before a snapshot
+              can be taken (and the transaction log rolled) is determined
+              by snapCount. In order to prevent all of the machines in the quorum
+              from taking a snapshot at the same time, each ZooKeeper server
+              will take a snapshot when the number of transactions in the transaction log
+              reaches a runtime generated random value in the [snapCount/2+1, snapCount] 
+              range.The default snapCount is 100,000.</p>
 </dd>
 
           
@@ -1446,6 +1450,25 @@ server.3=zoo3:2888:3888</pre>
               </pre>
 </dd>
 
+          
+<dt>
+<term>ipReachableTimeout</term>
+</dt>
+<dd>
+<p>(Java system property: <strong>zookeeper.ipReachableTimeout</strong>)</p>
+<p>
+<strong>New in 3.4.11:</strong>
+                Set this timeout value for IP addresses reachable checking when hostname is resolved, as mesured in
+                milliseconds.
+                By default, ZooKeeper will use the first IP address of the hostname(without any reachable checking).
+                When zookeeper.ipReachableTimeout is set(larger than 0), ZooKeeper will will try to pick up the first 
+                IP address which is reachable. This is done by calling Java API InetAddress.isReachable(long timeout)
+                function, in which this timeout value is used. If none of such reachable IP address can be found, the
+                first IP address of the hostname will be used anyway.
+              </p>
+</dd>
+
+          
 <dt>
 <term>tcpKeepAlive</term>
 </dt>
@@ -1453,15 +1476,20 @@ server.3=zoo3:2888:3888</pre>
 <p>(Java system property: <strong>zookeeper.tcpKeepAlive</strong>)</p>
 <p>
 <strong>New in 3.4.11:</strong>
-              Sets the keepAlive flag on the sockets used by quorum members to perform elections.
-              This will allow for connections between quorum members to remain up when there is 
-              network infrastructure that may otherwise terminate them. Some NATs and firewalls may
-              terminate or lose state for long running or idle connections. </p>
-              Enabling this option relies on OS level settings to work properly, check your operating
-              system's options regarding TCP keepalive for more information.
-              Defaults to <strong>false</strong>.</p>
+                Setting this to true sets the TCP keepAlive flag on the
+                sockets used by quorum members to perform elections.
+                This will allow for connections between quorum members to
+                remain up when there is network infrastructure that may
+                otherwise break them. Some NATs and firewalls may terminate
+                or lose state for long running or idle connections.</p>
+<p> Enabling this option relies on OS level settings to work
+                properly, check your operating system's options regarding TCP
+                keepalive for more information.  Defaults to
+                <strong>false</strong>.
+              </p>
 </dd>
 
+        
 </dl>
 <p></p>
 <a name="sc_authOptions"></a>
@@ -2045,7 +2073,7 @@ imok
 
         
 <dt>
-<term>incorrect placement of transasction log</term>
+<term>incorrect placement of transaction log</term>
 </dt>
 <dd>
 <p>The most performance critical part of ZooKeeper is the

docs/zookeeperTutorial.html

@@ -216,7 +216,18 @@ document.write("Last Published: " + document.lastModified);
 <a href="#sc_producerConsumerQueues">Producer-Consumer Queues</a>
 </li>
 <li>
-<a href="#sc_sourceListing">Complete Source Listing</a>
+<a href="#Complete+example">Complete example</a>
+<ul class="minitoc">
+<li>
+<a href="#Queue+test">Queue test</a>
+</li>
+<li>
+<a href="#Barrier+test">Barrier test</a>
+</li>
+<li>
+<a href="#sc_sourceListing">Source Listing</a>
+</li>
+</ul>
 </li>
 </ul>
 </div>
@@ -546,9 +557,37 @@ from each one.</p>
 </pre>
 </div>
 
-<a name="sc_sourceListing"></a>
-<h2 class="h3">Complete Source Listing</h2>
+
+<a name="Complete+example"></a>
+<h2 class="h3">Complete example</h2>
 <div class="section">
+<p>
+In the following section you can find a complete command line application to demonstrate the above mentioned
+recipes. Use the following command to run it.
+</p>
+<pre class="code">
+ZOOBINDIR="[path_to_distro]/bin"
+. "$ZOOBINDIR"/zkEnv.sh
+java SyncPrimitive [Test Type] [ZK server] [No of elements] [Client type]
+</pre>
+<a name="Queue+test"></a>
+<h3 class="h4">Queue test</h3>
+<p>Start a producer to create 100 elements</p>
+<pre class="code">
+java SyncPrimitive qTest localhost 100 p
+</pre>
+<p>Start a consumer to consume 100 elements</p>
+<pre class="code">
+java SyncPrimitive qTest localhost 100 c
+</pre>
+<a name="Barrier+test"></a>
+<h3 class="h4">Barrier test</h3>
+<p>Start a barrier with 2 participants (start as many times as many participants you'd like to enter)</p>
+<pre class="code">
+java SyncPrimitive bTest localhost 2
+</pre>
+<a name="sc_sourceListing"></a>
+<h3 class="h4">Source Listing</h3>
 <div class="note example">
 <div class="label">SyncPrimitive.Java</div>
 <div class="content">
@@ -765,15 +804,19 @@ public class SyncPrimitive implements Watcher {
                         mutex.wait();
                     } else {
                         Integer min = new Integer(list.get(0).substring(7));
+                        String minNode = list.get(0);
                         for(String s : list){
                             Integer tempValue = new Integer(s.substring(7));
                             //System.out.println("Temporary value: " + tempValue);
-                            if(tempValue &lt; min) min = tempValue;
+                            if(tempValue &lt; min) {
+                                min = tempValue;
+                                minNode = s;
+                            }
                         }
-                        System.out.println("Temporary value: " + root + "/element" + min);
-                        byte[] b = zk.getData(root + "/element" + min,
-                                    false, stat);
-                        zk.delete(root + "/element" + min, 0);
+                        System.out.println("Temporary value: " + root + "/" + minNode);
+                        byte[] b = zk.getData(root + "/" + minNode,
+                        false, stat);
+                        zk.delete(root + "/" + minNode, 0);
                         ByteBuffer buffer = ByteBuffer.wrap(b);
                         retvalue = buffer.getInt();
 

src/docs/src/documentation/content/xdocs/zookeeperTutorial.xml

@@ -361,7 +361,41 @@ from each one.</para>
 </programlisting>
  
 </section>
-<section id="sc_sourceListing"><title>Complete Source Listing</title>
+
+<section>
+<title>Complete example</title>
+<para>
+In the following section you can find a complete command line application to demonstrate the above mentioned
+recipes. Use the following command to run it.
+</para>
+<programlisting>
+ZOOBINDIR="[path_to_distro]/bin"
+. "$ZOOBINDIR"/zkEnv.sh
+java SyncPrimitive [Test Type] [ZK server] [No of elements] [Client type]
+</programlisting>
+
+<section>
+<title>Queue test</title>
+<para>Start a producer to create 100 elements</para>
+<programlisting>
+java SyncPrimitive qTest localhost 100 p
+</programlisting>
+
+<para>Start a consumer to consume 100 elements</para>
+<programlisting>
+java SyncPrimitive qTest localhost 100 c
+</programlisting>
+</section>
+
+<section>
+<title>Barrier test</title>
+<para>Start a barrier with 2 participants (start as many times as many participants you'd like to enter)</para>
+<programlisting>
+java SyncPrimitive bTest localhost 2
+</programlisting>
+</section>
+
+<section id="sc_sourceListing"><title>Source Listing</title>
 <example id="eg_SyncPrimitive_java">
 <title>SyncPrimitive.Java</title>
 <programlisting>
@@ -574,15 +608,19 @@ public class SyncPrimitive implements Watcher {
                         mutex.wait();
                     } else {
                         Integer min = new Integer(list.get(0).substring(7));
+                        String minNode = list.get(0);
                         for(String s : list){
                             Integer tempValue = new Integer(s.substring(7));
                             //System.out.println("Temporary value: " + tempValue);
-                            if(tempValue &lt; min) min = tempValue;
+                            if(tempValue &lt; min) {
+                                min = tempValue;
+                                minNode = s;
+                            }
                         }
-                        System.out.println("Temporary value: " + root + "/element" + min);
-                        byte[] b = zk.getData(root + "/element" + min,
-                                    false, stat);
-                        zk.delete(root + "/element" + min, 0);
+                        System.out.println("Temporary value: " + root + "/" + minNode);
+                        byte[] b = zk.getData(root + "/" + minNode,
+                        false, stat);
+                        zk.delete(root + "/" + minNode, 0);
                         ByteBuffer buffer = ByteBuffer.wrap(b);
                         retvalue = buffer.getInt();
 
@@ -669,7 +707,6 @@ public class SyncPrimitive implements Watcher {
 }
 </programlisting></example>
 </section>
+</section>
 
 </article>
-
-