Permalink
Browse files

more doc

  • Loading branch information...
1 parent 47542ee commit a38ab20ab3e862390f92e7b9bcc9306fff8e265a Michi Mutsuzaki committed Jul 2, 2012
@@ -1,4 +1,4 @@
-/**
+/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
@@ -29,8 +29,10 @@
#include "zookeeper_const.hh"
#include "zookeeper_multi.hh"
+/** Org namespace. */
namespace org {
+/** Apache namespace. */
namespace apache {
/** ZooKeeper namespace. */
@@ -514,9 +516,15 @@ class ZooKeeper : boost::noncopyable {
ReturnCode::type sync(const std::string& path,
boost::shared_ptr<SyncCallback> callback);
+ /**
+ * Atomically executes multiple operations.
+ */
ReturnCode::type multi(const boost::ptr_vector<Op>& ops,
boost::shared_ptr<MultiCallback> callback);
+ /**
+ * Synchronous version of multi.
+ */
ReturnCode::type multi(const boost::ptr_vector<Op>& ops,
boost::ptr_vector<OpResult>& results);
@@ -3,6 +3,7 @@
\example examples/zk_hello_world.cc
@mainpage
+@tableofcontents
\section quick Quickstart
@@ -14,8 +15,8 @@ Install all the dependencies:
- ant
- cmake
- log4cxx
-- boost-thread
-- boost-system
+- boost with thread, system, and filesystem libraries
+- googletest
\subsection build Building and Installing
@@ -61,10 +62,77 @@ ZooKeeper Getting Started Guide</a>.
\subsection hello Hello, world!
+Now let's compile and run our first program, \ref examples/zk_hello_world.cc. This
+program creates a znode, reads from the znode and prints the value, and removes the
+znode.
+
+ cd $ZKHOME/src/contrib/zkcpp/examples
+ g++ zk_hello_world.cc -o zk_hello_world -I /usr/local/include -L /usr/local/lib -lzkcpp
+ ./zk_hello_world
+
+It should output something like this:
+
+ log4cxx: No appender could be found for logger (zookeeper.c).
+ log4cxx: Please initialize the log4cxx system properly.
+ /hello world
+
+The \ref logging section describes how to configure log4cxx logging to get rid of this warning.
+
+\section logging Logging
+
+Zkcpp uses <a href="http://logging.apache.org/log4cxx/index.html">Apache log4cxx</a> for logging.
+There are many ways to configure log4cxx, but the simplest way is to put a log4cxx configuration
+file named log4cxx.properties under the same directory as your executable that links against zkcpp.
+Here is a sample configuration that creates a log file test.log with the log level set to DEBUG:
+
+ log4j.rootLogger=DEBUG, file
+ log4j.appender.file=org.apache.log4j.RollingFileAppender
+ log4j.appender.file.File=test.log
+ log4j.appender.file.MaxFileSize=100MB
+ log4j.appender.file.MaxBackupIndex=1
+ log4j.appender.file.layout=org.apache.log4j.PatternLayout
+ log4j.appender.file.layout.ConversionPattern=%d [%t] %-5p %c:%L %m%n
+
+Run zk_hello_world after creating a log4cxx.properties with the above configuration in the same
+directory as zk_hello_world. This time, you should not see the log4cxx warnings, and there is a
+log file called test.log that contains debug logs like these:
+
+ 2012-07-01 23:19:40,398 [0x7fff786a2960] DEBUG zookeeper.c:359 Initializing a ZooKeeper client: version=ZooKeeper C++ Client 3.5.0
+ 2012-07-01 23:19:40,398 [0x7fff786a2960] DEBUG zookeeper.c:376 Initiating client connection, host=localhost:2181 sessionTimeout=30000 watcher=0 flags=0
+ 2012-07-01 23:19:40,401 [0x7fff786a2960] DEBUG zk_adaptor.cc:92 starting threads...
+ ...
+
\section model Data Model
\section async Asynchronous and Synchronous APIs
\section watch Watches
\section stat Znode Stat
+
+Some \link org::apache::zookeeper::ZooKeeper ZooKeeper \endlink operations
+return a \link org::apache::zookeeper::data::Stat data::Stat \endlink object,
+which contains metadata information about a znode. The Stat contains the
+ following fields (from
+<a href="http://zookeeper.apache.org/doc/r3.4.3/zookeeperProgrammers.html#sc_zkStatStructure">
+ZooKeeper Programmer's Guide</a>):
+
+- \c czxid The zxid of the change that caused this znode to be created.
+- \c mzxid The zxid of the change that last modified this znode.
+- \c ctime The time in milliseconds from epoch when this znode was created.
+- \c mtime The time in milliseconds from epoch when this znode was last modified.
+- \c version The number of changes to the data of this znode.
+- \c cversion The number of changes to the children of this znode.
+- \c aversion The number of changes to the ACL of this znode.
+- \c ephemeralOwner The session id of the owner of this znode if the znode is an ephemeral node. If it is not an ephemeral node, it will be zero.
+- \c dataLength The length of the data field of this znode.
+- \c numChildren The number of children of this znode.
+
+You can pass the znode version to \link org::apache::zookeeper::ZooKeeper::set() set() \endlink
+and \link org::apache::zookeeper::ZooKeeper::remove() remove() \endlink operations, and aversion
+to \link org::apache::zookeeper::ZooKeeper::setAcl() setAcl() \endlink operation to avoid
+conflicting updates. These operations will fail with \link org::apache::zookeeper::ReturnCode::BadVersion
+ReturnCode::BadVersion \endlink return code if the (a)version passed to these operation
+does not match the current znode (a)version. You can pass -1 to these operations to bypass
+the version check.
+
\section auth Authentication and Authorization
*/

0 comments on commit a38ab20

Please sign in to comment.