You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@zookeeper.apache.org by ma...@apache.org on 2009/06/23 20:38:34 UTC
svn commit: r787780 [3/3] - in /hadoop/zookeeper/trunk: ./ docs/
src/docs/src/documentation/content/xdocs/
Added: hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/bookkeeperStarted.xml
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/bookkeeperStarted.xml?rev=787780&view=auto
==============================================================================
--- hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/bookkeeperStarted.xml (added)
+++ hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/bookkeeperStarted.xml Tue Jun 23 18:38:33 2009
@@ -0,0 +1,204 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2002-2004 The Apache Software Foundation
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.0//EN"
+"http://www.oasis-open.org/docbook/xml/simple/1.0/sdocbook.dtd">
+<article id="bk_GettStartedGuide">
+ <title>BookKeeper Getting Started Guide</title>
+
+ <articleinfo>
+ <legalnotice>
+ <para>Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License. You may
+ obtain a copy of the License at <ulink
+ url="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</ulink>.</para>
+
+ <para>Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an "AS IS"
+ BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied. See the License for the specific language governing permissions
+ and limitations under the License.</para>
+ </legalnotice>
+
+ <abstract>
+ <para>This guide contains detailed information about using BookKeeper
+ for logging. It discusses the basic operations BookKeeper supports,
+ and how to create logs and perform basic read and write operations on these
+ logs.</para>
+ </abstract>
+ </articleinfo>
+ <section id="bk_GettingStarted">
+ <title>Getting Started: Setting up BookKeeper to write logs.</title>
+
+ <para>This document contains information to get you started quickly with
+ BookKeeper. It is aimed primarily at developers willing to try it out, and
+ contains simple installation instructions for a simple BookKeeper installation
+ and a simple programming example. For further programming detail, please refer to
+ <ulink url="bookkeeperProgrammer.html">BookKeeper Programmer's Guide</ulink>.
+ </para>
+
+ <section id="bk_Prerequisites">
+ <title>Pre-requisites</title>
+ <para>See <ulink url="bookkeeperConfig.html#bk_sysReq">
+ System Requirements</ulink> in the Admin guide.</para>
+ </section>
+
+ <section id="bk_Download">
+ <title>Download</title>
+ <para> BookKeeper is distributed along with ZooKeeper. To get a ZooKeeper distribution,
+ download a recent
+ <ulink url="http://hadoop.apache.org/zookeeper/releases.html">
+ stable</ulink> release from one of the Apache Download
+ Mirrors.</para>
+ </section>
+
+ <section id="bk_localBK">
+ <title>LocalBookKeeper</title>
+ <para> Under org.apache.bookkeeper.util, you'll find a java program
+ called LocalBookKeeper.java that sets you up to run BookKeeper on a
+ single machine. This is far from ideal from a performance perspective,
+ but the program is useful for both test and educational purposes.
+ </para>
+ </section>
+
+ <section id="bk_setupBookies">
+ <title>Setting up bookies</title>
+ <para> If you're bold and you want more than just running things locally, then
+ you'll need to run bookies in different servers. You'll need at least three bookies
+ to start with.
+ </para>
+
+ <para>
+ For each bookie, we need to execute a command like the following:
+ </para>
+
+ <para><computeroutput>
+ java -cp .:./zookeeper-dev-bookkeeper.jar:./zookeeper-dev.jar:../log4j/apache-log4j-1.2.15/log4j-1.2.15.jar\
+ -Dlog4j.configuration=log4j.properties org.apache.bookkeeper.proto.BookieServer 3181 /path_to_log_device/\
+ /path_to_ledger_device/
+ </computeroutput></para>
+
+ <para> "/path_to_log_device/" and "/path_to_ledger_device/" are different paths. Also, port 3181
+ is the port that a bookie listens on for connection requests from clients.
+ </para>
+ </section>
+
+ <section id="bk_setupZK">
+ <title>Setting up ZooKeeper</title>
+ <para> ZooKeeper stores metadata on behalf of BookKeeper clients and bookies. To get a minimal
+ ZooKeeper installation to work with BookKeeper, we can set up one server running in
+ standalone mode. Once we have the server running, we need to create a few znodes:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para><computeroutput>
+ /ledgers
+ </computeroutput></para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>
+ /ledgers/available
+ </computeroutput></para>
+ </listitem>
+
+ <listitem>
+ <para> For each bookie, we add one znode such that the name of the znode is the
+ concatenation of the machine name and the port number that the bookie is
+ listening on. For example, if a bookie is running on bookie.foo.com an is listening
+ on port 3181, we add a znode
+ <computeroutput>/ledgers/available/bookie.foo.com:3181</computeroutput>.
+ </para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section id="bk_example">
+ <title>Example</title>
+ <para>
+ In the following excerpt of code, we:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ Create a ledger;
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Write to the ledger;
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Close the ledger;
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Open the same ledger for reading;
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Read from the ledger;
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Close the ledger again;
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <programlisting>
+LedgerHandle lh = bkc.createLedger(ledgerPassword);
+ledgerId = lh.getId();
+ByteBuffer entry = ByteBuffer.allocate(4);
+
+for(int i = 0; i < 10; i++){
+ entry.putInt(i);
+ entry.position(0);
+ entries.add(entry.array());
+ lh.addEntry(entry.array());
+}
+lh.close();
+lh = bkc.openLedger(ledgerId, ledgerPassword);
+
+LedgerSequence ls = lh.readEntries(0, 9);
+int i = 0;
+while(ls.hasMoreElements()){
+ ByteBuffer origbb = ByteBuffer.wrap(
+ entries.get(i++));
+ Integer origEntry = origbb.getInt();
+ ByteBuffer result = ByteBuffer.wrap(
+ ls.nextElement().getEntry());
+
+ Integer retrEntry = result.getInt();
+}
+lh.close();
+ </programlisting>
+ </section>
+ </section>
+</article>
\ No newline at end of file
Modified: hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/index.xml
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/index.xml?rev=787780&r1=787779&r2=787780&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/index.xml (original)
+++ hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/index.xml Tue Jun 23 18:38:33 2009
@@ -79,6 +79,16 @@
</ul>
</li>
+ <li><strong>BookKeeper Documentation</strong>
+ <p> BookKeeper is a highly-available system that implements high-performance write-ahead logging. It uses ZooKeeper for metadata,
+ which is the main reason for being a ZooKeeper contrib.
+ </p>
+ <ul>
+ <li><a href="bookkeeperOverview.html">henn, what's it again?</a></li>
+ <li><a href="bookkeeperStarted.html">Ok, now how do I try it out</a></li>
+ <li><a href="bookkeeperProgrammer.html">Awesome, but how do I integrate it with my app?</a></li>
+ </ul>
+ </li>
</ul>
</body>
Modified: hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/site.xml
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/site.xml?rev=787780&r1=787779&r2=787780&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/site.xml (original)
+++ hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/site.xml Tue Jun 23 18:38:33 2009
@@ -46,6 +46,13 @@
<recipes label="Recipes" href="recipes.html" />
</docs>
+ <docs label="BookKeeper">
+ <bkStarted label="Getting started" href="bookkeeperStarted.html" />
+ <bkOverview label="Overview" href="bookkeeperOverview.html" />
+ <bkProgrammer label="Setup guide" href="bookkeeperConfig.html" />
+ <bkProgrammer label="Programmer's guide" href="bookkeeperProgrammer.html" />
+ </docs>
+
<docs label="Admin & Ops">
<admin label="Administrator's Guide" href="zookeeperAdmin.html" />
<quota label="Quota Guide" href="zookeeperQuotas.html" />
Modified: hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperTutorial.xml
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperTutorial.xml?rev=787780&r1=787779&r2=787780&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperTutorial.xml (original)
+++ hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperTutorial.xml Tue Jun 23 18:38:33 2009
@@ -68,12 +68,10 @@
zk = null;
}
}
- //else mutex = new Integer(-1);
}
synchronized public void process(WatchedEvent event) {
synchronized (mutex) {
- //System.out.println("Process: " + event.getType());
mutex.notify();
}
}