ZOOKEEPER-2477: documentation should refer to Java cli shell and not C cli shell (Abraham Fine via phunt)

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

CHANGES.txt

@@ -332,6 +332,9 @@ BUGFIXES:
   ZOOKEEPER-1898: ZooKeeper Java cli shell always returns "0" as exit code
   (Abraham Fine via phunt)
 
+  ZOOKEEPER-2477: documentation should refer to Java cli shell and not
+  C cli shell (Abraham Fine via phunt)
+
 IMPROVEMENTS:
   ZOOKEEPER-2024 Major throughput improvement with mixed workloads (Kfir Lev-Ari via shralex)
 

docs/zookeeperAdmin.html

@@ -672,54 +672,12 @@ server.3=zoo3:2888:3888</pre>
 <p>Test your deployment by connecting to the hosts:</p>
 
           
-<ul>
-            
-<li>
-              
 <p>In Java, you can run the following command to execute
-              simple operations:</p>
-
-              
-<p>
-<span class="codefrag computeroutput">$ java -cp zookeeper.jar:lib/slf4j-api-1.7.5.jar:lib/slf4j-log4j12-1.7.5.jar:lib/log4j-1.2.17.jar:conf:src/java/lib/jline-2.11.jar \
-      org.apache.zookeeper.ZooKeeperMain -server 127.0.0.1:2181</span>
-</p>
-            
-</li>
-
-            
-<li>
-              
-<p>In C, you can compile either the single threaded client or
-              the multithreaded client: or n the c subdirectory in the
-              ZooKeeper sources. This compiles the single threaded
-              client:</p>
-
-              
-<p>
-<span class="codefrag computeroutput">$ make cli_st</span>
-</p>
-
-              
-<p>And this compiles the mulithreaded client:</p>
-
-              
-<p>
-<span class="codefrag computeroutput">$ make cli_mt</span>
-</p>
-            
-</li>
-          
-</ul>
-
-          
-<p>Running either program gives you a shell in which to execute
-          simple file-system-like operations. To connect to ZooKeeper with the
-          multithreaded client, for example, you would run:</p>
+          simple operations:</p>
 
           
 <p>
-<span class="codefrag computeroutput">$ cli_mt 127.0.0.1:2181</span>
+<span class="codefrag computeroutput">$ bin/zkCli.sh -server 127.0.0.1:2181</span>
 </p>
         
 </li>
@@ -1625,20 +1583,6 @@ server.3=zoo3:2888:3888</pre>
               zookeeper.ssl.authProvider=[scheme]</strong> and that provider
               will be used for secure authentication.</p>
 </dd>
-
-          
-<dt>
-<term>zookeeper.client.secure</term>
-</dt>
-<dd>
-<p>(Java system property only: <strong>zookeeper.client.secure</strong>)</p>
-<p>If you want to connect to server's secure client port, you need to
-                set this property to <strong>true</strong> on client.
-                This will connect to server using SSL with specified credentials. Note that
-                you also need to plug-in Netty client.
-              </p>
-</dd>
-
         
 </dl>
 <a name="Experimental+Options%2FFeatures"></a>

docs/zookeeperObservers.html

@@ -274,7 +274,7 @@ document.write("Last Published: " + document.lastModified);
       to add an Observer to your ZooKeeper cluster. Now you can connect to it as
       though it were an ordinary Follower. Try it out, by running:</p>
 <pre class="code">
-      bin/zkCli.sh -server localhost:2181
+      $ bin/zkCli.sh -server localhost:2181
     </pre>
 <p>
       where localhost:2181 is the hostname and port number of the Observer as

docs/zookeeperProgrammers.html

@@ -276,6 +276,11 @@ document.write("Last Published: " + document.lastModified);
 <ul class="minitoc">
 <li>
 <a href="#Java+Binding">Java Binding</a>
+<ul class="minitoc">
+<li>
+<a href="#sc_java_client_configuration">Client Configuration Parameters</a>
+</li>
+</ul>
 </li>
 <li>
 <a href="#C+Binding">C Binding</a>
@@ -284,7 +289,7 @@ document.write("Last Published: " + document.lastModified);
 <a href="#Installation">Installation</a>
 </li>
 <li>
-<a href="#Using+the+C+Client">Using the C Client</a>
+<a href="#Building+Your+Own+C+Client">Building Your Own C Client</a>
 </li>
 </ul>
 </li>
@@ -1572,7 +1577,7 @@ document.write("Last Published: " + document.lastModified);
 <p>This is a very simple example which is intended to show
         how to interact with ZooKeeper ACLs
         specifically. See <span class="codefrag filename">.../trunk/src/c/src/cli.c</span>
-        for an example of a proper C client implementation</p>
+        for an example of a C client implementation</p>
       
 </div>
 </div>
@@ -1926,6 +1931,126 @@ authProvider.2=com.f.MyAuth2
       (SESSION_EXPIRED and AUTH_FAILED), the ZooKeeper object becomes invalid.
       On a close, the two threads shut down and any further access on zookeeper
       handle is undefined behavior and should be avoided. </p>
+<a name="sc_java_client_configuration"></a>
+<h4>Client Configuration Parameters</h4>
+<p>
+            The following list contains configuration properties for the Java client. You can set any
+            of these properties using Java system properties. For server properties, please check the
+            following reference
+            <a href="zookeeperAdmin.html#sc_configuration">Server configuration section.</a>
+        
+</p>
+<dl>
+            
+<dt>
+<term>zookeeper.sasl.client</term>
+</dt>
+<dd>
+<p>Set the value to <strong>false</strong> to disable
+                    SASL authentication. Default is <strong>true</strong>.</p>
+</dd>
+            
+<dt>
+<term>zookeeper.sasl.clientconfig</term>
+</dt>
+<dd>
+<p>Specifies the context key in the JAAS login file. Default is "Client".</p>
+</dd>
+            
+<dt>
+<term>zookeeper.sasl.client.username</term>
+</dt>
+<dd>
+<p>Traditionally, a principal is divided into three parts: the primary, the instance, and the realm.
+                        The format of a typical Kerberos V5 principal is primary/instance@REALM.
+                        zookeeper.sasl.client.username specifies the primary part of the server principal. Default
+                        is "zookeeper". Instance part is derived from the server IP. Finally server's principal is
+                        username/IP@realm, where username is the value of zookeeper.sasl.client.username, IP is
+                        the server IP, and realm is the value of zookeeper.server.realm.</p>
+</dd>
+            
+<dt>
+<term>zookeeper.server.realm</term>
+</dt>
+<dd>
+<p>Realm part of the server principal. By default it is the client principal realm.</p>
+</dd>
+            
+<dt>
+<term>zookeeper.disableAutoWatchReset</term>
+</dt>
+<dd>
+<p>This switch controls whether automatic watch resetting is enabled. Clients automatically
+                        reset watches during session reconnect by default, this option allows the client to turn off
+                        this behavior by setting zookeeper.disableAutoWatchReset to <strong>true</strong>. 
+                    </p>
+</dd>
+            
+<dt>
+<term>zookeeper.client.secure</term>
+</dt>
+<dd>
+<p>
+                        If you want to connect to the server secure client port, you need to set this property to
+                        <strong>true</strong>
+                        on the client. This will connect to server using SSL with specified credentials. Note that
+                        it requires the Netty client.
+                    </p>
+</dd>
+            
+<dt>
+<term>zookeeper.clientCnxnSocket</term>
+</dt>
+<dd>
+<p>
+                        Specifies which ClientCnxnSocket to be used. Possible values are
+                        <strong>org.apache.zookeeper.ClientCnxnSocketNIO</strong>
+                        and
+                        <strong>org.apache.zookeeper.ClientCnxnSocketNetty</strong>
+                        . Default is
+                        <strong>org.apache.zookeeper.ClientCnxnSocketNIO</strong>
+                        . If you want to connect to server's secure client port, you need to set this property to
+                        <strong>org.apache.zookeeper.ClientCnxnSocketNetty</strong>
+                        on client.
+                    </p>
+</dd>
+            
+<dt>
+<term>zookeeper.ssl.keyStore.location and zookeeper.ssl.keyStore.password</term>
+</dt>
+<dd>
+<p>Specifies the file path to a JKS containing the local credentials to be used for SSL connections,
+                        and the password to unlock the file.
+                    </p>
+</dd>
+            
+<dt>
+<term>zookeeper.ssl.trustStore.location and zookeeper.ssl.trustStore.password</term>
+</dt>
+<dd>
+<p>Specifies the file path to a JKS containing the remote credentials to be used for SSL connections,
+                        and the password to unlock the file.
+                    </p>
+</dd>
+            
+<dt>
+<term>jute.maxbuffer</term>
+</dt>
+<dd>
+<p>It specifies the maximum size of the incoming data from the server. The default value is 4194304
+                        Bytes , or just 4 MB. This is really a sanity check. The ZooKeeper server is designed to store and send
+                        data on the order of kilobytes. If incoming data length is more than this value, an IOException
+                        is raised.</p>
+</dd>
+            
+<dt>
+<term>zookeeper.kinit</term>
+</dt>
+<dd>
+<p>Specifies path to kinit binary. Default is "/usr/bin/kinit".</p>
+</dd>
+        
+</dl>
 <a name="C+Binding"></a>
 <h3 class="h4">C Binding</h3>
 <p>The C binding has a single-threaded and multi-threaded library.
@@ -2074,32 +2199,9 @@ authProvider.2=com.f.MyAuth2
 </li>
         
 </ol>
-<a name="Using+the+C+Client"></a>
-<h4>Using the C Client</h4>
-<p>You can test your client by running a ZooKeeper server (see
-        instructions on the project wiki page on how to run it) and connecting
-        to it using one of the cli applications that were built as part of the
-        installation procedure. cli_mt (multithreaded, built against
-        zookeeper_mt library) is shown in this example, but you could also use
-        cli_st (singlethreaded, built against zookeeper_st library):</p>
-<p>
-<span class="codefrag command">$ cli_mt zookeeper_host:9876</span>
-</p>
-<p>This is a client application that gives you a shell for
-        executing simple ZooKeeper commands. Once successfully started
-        and connected to the server it displays a shell prompt. You
-        can now enter ZooKeeper commands. For example, to create a
-        node:</p>
-<p>
-<span class="codefrag command">&gt; create /my_new_node</span>
-</p>
-<p>To verify that the node's been created:</p>
-<p>
-<span class="codefrag command">&gt; ls /</span>
-</p>
-<p>You should see a list of node who are children of the root node
-        "/".</p>
-<p>In order to be able to use the ZooKeeper API in your application
+<a name="Building+Your+Own+C+Client"></a>
+<h4>Building Your Own C Client</h4>
+<p>In order to be able to use the ZooKeeper C API in your application
         you have to remember to</p>
 <ol>
           
@@ -2124,11 +2226,14 @@ authProvider.2=com.f.MyAuth2
 </li>
         
 </ol>
-<p>Refer to <a href="#ch_programStructureWithExample">Program Structure, with Simple Example</a>
-          for examples of usage in Java and C.
-          <em>[tbd]</em>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+<p>See <span class="codefrag filename">.../trunk/src/c/src/cli.c</span>
+          for an example of a C client implementation</p>
         
-</p>
+</div>
+</div>
 </div>
 
    

docs/zookeeperQuotas.html

@@ -224,8 +224,7 @@ document.write("Last Published: " + document.lastModified);
 	are printed in the log of the ZooKeeper. 
 	</p>
 <p>
-<span class="codefrag computeroutput">$java -cp zookeeper.jar:src/java/lib/log4j-1.2.16.jar:src/java/lib/jline-2.11.jar:conf \
-	 org.apache.zookeeper.ZooKeeperMain -server host:port</span>
+<span class="codefrag computeroutput">$ bin/zkCli.sh -server host:port</span>
 </p>
 <p> The above command gives you a command line option of using quotas.</p>
 <a name="Setting+Quotas"></a>

docs/zookeeperStarted.html

@@ -335,54 +335,8 @@ clientPort=2181
       more details.</p>
 <a name="sc_ConnectingToZooKeeper"></a>
 <h3 class="h4">Connecting to ZooKeeper</h3>
-<p>Once ZooKeeper is running, you have several options for connection
-      to it:</p>
-<ul>
-        
-<li>
-          
-<p>
-<strong>Java</strong>: Use</p>
-
-          
-<pre class="code">bin/zkCli.sh -server 127.0.0.1:2181</pre>
-
-          
+<pre class="code">$ bin/zkCli.sh -server 127.0.0.1:2181</pre>
 <p>This lets you perform simple, file-like operations.</p>
-        
-</li>
-
-        
-<li>
-          
-<p>
-<strong>C</strong>: compile cli_mt
-          (multi-threaded) or cli_st (single-threaded) by running
-          <span class="codefrag command">make cli_mt</span> or <span class="codefrag command">make
-          cli_st</span> in
-          the <strong>src/c</strong> subdirectory in
-          the ZooKeeper sources. See the README contained within
-          <strong>src/c</strong> for full details.</p>
-
-          
-<p>You can run the program
-          from <strong>src/c</strong> using:</p>
-
-          
-<pre class="code">LD_LIBRARY_PATH=. cli_mt 127.0.0.1:2181</pre>
-
-          
-<p>or</p>
-
-          
-<pre class="code">LD_LIBRARY_PATH=. cli_st 127.0.0.1:2181</pre>
-          
-<p>This will give you a simple shell to execute file
-          system like operations on ZooKeeper.</p>
-        
-</li>
-      
-</ul>
 <p>Once you have connected, you should see something like:
         </p>
 <pre class="code">

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

@@ -302,34 +302,10 @@ server.3=zoo3:2888:3888</programlisting>
         <listitem>
           <para>Test your deployment by connecting to the hosts:</para>
 
-          <itemizedlist>
-            <listitem>
-              <para>In Java, you can run the following command to execute
-              simple operations:</para>
-
-              <para><computeroutput>$ java -cp zookeeper.jar:lib/slf4j-api-1.7.5.jar:lib/slf4j-log4j12-1.7.5.jar:lib/log4j-1.2.17.jar:conf:src/java/lib/jline-2.11.jar \
-      org.apache.zookeeper.ZooKeeperMain -server 127.0.0.1:2181</computeroutput></para>
-            </listitem>
-
-            <listitem>
-              <para>In C, you can compile either the single threaded client or
-              the multithreaded client: or n the c subdirectory in the
-              ZooKeeper sources. This compiles the single threaded
-              client:</para>
-
-              <para><computeroutput>$ make cli_st</computeroutput></para>
-
-              <para>And this compiles the mulithreaded client:</para>
-
-              <para><computeroutput>$ make cli_mt</computeroutput></para>
-            </listitem>
-          </itemizedlist>
-
-          <para>Running either program gives you a shell in which to execute
-          simple file-system-like operations. To connect to ZooKeeper with the
-          multithreaded client, for example, you would run:</para>
+          <para>In Java, you can run the following command to execute
+          simple operations:</para>
 
-          <para><computeroutput>$ cli_mt 127.0.0.1:2181</computeroutput></para>
+          <para><computeroutput>$ bin/zkCli.sh -server 127.0.0.1:2181</computeroutput></para>
         </listitem>
       </orderedlist>
     </section>

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

@@ -102,7 +102,7 @@
       to add an Observer to your ZooKeeper cluster. Now you can connect to it as
       though it were an ordinary Follower. Try it out, by running:</para>
     <programlisting>
-      bin/zkCli.sh -server localhost:2181
+      $ bin/zkCli.sh -server localhost:2181
     </programlisting>
     <para>
       where localhost:2181 is the hostname and port number of the Observer as

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

@@ -1021,7 +1021,7 @@
       <note><para>This is a very simple example which is intended to show
         how to interact with ZooKeeper ACLs
         specifically. See <filename>.../trunk/src/c/src/cli.c</filename>
-        for an example of a proper C client implementation</para>
+        for an example of a C client implementation</para>
       </note>
 
       <programlisting>
@@ -1593,33 +1593,9 @@ authProvider.2=com.f.MyAuth2
       </section>
 
       <section>
-        <title>Using the C Client</title>
+        <title>Building Your Own C Client</title>
 
-        <para>You can test your client by running a ZooKeeper server (see
-        instructions on the project wiki page on how to run it) and connecting
-        to it using one of the cli applications that were built as part of the
-        installation procedure. cli_mt (multithreaded, built against
-        zookeeper_mt library) is shown in this example, but you could also use
-        cli_st (singlethreaded, built against zookeeper_st library):</para>
-
-        <para><command>$ cli_mt zookeeper_host:9876</command></para>
-
-        <para>This is a client application that gives you a shell for
-        executing simple ZooKeeper commands. Once successfully started
-        and connected to the server it displays a shell prompt. You
-        can now enter ZooKeeper commands. For example, to create a
-        node:</para>
-
-        <para><command>&gt; create /my_new_node</command></para>
-
-        <para>To verify that the node's been created:</para>
-
-        <para><command>&gt; ls /</command></para>
-
-        <para>You should see a list of node who are children of the root node
-        "/".</para>
-
-        <para>In order to be able to use the ZooKeeper API in your application
+        <para>In order to be able to use the ZooKeeper C API in your application
         you have to remember to</para>
 
         <orderedlist>
@@ -1639,10 +1615,9 @@ authProvider.2=com.f.MyAuth2
           </listitem>
         </orderedlist>
 
-        <para>Refer to <xref linkend="ch_programStructureWithExample"/>
-          for examples of usage in Java and C.
-          <emphasis>[tbd]</emphasis>
-        </para>
+        <note><para>See <filename>.../trunk/src/c/src/cli.c</filename>
+          for an example of a C client implementation</para>
+        </note>
       </section>
     </section>
   </section>

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

@@ -43,8 +43,7 @@
 	ZooKeeper prints <emphasis>WARN</emphasis> messages if users exceed the quota assigned to them. The messages 
 	are printed in the log of the ZooKeeper. 
 	</para>
-	<para><computeroutput>$java -cp zookeeper.jar:src/java/lib/log4j-1.2.16.jar:src/java/lib/jline-2.11.jar:conf \
-	 org.apache.zookeeper.ZooKeeperMain -server host:port</computeroutput></para> 
+	<para><computeroutput>$ bin/zkCli.sh -server host:port</computeroutput></para>
 	 <para> The above command gives you a command line option of using quotas.</para>
 	 <section>
 	 <title>Setting Quotas</title>

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

@@ -164,39 +164,10 @@ clientPort=2181
     <section id="sc_ConnectingToZooKeeper">
       <title>Connecting to ZooKeeper</title>
 
-      <para>Once ZooKeeper is running, you have several options for connection
-      to it:</para>
+      <programlisting>$ bin/zkCli.sh -server 127.0.0.1:2181</programlisting>
 
-      <itemizedlist>
-        <listitem>
-          <para><emphasis role="bold">Java</emphasis>: Use</para>
-
-          <programlisting>bin/zkCli.sh -server 127.0.0.1:2181</programlisting>
-
-          <para>This lets you perform simple, file-like operations.</para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold">C</emphasis>: compile cli_mt
-          (multi-threaded) or cli_st (single-threaded) by running
-          <command>make cli_mt</command> or <command>make
-          cli_st</command> in
-          the <emphasis role="bold">src/c</emphasis> subdirectory in
-          the ZooKeeper sources. See the README contained within
-          <emphasis role="bold">src/c</emphasis> for full details.</para>
-
-          <para>You can run the program
-          from <emphasis role="bold">src/c</emphasis> using:</para>
-
-          <programlisting>LD_LIBRARY_PATH=. cli_mt 127.0.0.1:2181</programlisting>
+      <para>This lets you perform simple, file-like operations.</para>
 
-          <para>or</para>
-
-          <programlisting>LD_LIBRARY_PATH=. cli_st 127.0.0.1:2181</programlisting>
-          <para>This will give you a simple shell to execute file
-          system like operations on ZooKeeper.</para>
-        </listitem>
-      </itemizedlist>
       <para>Once you have connected, you should see something like:
         </para>
       <programlisting>