zookeeper-client/zookeeper-client-c/README

                     Zookeeper C client library 


This package provides a C client interface to Zookeeper server.

For the latest information about ZooKeeper, please visit our website at:
   http://zookeeper.apache.org/
and our wiki, at:
   https://cwiki.apache.org/confluence/display/ZOOKEEPER

Full documentation for this release can also be found in ../../docs/index.html


OVERVIEW

The client supports two types of APIs -- synchronous and asynchronous.

Asynchronous API provides non-blocking operations with completion callbacks and 
relies on the application to implement event multiplexing on its behalf.

On the other hand, Synchronous API provides a blocking flavor of
zookeeper operations and runs its own event loop in a separate thread.

Sync and Async APIs can be mixed and matched within the same application.

The package includes two shared libraries: zookeeper_st and
zookeeper_mt. The former only provides the Async API and is not
thread-safe. The only reason this library exists is to support the
platforms were pthread library is not available or unstable
(i.e. FreeBSD 4.x). In all other cases the application developers are
advised to link against zookeeper_mt as it includes support for both
Sync and Async API.


INSTALLATION

If you're building the client from a source checkout you need to
follow the steps outlined below. If you're building from a release
tar downloaded from Apache please skip to step 2.

1) do a "ant compile_jute" from the zookeeper top level directory (.../trunk).
   This will create a directory named "generated" under zookeeper-client/zookeeper-client-c.
   Skip to step 3.
2) unzip/untar the source tarball and cd to the zookeeper-x.x.x/zookeeper-client/zookeeper-client-c directory
3) change directory to zookeeper-client/zookeeper-client-c and do a "autoreconf -if" to bootstrap
   autoconf, automake and libtool. Please make sure you have autoconf
   version 2.59 or greater installed. If cppunit is installed in a non-standard
   directory, you need to specify where to find cppunit.m4. For example, if
   cppunit is installed under /usr/local, run:
   
       ACLOCAL="aclocal -I /usr/local/share/aclocal" autoreconf -if

4) do a "./configure [OPTIONS]" to generate the makefile. See INSTALL
   for general information about running configure. Additionally, the
   configure supports the following options:
   --enable-debug     enables optimization and enables debug info compiler
                      options, disabled by default
   --without-syncapi  disables Sync API support; zookeeper_mt library won't
                      be built, enabled by default
   --disable-static   do not build static libraries, enabled by default
   --disable-shared   do not build shared libraries, enabled by default
   --without-cppunit  do not build the test library, enabled by default.

5) do a "make" or "make install" to build the libraries and install them. 
   Alternatively, you can also build and run a unit test suite (and
   you probably should).  Please make sure you have cppunit-1.10.x or
   higher installed before you execute step 4.  Once ./configure has
   finished, do a "make check". It will build the libraries, build
   the tests and run them.
6) to generate doxygen documentation do a "make doxygen-doc". All
   documentations will be placed to a new subfolder named docs. By
   default only HTML documentation is generated.  For information on
   other document formats please use "./configure --help"

Alternatively you can use the CMake build system. On Windows, this is required.
Follow steps 1 and 2 above, and then continue here.

1) do a "cmake [OPTIONS]" to generate the makefile or msbuild files (the correct
   build system will be generated based on your platform). Some options from above
   are supported:
   -DCMAKE_BUILD_TYPE  Debug by default, Release enables optimzation etc.
   -DWANT_SYNCAPI      ON by default, OFF disables the Sync API support
   -DWANT_CPPUNIT      ON except on Windows, OFF disables the tests
   -DWITH_OPENSSL      ON by default, OFF disables the SSL support. You can also
                       specify a custom path by -DWITH_OPENSSL=/path/to/openssl/
   -DWITH_CYRUS_SASL   ON by default, OFF disables SASL support. You can also
                       specify a custom path by -DWITH_CYRUS_SASL=/path/to/cyrus-sasl/
   -DBUILD_SHARED_LIBS not yet supported, only static libraries are built
   other CMake options see "cmake --help" for generic options, such as generator

2) do a "cmake --build ." to build the default targets. Alternatively you can
   invoke "make" or "msbuild" manually. If the tests were enabled, use "ctest -V"
   to run them.

Current limitations of the CMake build system include lack of Solaris support,
no shared library option, no explicitly exported symbols (all are exported by
default), no versions on the libraries, and no documentation generation.
Features of CMake include a single, easily consumed cross-platform build system
to generate the ZooKeeper C Client libraries for any project, with little to no
configuration.

EXAMPLE/SAMPLE C CLIENT SHELL

NOTE: the ZooKeeper C client shell (cli_st and cli_mt) is meant as a
example/sample of ZooKeeper C client API usage. It is not a full
fledged client and not meant for production usage - see the Java
client shell for a fully featured shell.

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 the zookeeper shell application cli that is 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):

$ cli_mt zookeeper_host:9876

To start a client with read-only mode enabled, use the -r flag:

$ cli_mt -r zookeeper_host:9876

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:

> create /my_new_node

To verify that the node's been created:

> ls /

You should see a list of nodes who are the children of the root node "/".

Here's a list of command supported by the cli shell:

ls <path>             -- list children of a znode identified by <path>. The
                         command set a children watch on the znode.
get <path>            -- get the value of a znode at <path>
set <path> <value>    -- set the value of a znode at <path> to <value>
create [+e|+s] <path> -- create a znode as a child of znode <path>; 
                         use +e option to create an ephemeral znode,
                         use +s option to create a znode with a sequence number 
                         appended to the name. The operation will fail if 
                         the parent znode (the one identified by <path>) doesn't
                         exist.
delete <path>         -- delete the znode at <path>. The command will fail if the znode
                         has children.
sync <path>           -- make sure all pending updates have been applied to znode at <path>
exists <path>         -- returns a result code indicating whether the znode at <path>
                         exists. The command also sets a znode watch.
myid                  -- prints out the current zookeeper session id.
quit                  -- exit the shell.

In order to be able to use the zookeeper API in your application you have to
1) remember to include the zookeeper header 
   #include <zookeeper/zookeeper.h>
2) use -DTHREADED compiler option to enable Sync API; in this case you should
   be linking your code against zookeeper_mt library

Please take a look at cli.c to understand how to use the two API types. 
(TODO: some kind of short tutorial would be helpful, I guess)