BOOKKEEPER-121: Review Hedwig client documentation (breed via ivank)

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

Author: ivankelly

CHANGES.txt

@@ -10,6 +10,8 @@ BUGFIXES:
 
  BOOKKEEPER-124: build has RAT failures (ivank)
 
+ BOOKKEEPER-121: Review Hedwig client documentation (breed via ivank)
+
  bookkeeper-server/
 
   BOOKKEEPER-1: Static variable makes tests fail (fpj via ivank)

doc/hedwigBuild.textile

@@ -15,8 +15,6 @@ For the core itself:
 
 * JDK 6: "http://java.sun.com/":http://java.sun.com/. Ensure @$JAVA_HOME@ is correctly set.
 * Maven 2: "http://maven.apache.org/":http://maven.apache.org/.
-* Protocol Buffers 2.3.0: "http://protobuf.googlecode.com/":http://protobuf.googlecode.com/.
-* Zookeeper 3.4.0: "http://zookeeper.apache.org/":http://zookeeper.apache.org/.
 
 Hedwig has been tested on Windows XP, Linux 2.6, and OS X.
 
@@ -35,8 +33,6 @@ To check out, build, and develop using Eclipse:
 # Go to Preferences > Team > SVN. For the SVN interface, choose "Pure Java".
 # Choose File > New > Project... > Maven > Checkout Maven Projects from SCM.
 # For the SCM URL type, choose SVN. For the URL, enter SVN URL. Maven will automatically create a top-level Eclipse project for each of the 4 Maven modules (recommended). If you want fewer top-level projects, uncheck the option of having a project for each module (under Advanced).
-# Right-click on the @protocol@ project and choose Run As > Maven generate-sources. This will generate the Java and C++ code for Protocol Buffers.
-# Refresh the workspace to pick up the generated code and add @hedwig/protocol/target/generated-sources/java@ as a source folder. (6 & 7 should really be doable automatically, but I haven't figured out how.)
 
 You are now ready to run and debug the client and server code. See the User's Guide for instructions on running and usage.
 

doc/hedwigDesign.textile

@@ -36,9 +36,13 @@ h1. Pseudocode
 
 This summarizes the control flow through the system.
 
-publishhandler topicmgr.getowner (maybe) claim the topic, calling back into persmgr.acquiredtopic read /hedwig/standalone/topics/TOPIC (which should initially be empty) for each line, parse as "STARTSEQ" # TODO how is this written? ledger = bk.openledger(ledgerid) lastid = ledger.getlast if lastid > 0, lrs[startseq] = persmgr.ledger2lr[ledgerid] = new LedgerRange(ledger, ledgerid, startseq, startseq + lastid # TODO what are ledger ranges? create new ledger for topic # TODO read lr = new LedgerRange(ledger, ledgerid, lastid, -1) lrs[lastid] = lr persmgr.topic2ranges[topic] = lrs add region info to pub req and send that to persmgr.persistmessage entryid = persmgr.topic2ranges[topic].last.ledger.addentry(the pub'd data) update persmgr.topic2lastseq[topic]: .local = persmgr.ledger2lr[ledger id].startseq + entryid .regions = maxes of orig seq and incoming pub seq
+h2. publish
 
-subscribehandler topicmgr.getowner... delivmgr.startservingsubscription(topic, endpoint, ishubsubscriber) delivmgr.endpoint2sub[endpoint] = new subscriber(lastseq = persmgr.getcurrentseqidfortopic(topic).local) delivmgr.topic2ptr2subs[topic][ptr].add(sub) sub.delivernextmessage sub.curseq = persmgr.getseqidafterskipping(topic, sub.lastseq, skip = 1) msg = persmgr.scansinglemessage(topic, seq = sub.curseq) if persmgr.topic2lastseq[topic].local >= seq lr = persmgr.topic2ranges[topic].floor(seq) return lr.ledger.read(first = last = seq - lr.startseq) if failed, then retry in 1 s endpoint.send(msg) movedeliveryptr delivmgr.topic2ptr2subs[topic][sub.lastseq].remove(sub) delivmgr.topic2ptr2subs[topic][sub.curseq].add(sub) previd = sub.lastseq, sub.lastseq = sub.curseq sub.delivernextmessage...
+Need to document
+
+h2. subscribe
+
+Need to document
 
 h1. ReadAhead Cache
 

doc/hedwigUser.textile

@@ -43,20 +43,21 @@ Hedwig requires BookKeeper to run. For BookKeeper setup instructions see "BookKe
 
 To start a Hedwig hub server:
 
- @ hedwig-server/bin/hedwig server
+@hedwig-server/bin/hedwig server@
 
 Hedwig takes its configuration from hedwig-server/conf/hw_server.conf by default. To change location of the conf file, modify the HEDWIG_SERVER_CONF environment variable.
 
 h1. Debugging
 
 You can attach an Eclipse debugger (or any debugger) to a Java process running on a remote host, as long as it has been started with the appropriate JVM flags. (See the Building Hedwig document to set up your Eclipse environment.) To launch something using @bin/hedwig@ with debugger attachment enabled, prefix the command with @HEDWIG_EXTRA_OPTS=-agentlib:jdwp=transport=dt_socket,server=y,address=5000@, e.g.:
 
-@ HEDWIG_EXTRA_OPTS=-agentlib:jdwp=transport=dt_socket,server=y,address=5000 hedwig-server/bin/hedwig server
+@HEDWIG_EXTRA_OPTS=-agentlib:jdwp=transport=dt_socket,server=y,address=5000 hedwig-server/bin/hedwig server@
 
 h1. Logging
 
-To control the logging in Hedwig server, set HEDWIG_LOG_CONF to the location of a log4j.properties file.
+Hedwig uses "slf4j":http://www.slf4j.org for logging, with the log4j bindings enabled by default. To enable logging from hedwig, create a log4j.properties file and point the environment variable HEDWIG_LOG_CONF to the file. The path to the log4j.properties file must be absolute.
 
-@ HEDWIG_LOG_CONF=../hw_testing/log4j.properties hedwig-server/bin/hedwig server
+@export HEDWIG_LOG_CONF=/tmp/log4j.properties@
+@hedwig-server/bin/hedwig server@