Mailing-List: contact dev-help@zookeeper.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@zookeeper.apache.org
Date: Tue, 14 Mar 2017 18:27:41 +0000 (UTC)
From: "ASF GitHub Bot (JIRA)" <jira@apache.org>
To: dev@zookeeper.apache.org
Message-ID: <JIRA.12405821.1223307334000.17507.1489516061714@Atlassian.JIRA>
In-Reply-To: <JIRA.12405821.1223307334000@Atlassian.JIRA>
References: <JIRA.12405821.1223307334000@Atlassian.JIRA> <JIRA.12405821.1223307334955@jira-lw-us.apache.org>
Subject: [jira] [Commented] (ZOOKEEPER-169) Content needed: "Connecting to
 ZooKeeper"
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit
archived-at: Tue, 14 Mar 2017 18:27:46 -0000


    [ https://issues.apache.org/jira/browse/ZOOKEEPER-169?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15924747#comment-15924747 ] 

ASF GitHub Bot commented on ZOOKEEPER-169:
------------------------------------------

Github user SimplyFox commented on a diff in the pull request:

    https://github.com/apache/zookeeper/pull/189#discussion_r105990456
  
    --- Diff: src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml ---
    @@ -1714,7 +1714,115 @@ public abstract class ServerAuthenticationProvider implements AuthenticationProv
         <section id="sc_connectingToZk">
           <title>Connecting to ZooKeeper</title>
     
    -      <para></para>
    +      <para>Before we begin, you will have to set up a running Zookeeper server so that we can start developing the client. For C client bindings, we will be using the multithreaded library(zookeeper_mt) with a simple example written in C. To establish a connection with Zookeeper server, we make use of C API - <emphasis>zookeeper_init</emphasis> with the following signature:</para>
    +
    +      <programlisting><emphasis>int</emphasis> <emphasis>zookeeper_init</emphasis>(<emphasis>const</emphasis> <emphasis>char</emphasis> *host, watcher_fn fn, <emphasis>int</emphasis> recv_timeout, <emphasis>const</emphasis> clientid_t *clientid, <emphasis>void</emphasis> *context, <emphasis>int</emphasis> flags);</programlisting>
    +
    +      <variablelist>
    +        <varlistentry>
    +          <term>*host</term>
    +            <listitem>
    +              <para>Connection string to zookeeper server in the format of host:port. If there are multiple servers, use comma as separator after specifying the host:port pairs. Eg: "127.0.0.1:2181,127.0.0.1:3001,127.0.0.1:3002"</para>
    +            </listitem>
    +        </varlistentry>
    +
    +        <varlistentry>
    +          <term>fn</term>
    +          <listitem>
    +              <para>Watcher function to process events when a notification is triggered.</para>
    +          </listitem>
    +        </varlistentry>
    +
    +        <varlistentry>
    +          <term>recv_timeout</term>
    +          <listitem>
    +              <para>Session expiration time in milliseconds.</para>
    +          </listitem>
    +        </varlistentry>
    +
    +        <varlistentry>
    +          <term>*clientid</term>
    +          <listitem>
    +              <para>We can specify 0 for a new session. If a session has already establish previously, we could provide that client ID and it would reconnect to that previous session.</para>
    +          </listitem>
    +        </varlistentry>
    +
    +        <varlistentry>
    +          <term>*context</term>
    +          <listitem>
    +              <para>Context object that can be associated with the zkhandle_t handler. If it is not used, we can set it to 0.</para>
    +          </listitem>
    +        </varlistentry>
    +
    +        <varlistentry>
    +          <term>flags</term>
    +          <listitem>
    +              <para>In an initiation, we can leave it for 0.</para>
    +          </listitem>
    +        </varlistentry>
    +      </variablelist>
    +
    +      <para>We will demonstrate client that outputs "Connected to Zookeeper" after successful connection or an error message otherwise. Let's call the following code <emphasis>zkClient.cc</emphasis> :</para>
    +      <programlisting>
    +#include &lt;stdio.h>
    +#include &lt;zookeeper/zookeeper.h>
    +#include &lt;errno.h>
    +using namespace std;
    +
    +// Keeping track of the connection state
    +static int connected = 0;
    +static int expired   = 0;
    +
    +// *zkHandler handles the connection with Zookeeper
    +static zhandle_t *zkHandler;
    +
    +// watcher function would process events
    +void watcher(zhandle_t *zkH, int type, int state, const char *path, void *watcherCtx)
    +{
    +    if (type == ZOO_SESSION_EVENT) {
    +
    +        // state refers to states of zookeeper connection.
    +        // To keep it simple, we would demonstrate these 3: ZOO_EXPIRED_SESSION_STATE, ZOO_CONNECTED_STATE, ZOO_NOTCONNECTED_STATE
    +        // If you are using ACL, you should be aware of an authentication failure state - ZOO_AUTH_FAILED_STATE
    +        if (state == ZOO_CONNECTED_STATE) {
    +            connected = 1;
    +        } else if (state == ZOO_NOTCONNECTED_STATE ) {
    +            connected = 0;
    +        } else if (state == ZOO_EXPIRED_SESSION_STATE) {
    +            expired = 1;
    +            connected = 0;
    +            zookeeper_close(zkH);
    +        }
    +    }
    +}
    +
    +int main(){
    +    zoo_set_debug_level(ZOO_LOG_LEVEL_DEBUG);
    +
    +    // zookeeper_init returns the handler upon a successful connection, null otherwise
    +    zkHandler = zookeeper_init("localhost:2181", watcher, 10000, 0, 0, 0);
    +    
    +    if (!zkHandler) {
    +        return errno;
    +    }else{
    +        printf("Connection established with Zookeeper. \n");
    +    }
    +
    +    // Close Zookeeper connection
    +    zookeeper_close(zkHandler);
    +
    +    return 0;
    +}
    +      </programlisting>
    +
    +      <para>Compile the code with the multithreaded library mentioned before.</para>
    +      <para><command>&gt; g++ -Iinclude/ zkClient.cpp -lzookeeper_mt -o Client</command></para>
    --- End diff --
    
    Btw, I tested the code, and zoo_init doesn't seem to validate the port number. Given an invalid hostname, the zkhandler wont initialize. But given a wrong port number, it'd still work. Should I report it as a bug? or just specify in the documentation that a valid zookeeper port should be given?


> Content needed: "Connecting to ZooKeeper"
> -----------------------------------------
>
>                 Key: ZOOKEEPER-169
>                 URL: https://issues.apache.org/jira/browse/ZOOKEEPER-169
>             Project: ZooKeeper
>          Issue Type: Sub-task
>          Components: documentation
>            Reporter: Robbie Scott
>   Original Estimate: 4h
>  Remaining Estimate: 4h
>
> We need the content which describes how to a client should connect to a zookeeper server. Ideally this would have pseudo code describing any lead-up (for example resource allocation, etc),  a few lines of sample code in Java, and a few parallel lines in C. 
> Any commentary would be highly appreciated. Stuff like, "You can open an unlimited number of ZooKeeper connections because..." or "Opening too many connections to ZooKeeper is not advisable because..." -- in short, anything that is not obvious to the new ZooKeeper developer. 


--
This message was sent by Atlassian JIRA
(v6.3.15#6346)