Author: breed
Date: Wed Jan 28 00:21:54 2009
New Revision: 738317
URL: http://svn.apache.org/viewvc?rev=738317&view=rev
Log:
ZOOKEEPER-263. document connection host:port as comma separated list in forrest
docs (pat via breed)
Modified:
hadoop/zookeeper/trunk/CHANGES.txt
hadoop/zookeeper/trunk/docs/zookeeperProgrammers.html
hadoop/zookeeper/trunk/docs/zookeeperProgrammers.pdf
hadoop/zookeeper/trunk/src/c/include/zookeeper.h
hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml
hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ZooKeeper.java
Modified: hadoop/zookeeper/trunk/CHANGES.txt
URL:
http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/CHANGES.txt?rev=738317&r1=738316&r2=738317&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/CHANGES.txt (original)
+++ hadoop/zookeeper/trunk/CHANGES.txt Wed Jan 28 00:21:54 2009
@@ -72,6 +72,8 @@
ZOOKEEPER-268. tostring on jute generated objects can cause NPE. (pat via
mahadev)
ZOOKEEPER-267. java client incorrectly generating syncdisconnected event
when in disconnected state. (pat via breed)
+
+ ZOOKEEPER-263. document connection host:port as comma separated list in
forrest docs (pat via breed)
IMPROVEMENTS:
Modified: hadoop/zookeeper/trunk/docs/zookeeperProgrammers.html
URL:
http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/docs/zookeeperProgrammers.html?rev=738317&r1=738316&r2=738317&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/docs/zookeeperProgrammers.html (original)
+++ hadoop/zookeeper/trunk/docs/zookeeperProgrammers.html Wed Jan 28 00:21:54
2009
@@ -733,6 +733,15 @@
<a name="N101A5"></a><a name="ch_zkSessions"></a>
<h2 class="h3">ZooKeeper Sessions</h2>
<div class="section">
+<p>To create a client session the application code must provide
+ a string containing a comma separated list of host:port pairs,
+ each corresponding to a ZooKeeper server (e.g. "127.0.0.1:4545" or
+ "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"). The ZooKeeper
+ client library will pick an arbitrary server and try to connect to
+ it. If this connection fails, or if the client becomes
+ disconnected from the server for any reason, the client will
+ automatically try the next server in the list, until a connection
+ is (re-)established.</p>
<p>When a client gets a handle to the ZooKeeper service,
ZooKeeper creates a ZooKeeper session, represented as a 64-bit
number, that it assigns to the client. If the client connects to a
@@ -771,7 +780,7 @@
</div>
-<a name="N101B8"></a><a name="ch_zkWatches"></a>
+<a name="N101BB"></a><a name="ch_zkWatches"></a>
<h2 class="h3">ZooKeeper Watches</h2>
<div class="section">
<p>All of the read operations in ZooKeeper - <strong>getData()</strong>,
<strong>getChildren()</strong>, and <strong>exists()</strong> - have the option
of setting a watch as a
@@ -848,7 +857,7 @@
general this all occurs transparently. There is one case where a watch
may be missed: a watch for the existance of a znode not yet created will
be missed if the znode is created and deleted while disconnected.</p>
-<a name="N101EE"></a><a name="sc_WatchGuarantees"></a>
+<a name="N101F1"></a><a name="sc_WatchGuarantees"></a>
<h3 class="h4">What ZooKeeper Guarantees about Watches</h3>
<p>With regard to watches, ZooKeeper maintains these
guarantees:</p>
@@ -883,7 +892,7 @@
</li>
</ul>
-<a name="N10213"></a><a name="sc_WatchRememberThese"></a>
+<a name="N10216"></a><a name="sc_WatchRememberThese"></a>
<h3 class="h4">Things to Remember about Watches</h3>
<ul>
@@ -942,7 +951,7 @@
</div>
-<a name="N1023F"></a><a name="sc_ZooKeeperAccessControl"></a>
+<a name="N10242"></a><a name="sc_ZooKeeperAccessControl"></a>
<h2 class="h3">ZooKeeper access control using ACLs</h2>
<div class="section">
<p>ZooKeeper uses ACLs to control access to its znodes (the
@@ -971,7 +980,7 @@
example, the pair <em>(ip:19.22.0.0/16, READ)</em>
gives the <em>READ</em> permission to any clients with
an IP address that starts with 19.22.</p>
-<a name="N10266"></a><a name="sc_ACLPermissions"></a>
+<a name="N10269"></a><a name="sc_ACLPermissions"></a>
<h3 class="h4">ACL Permissions</h3>
<p>ZooKeeper supports the following permissions:</p>
<ul>
@@ -1027,7 +1036,7 @@
node, but nothing more. (The problem is, if you want to call
zoo_exists() on a node that doesn't exist, there is no
permission to check.)</p>
-<a name="N102BC"></a><a name="sc_BuiltinACLSchemes"></a>
+<a name="N102BF"></a><a name="sc_BuiltinACLSchemes"></a>
<h4>Builtin ACL Schemes</h4>
<p>ZooKeeeper has the following built in schemes:</p>
<ul>
@@ -1088,7 +1097,7 @@
</ul>
-<a name="N10312"></a><a name="ZooKeeper+C+client+API"></a>
+<a name="N10315"></a><a name="ZooKeeper+C+client+API"></a>
<h4>ZooKeeper C client API</h4>
<p>The following constants are provided by the ZooKeeper C
library:</p>
@@ -1310,7 +1319,7 @@
</div>
-<a name="N10429"></a><a name="ch_zkGuarantees"></a>
+<a name="N1042C"></a><a name="ch_zkGuarantees"></a>
<h2 class="h3">Consistency Guarantees</h2>
<div class="section">
<p>ZooKeeper is a high performance, scalable service. Both reads and
@@ -1436,12 +1445,12 @@
</div>
-<a name="N10490"></a><a name="ch_bindings"></a>
+<a name="N10493"></a><a name="ch_bindings"></a>
<h2 class="h3">Bindings</h2>
<div class="section">
<p>The ZooKeeper client libraries come in two languages: Java and C.
The following sections describe these.</p>
-<a name="N10499"></a><a name="Java+Binding"></a>
+<a name="N1049C"></a><a name="Java+Binding"></a>
<h3 class="h4">Java Binding</h3>
<p>There are two packages that make up the ZooKeeper Java binding:
<strong>org.apache.zookeeper</strong> and
<strong>org.apache.zookeeper.data</strong>. The rest of the
@@ -1508,7 +1517,7 @@
(SESSION_EXPIRED and AUTH_FAILED), the ZooKeeper object becomes invalid,
the two threads shut down, and any further ZooKeeper calls throw
errors.</p>
-<a name="N104E2"></a><a name="C+Binding"></a>
+<a name="N104E5"></a><a name="C+Binding"></a>
<h3 class="h4">C Binding</h3>
<p>The C binding has a single-threaded and multi-threaded library.
The multi-threaded library is easiest to use and is most similar to the
@@ -1525,7 +1534,7 @@
(i.e. FreeBSD 4.x). In all other cases, application developers should
link with zookeeper_mt, as it includes support for both Sync and Async
API.</p>
-<a name="N104F1"></a><a name="Installation"></a>
+<a name="N104F4"></a><a name="Installation"></a>
<h4>Installation</h4>
<p>If you're building the client from a check-out from the Apache
repository, follow the steps outlined below. If you're building from a
@@ -1656,7 +1665,7 @@
</li>
</ol>
-<a name="N1059A"></a><a name="Using+the+C+Client"></a>
+<a name="N1059D"></a><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
@@ -1714,7 +1723,7 @@
</div>
-<a name="N105E0"></a><a name="ch_guideToZkOperations"></a>
+<a name="N105E3"></a><a name="ch_guideToZkOperations"></a>
<h2 class="h3">Building Blocks: A Guide to ZooKeeper Operations</h2>
<div class="section">
<p>This section surveys all the operations a developer can perform
@@ -1732,28 +1741,28 @@
</li>
</ul>
-<a name="N105F4"></a><a name="sc_errorsZk"></a>
+<a name="N105F7"></a><a name="sc_errorsZk"></a>
<h3 class="h4">Handling Errors</h3>
<p>Both the Java and C client bindings may report errors. The Java client
binding does so by throwing KeeperException, calling code() on the exception
will return the specific error code. The C client binding returns an error code
as defined in the enum ZOO_ERRORS. API callbacks indicate result code for both
language bindings. See the API documentation (javadoc for Java, doxygen for C)
for full details on the possible errors and their meaning.</p>
-<a name="N105FE"></a><a name="sc_connectingToZk"></a>
+<a name="N10601"></a><a name="sc_connectingToZk"></a>
<h3 class="h4">Connecting to ZooKeeper</h3>
<p></p>
-<a name="N10607"></a><a name="sc_readOps"></a>
+<a name="N1060A"></a><a name="sc_readOps"></a>
<h3 class="h4">Read Operations</h3>
<p></p>
-<a name="N10610"></a><a name="sc_writeOps"></a>
+<a name="N10613"></a><a name="sc_writeOps"></a>
<h3 class="h4">Write Operations</h3>
<p></p>
-<a name="N10619"></a><a name="sc_handlingWatches"></a>
+<a name="N1061C"></a><a name="sc_handlingWatches"></a>
<h3 class="h4">Handling Watches</h3>
<p></p>
-<a name="N10622"></a><a name="sc_miscOps"></a>
+<a name="N10625"></a><a name="sc_miscOps"></a>
<h3 class="h4">Miscelleaneous ZooKeeper Operations</h3>
<p></p>
</div>
-<a name="N1062C"></a><a name="ch_programStructureWithExample"></a>
+<a name="N1062F"></a><a name="ch_programStructureWithExample"></a>
<h2 class="h3">Program Structure, with Simple Example</h2>
<div class="section">
<p>
@@ -1762,7 +1771,7 @@
</div>
-<a name="N10637"></a><a name="ch_gotchas"></a>
+<a name="N1063A"></a><a name="ch_gotchas"></a>
<h2 class="h3">Gotchas: Common Problems and Troubleshooting</h2>
<div class="section">
<p>So now you know ZooKeeper. It's fast, simple, your application
Modified: hadoop/zookeeper/trunk/docs/zookeeperProgrammers.pdf
URL:
http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/docs/zookeeperProgrammers.pdf?rev=738317&r1=738316&r2=738317&view=diff
==============================================================================
Binary files - no diff available.
Modified: hadoop/zookeeper/trunk/src/c/include/zookeeper.h
URL:
http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/c/include/zookeeper.h?rev=738317&r1=738316&r2=738317&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/src/c/include/zookeeper.h (original)
+++ hadoop/zookeeper/trunk/src/c/include/zookeeper.h Wed Jan 28 00:21:54 2009
@@ -280,8 +280,8 @@
* to that handle. Session establishment is asynchronous, meaning that the
* session should not be considered established until (and unless) an
* event of state ZOO_CONNECTED_STATE is received.
- * \param host the host name to connect to. This may be a comma separated list
- * of different hosts.
+ * \param host comma separated host:port pairs, each corresponding to a zk
+ * server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"
* \param fn the global watcher callback function. When notifications are
* triggered this function will be invoked.
* \param clientid the id of a previously established session that this
Modified:
hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml
URL:
http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml?rev=738317&r1=738316&r2=738317&view=diff
==============================================================================
---
hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml
(original)
+++
hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml
Wed Jan 28 00:21:54 2009
@@ -358,6 +358,16 @@
<section id="ch_zkSessions">
<title>ZooKeeper Sessions</title>
+ <para>To create a client session the application code must provide
+ a string containing a comma separated list of host:port pairs,
+ each corresponding to a ZooKeeper server (e.g. "127.0.0.1:4545" or
+ "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"). The ZooKeeper
+ client library will pick an arbitrary server and try to connect to
+ it. If this connection fails, or if the client becomes
+ disconnected from the server for any reason, the client will
+ automatically try the next server in the list, until a connection
+ is (re-)established.</para>
+
<para>When a client gets a handle to the ZooKeeper service,
ZooKeeper creates a ZooKeeper session, represented as a 64-bit
number, that it assigns to the client. If the client connects to a
Modified:
hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ZooKeeper.java
URL:
http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ZooKeeper.java?rev=738317&r1=738316&r2=738317&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ZooKeeper.java
(original)
+++ hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ZooKeeper.java
Wed Jan 28 00:21:54 2009
@@ -317,7 +317,24 @@
protected final ClientCnxn cnxn;
/**
- * @see ZooKeeper(String, int, Watcher, long, byte[])
+ * To create a client(ZooKeeper) object, the application needs to pass a
+ * string containing a comma separated list of host:port pairs, each
+ * corresponding to a ZooKeeper server.
+ * <p>
+ * The client object will pick an arbitrary server and try to connect to
it.
+ * If failed, it will try the next one in the list, until a connection is
+ * established, or all the servers have been tried.
+ *
+ * @param host
+ * comma separated host:port pairs, each corresponding to a zk
+ * server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"
+ * @param sessionTimeout
+ * session timeout in milliseconds
+ * @param watcher
+ * a watcher object which will be notified of state changes, may
+ * also be notified for node events
+ *
+ * @throws IOException in cases of network failure
*/
public ZooKeeper(String host, int sessionTimeout, Watcher watcher)
throws IOException {
@@ -330,8 +347,8 @@
/**
* To create a client(ZooKeeper) object, the application needs to pass a
- * string containing a list of host:port pairs, each corresponding to a
- * ZooKeeper server.
+ * string containing a comma separated list of host:port pairs, each
+ * corresponding to a ZooKeeper server.
* <p>
* The client object will pick an arbitrary server and try to connect to
it.
* If failed, it will try the next one in the list, until a connection is
@@ -345,7 +362,7 @@
*
* @param host
* comma separated host:port pairs, each corresponding to a zk
- * server. eg. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"
+ * server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"
* @param sessionTimeout
* session timeout in milliseconds
* @param watcher
@@ -356,8 +373,7 @@
* @param sessionPasswd
* password for this session
*
- * @throws IOException
- * in cases of network failure
+ * @throws IOException in cases of network failure
*/
public ZooKeeper(String host, int sessionTimeout, Watcher watcher,
long sessionId, byte[] sessionPasswd) throws IOException {
