http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/bookkeeperOverview.html ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/bookkeeperOverview.html b/content/doc/r3.5.4-beta/bookkeeperOverview.html new file mode 100644 index 0000000..645f651 --- /dev/null +++ b/content/doc/r3.5.4-beta/bookkeeperOverview.html @@ -0,0 +1,694 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd";> +<html> +<head> +<META http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<meta content="Apache Forrest" name="Generator"> +<meta name="Forrest-version" content="0.9"> +<meta name="Forrest-skin-name" content="pelt"> +<title>BookKeeper overview</title> +<link type="text/css" href="skin/basic.css" rel="stylesheet"> +<link media="screen" type="text/css" href="skin/screen.css" rel="stylesheet"> +<link media="print" type="text/css" href="skin/print.css" rel="stylesheet"> +<link type="text/css" href="skin/profile.css" rel="stylesheet"> +<script src="skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="skin/fontsize.js" language="javascript" type="text/javascript"></script> +<link rel="shortcut icon" href="images/favicon.ico"> +</head> +<body onload="init()"> +<script type="text/javascript">ndeSetTextSize();</script> +<div id="top"> +<!--+ + |breadtrail + +--> +<div class="breadtrail"> +<a href="http://www.apache.org/";>Apache</a> > <a href="http://zookeeper.apache.org/";>ZooKeeper</a> > <a href="http://zookeeper.apache.org/";>ZooKeeper</a><script src="skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script> +</div> +<!--+ + |header + +--> +<div class="header"> +<!--+ + |start group logo + +--> +<div class="grouplogo"> +<a href="http://hadoop.apache.org/";><img class="logoImage" alt="Hadoop" src="images/hadoop-logo.jpg" title="Apache Hadoop"></a> +</div> +<!--+ + |end group logo + +--> +<!--+ + |start Project Logo + +--> +<div class="projectlogo"> +<a href="http://zookeeper.apache.org/";><img class="logoImage" alt="ZooKeeper" src="images/zookeeper_small.gif" title="ZooKeeper: distributed coordination"></a> +</div> +<!--+ + |end Project Logo + +--> +<!--+ + |start Search + +--> +<div class="searchbox"> +<form action="http://www.google.com/search"; method="get" class="roundtopsmall"> +<input value="zookeeper.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google"> + <input name="Search" value="Search" type="submit"> +</form> +</div> +<!--+ + |end search + +--> +<!--+ + |start Tabs + +--> +<ul id="tabs"> +<li> +<a class="unselected" href="http://zookeeper.apache.org/";>Project</a> +</li> +<li> +<a class="unselected" href="https://cwiki.apache.org/confluence/display/ZOOKEEPER/";>Wiki</a> +</li> +<li class="current"> +<a class="selected" href="index.html">ZooKeeper 3.4 Documentation</a> +</li> +</ul> +<!--+ + |end Tabs + +--> +</div> +</div> +<div id="main"> +<div id="publishedStrip"> +<!--+ + |start Subtabs + +--> +<div id="level2tabs"></div> +<!--+ + |end Endtabs + +--> +<script type="text/javascript"><!-- +document.write("Last Published: " + document.lastModified); +// --></script> +</div> +<!--+ + |breadtrail + +--> +<div class="breadtrail"> + + + </div> +<!--+ + |start Menu, mainarea + +--> +<!--+ + |start Menu + +--> +<div id="menu"> +<div onclick="SwitchMenu('menu_1.1', 'skin/')" id="menu_1.1Title" class="menutitle">Overview</div> +<div id="menu_1.1" class="menuitemgroup"> +<div class="menuitem"> +<a href="index.html">Welcome</a> +</div> +<div class="menuitem"> +<a href="zookeeperOver.html">Overview</a> +</div> +<div class="menuitem"> +<a href="zookeeperStarted.html">Getting Started</a> +</div> +<div class="menuitem"> +<a href="releasenotes.html">Release Notes</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.2', 'skin/')" id="menu_1.2Title" class="menutitle">Developer</div> +<div id="menu_1.2" class="menuitemgroup"> +<div class="menuitem"> +<a href="api/index.html">API Docs</a> +</div> +<div class="menuitem"> +<a href="zookeeperProgrammers.html">Programmer's Guide</a> +</div> +<div class="menuitem"> +<a href="javaExample.html">Java Example</a> +</div> +<div class="menuitem"> +<a href="zookeeperTutorial.html">Barrier and Queue Tutorial</a> +</div> +<div class="menuitem"> +<a href="recipes.html">Recipes</a> +</div> +</div> +<div onclick="SwitchMenu('menu_selected_1.3', 'skin/')" id="menu_selected_1.3Title" class="menutitle" style="background-image: url('skin/images/chapter_open.gif');">BookKeeper</div> +<div id="menu_selected_1.3" class="selectedmenuitemgroup" style="display: block;"> +<div class="menuitem"> +<a href="bookkeeperStarted.html">Getting started</a> +</div> +<div class="menupage"> +<div class="menupagetitle">Overview</div> +</div> +<div class="menuitem"> +<a href="bookkeeperConfig.html">Setup guide</a> +</div> +<div class="menuitem"> +<a href="bookkeeperProgrammer.html">Programmer's guide</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.4', 'skin/')" id="menu_1.4Title" class="menutitle">Admin & Ops</div> +<div id="menu_1.4" class="menuitemgroup"> +<div class="menuitem"> +<a href="zookeeperAdmin.html">Administrator's Guide</a> +</div> +<div class="menuitem"> +<a href="zookeeperQuotas.html">Quota Guide</a> +</div> +<div class="menuitem"> +<a href="zookeeperJMX.html">JMX</a> +</div> +<div class="menuitem"> +<a href="zookeeperObservers.html">Observers Guide</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.5', 'skin/')" id="menu_1.5Title" class="menutitle">Contributor</div> +<div id="menu_1.5" class="menuitemgroup"> +<div class="menuitem"> +<a href="zookeeperInternals.html">ZooKeeper Internals</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.6', 'skin/')" id="menu_1.6Title" class="menutitle">Miscellaneous</div> +<div id="menu_1.6" class="menuitemgroup"> +<div class="menuitem"> +<a href="https://cwiki.apache.org/confluence/display/ZOOKEEPER";>Wiki</a> +</div> +<div class="menuitem"> +<a href="https://cwiki.apache.org/confluence/display/ZOOKEEPER/FAQ";>FAQ</a> +</div> +<div class="menuitem"> +<a href="http://zookeeper.apache.org/mailing_lists.html";>Mailing Lists</a> +</div> +</div> +<div id="credit"></div> +<div id="roundbottom"> +<img style="display: none" class="corner" height="15" width="15" alt="" src="skin/images/rc-b-l-15-1body-2menu-3menu.png"></div> +<!--+ + |alternative credits + +--> +<div id="credit2"></div> +</div> +<!--+ + |end Menu + +--> +<!--+ + |start content + +--> +<div id="content"> +<div title="Portable Document Format" class="pdflink"> +<a class="dida" href="bookkeeperOverview.pdf"><img alt="PDF -icon" src="skin/images/pdfdoc.gif" class="skin"><br> + PDF</a> +</div> +<h1>BookKeeper overview</h1> +<div id="front-matter"> +<div id="minitoc-area"> +<ul class="minitoc"> +<li> +<a href="#bk_Overview">BookKeeper overview</a> +<ul class="minitoc"> +<li> +<a href="#bk_Intro">BookKeeper introduction</a> +</li> +<li> +<a href="#bk_moreDetail">In slightly more detail...</a> +</li> +<li> +<a href="#bk_basicComponents">Bookkeeper elements and concepts</a> +</li> +<li> +<a href="#bk_initialDesign">Bookkeeper initial design</a> +</li> +<li> +<a href="#bk_metadata">Bookkeeper metadata management</a> +</li> +<li> +<a href="#bk_closingOut">Closing out ledgers</a> +</li> +</ul> +</li> +</ul> +</div> +</div> + + + + +<a name="bk_Overview"></a> +<h2 class="h3">BookKeeper overview</h2> +<div class="section"> +<a name="bk_Intro"></a> +<h3 class="h4">BookKeeper introduction</h3> +<p> + BookKeeper is a replicated service to reliably log streams of records. In BookKeeper, + servers are "bookies", log streams are "ledgers", and each unit of a log (aka record) is a + "ledger entry". BookKeeper is designed to be reliable; bookies, the servers that store + ledgers, can crash, corrupt data, discard data, but as long as there are enough bookies + behaving correctly the service as a whole behaves correctly. + </p> +<p> + The initial motivation for BookKeeper comes from the namenode of HDFS. Namenodes have to + log operations in a reliable fashion so that recovery is possible in the case of crashes. + We have found the applications for BookKeeper extend far beyond HDFS, however. Essentially, + any application that requires an append storage can replace their implementations with + BookKeeper. BookKeeper has the advantage of scaling throughput with the number of servers. + </p> +<p> + At a high level, a bookkeeper client receives entries from a client application and stores it to + sets of bookies, and there are a few advantages in having such a service: + </p> +<ul> + +<li> + +<p> + We can use hardware that is optimized for such a service. We currently believe that such a + system has to be optimized only for disk I/O; + </p> + +</li> + + +<li> + +<p> + We can have a pool of servers implementing such a log system, and shared among a number of servers; + </p> + +</li> + + +<li> + +<p> + We can have a higher degree of replication with such a pool, which makes sense if the hardware necessary for it is cheaper compared to the one the application uses. + </p> + +</li> + +</ul> +<a name="bk_moreDetail"></a> +<h3 class="h4">In slightly more detail...</h3> +<p> BookKeeper implements highly available logs, and it has been designed with write-ahead logging in mind. Besides high availability + due to the replicated nature of the service, it provides high throughput due to striping. As we write entries in a subset of bookies of an + ensemble and rotate writes across available quorums, we are able to increase throughput with the number of servers for both reads and writes. + Scalability is a property that is possible to achieve in this case due to the use of quorums. Other replication techniques, such as + state-machine replication, do not enable such a property. + </p> +<p> An application first creates a ledger before writing to bookies through a local BookKeeper client instance. + Upon creating a ledger, a BookKeeper client writes metadata about the ledger to ZooKeeper. Each ledger currently + has a single writer. This writer has to execute a close ledger operation before any other client can read from it. + If the writer of a ledger does not close a ledger properly because, for example, it has crashed before having the + opportunity of closing the ledger, then the next client that tries to open a ledger executes a procedure to recover + it. As closing a ledger consists essentially of writing the last entry written to a ledger to ZooKeeper, the recovery + procedure simply finds the last entry written correctly and writes it to ZooKeeper. + </p> +<p> + Note that currently this recovery procedure is executed automatically upon trying to open a ledger and no explicit action is necessary. + Although two clients may try to recover a ledger concurrently, only one will succeed, the first one that is able to create the close znode + for the ledger. + </p> +<a name="bk_basicComponents"></a> +<h3 class="h4">Bookkeeper elements and concepts</h3> +<p> + BookKeeper uses four basic elements: + </p> +<ul> + +<li> + +<p> + +<strong>Ledger</strong>: A ledger is a sequence of entries, and each entry is a sequence of bytes. Entries are + written sequentially to a ledger and at most once. Consequently, ledgers have an append-only semantics; + </p> + +</li> + + +<li> + +<p> + +<strong>BookKeeper client</strong>: A client runs along with a BookKeeper application, and it enables applications + to execute operations on ledgers, such as creating a ledger and writing to it; + </p> + +</li> + + +<li> + +<p> + +<strong>Bookie</strong>: A bookie is a BookKeeper storage server. Bookies store the content of ledgers. For any given + ledger L, we call an <em>ensemble</em> the group of bookies storing the content of L. For performance, we store on + each bookie of an ensemble only a fragment of a ledger. That is, we stripe when writing entries to a ledger such that + each entry is written to sub-group of bookies of the ensemble. + </p> + +</li> + + +<li> + +<p> + +<strong>Metadata storage service</strong>: BookKeeper requires a metadata storage service to store information related + to ledgers and available bookies. We currently use ZooKeeper for such a task. + </p> + +</li> + +</ul> +<a name="bk_initialDesign"></a> +<h3 class="h4">Bookkeeper initial design</h3> +<p> + A set of bookies implements BookKeeper, and we use a quorum-based protocol to replicate data across the bookies. + There are basically two operations to an existing ledger: read and append. Here is the complete API list + (mode detail <a href="bookkeeperProgrammer.html"> + here</a>): + </p> +<ul> + +<li> + +<p> + Create ledger: creates a new empty ledger; + </p> + +</li> + + +<li> + +<p> + Open ledger: opens an existing ledger for reading; + </p> + +</li> + + +<li> + +<p> + Add entry: adds a record to a ledger either synchronously or asynchronously; + </p> + +</li> + + +<li> + +<p> + Read entries: reads a sequence of entries from a ledger either synchronously or asynchronously + </p> + +</li> + +</ul> +<p> + There is only a single client that can write to a ledger. Once that ledger is closed or the client fails, + no more entries can be added. (We take advantage of this behavior to provide our strong guarantees.) + There will not be gaps in the ledger. Fingers get broken, people get roughed up or end up in prison when + books are manipulated, so there is no deleting or changing of entries. + </p> +<table class="ForrestTable" cellspacing="1" cellpadding="4"> +<tr> +<td>BookKeeper Overview</td> +</tr> +<tr> +<td> + + <img alt="" src="images/bk-overview.jpg"> + + </td> +</tr> +</table> +<p> + A simple use of BooKeeper is to implement a write-ahead transaction log. A server maintains an in-memory data structure + (with periodic snapshots for example) and logs changes to that structure before it applies the change. The application + server creates a ledger at startup and store the ledger id and password in a well known place (ZooKeeper maybe). When + it needs to make a change, the server adds an entry with the change information to a ledger and apply the change when + BookKeeper adds the entry successfully. The server can even use asyncAddEntry to queue up many changes for high change + throughput. BooKeeper meticulously logs the changes in order and call the completion functions in order. + </p> +<p> + When the application server dies, a backup server will come online, get the last snapshot and then it will open the + ledger of the old server and read all the entries from the time the snapshot was taken. (Since it doesn't know the + last entry number it will use MAX_INTEGER). Once all the entries have been processed, it will close the ledger and + start a new one for its use. + </p> +<p> + A client library takes care of communicating with bookies and managing entry numbers. An entry has the following fields: + </p> +<table class="ForrestTable" cellspacing="1" cellpadding="4"> +<caption>Entry fields</caption> +<title>Entry fields</title> + + +<tr> + +<th>Field</th> + <th>Type</th> + <th>Description</th> + +</tr> + + +<tr> + +<td>Ledger number</td> + <td>long</td> + <td>The id of the ledger of this entry</td> + +</tr> + +<tr> + +<td>Entry number</td> + <td>long</td> + <td>The id of this entry</td> + +</tr> + + +<tr> + +<td>last confirmed (<em>LC</em>)</td> + <td>long</td> + <td>id of the last recorded entry</td> + +</tr> + +<tr> + +<td>data</td> + <td>byte[]</td> + <td>the entry data (supplied by application)</td> + +</tr> + +<tr> + +<td>authentication code</td> + <td>byte[]</td> + <td>Message authentication code that includes all other fields of the entry</td> + +</tr> + + + +</table> +<p> + The client library generates a ledger entry. None of the fields are modified by the bookies and only the first three + fields are interpreted by the bookies. + </p> +<p> + To add to a ledger, the client generates the entry above using the ledger number. The entry number will be one more + than the last entry generated. The <em>LC</em> field contains the last entry that has been successfully recorded by BookKeeper. + If the client writes entries one at a time, <em>LC</em> is the last entry id. But, if the client is using asyncAddEntry, there + may be many entries in flight. An entry is considered recorded when both of the following conditions are met: + </p> +<ul> + +<li> + +<p> + the entry has been accepted by a quorum of bookies + </p> + +</li> + + +<li> + +<p> + all entries with a lower entry id have been accepted by a quorum of bookies + </p> + +</li> + +</ul> +<p> + +<em>LC</em> seems mysterious right now, but it is too early to explain how we use it; just smile and move on. + </p> +<p> + Once all the other fields have been field in, the client generates an authentication code with all of the previous fields. + The entry is then sent to a quorum of bookies to be recorded. Any failures will result in the entry being sent to a new + quorum of bookies. + </p> +<p> + To read, the client library initially contacts a bookie and starts requesting entries. If an entry is missing or + invalid (a bad MAC for example), the client will make a request to a different bookie. By using quorum writes, + as long as enough bookies are up we are guaranteed to eventually be able to read an entry. + </p> +<a name="bk_metadata"></a> +<h3 class="h4">Bookkeeper metadata management</h3> +<p> + There are some meta data that needs to be made available to BookKeeper clients: + </p> +<ul> + +<li> + +<p> + The available bookies; + </p> + +</li> + + +<li> + +<p> + The list of ledgers; + </p> + +</li> + + +<li> + +<p> + The list of bookies that have been used for a given ledger; + </p> + +</li> + + +<li> + +<p> + The last entry of a ledger; + </p> + +</li> + +</ul> +<p> + We maintain this information in ZooKeeper. Bookies use ephemeral nodes to indicate their availability. Clients + use znodes to track ledger creation and deletion and also to know the end of the ledger and the bookies that + were used to store the ledger. Bookies also watch the ledger list so that they can cleanup ledgers that get deleted. + </p> +<a name="bk_closingOut"></a> +<h3 class="h4">Closing out ledgers</h3> +<p> + The process of closing out the ledger and finding the last ledger is difficult due to the durability guarantees of BookKeeper: + </p> +<ul> + +<li> + +<p> + If an entry has been successfully recorded, it must be readable. + </p> + +</li> + + +<li> + +<p> + If an entry is read once, it must always be available to be read. + </p> + +</li> + +</ul> +<p> + If the ledger was closed gracefully, ZooKeeper will have the last entry and everything will work well. But, if the + BookKeeper client that was writing the ledger dies, there is some recovery that needs to take place. + </p> +<p> + The problematic entries are the ones at the end of the ledger. There can be entries in flight when a BookKeeper client + dies. If the entry only gets to one bookie, the entry should not be readable since the entry will disappear if that bookie + fails. If the entry is only on one bookie, that doesn't mean that the entry has not been recorded successfully; the other + bookies that recorded the entry might have failed. + </p> +<p> + The trick to making everything work is to have a correct idea of a last entry. We do it in roughly three steps: + </p> +<ol> + +<li> + +<p> + Find the entry with the highest last recorded entry, <em>LC</em>; + </p> + +</li> + + +<li> + +<p> + Find the highest consecutively recorded entry, <em>LR</em>; + </p> + +</li> + + +<li> + +<p> + Make sure that all entries between <em>LC</em> and <em>LR</em> are on a quorum of bookies; + </p> + +</li> + + +</ol> +</div> + +<p align="right"> +<font size="-2"></font> +</p> +</div> +<!--+ + |end content + +--> +<div class="clearboth"> </div> +</div> +<div id="footer"> +<!--+ + |start bottomstrip + +--> +<div class="lastmodified"> +<script type="text/javascript"><!-- +document.write("Last Published: " + document.lastModified); +// --></script> +</div> +<div class="copyright"> + Copyright © + 2008 <a href="http://www.apache.org/licenses/";>The Apache Software Foundation.</a> +</div> +<!--+ + |end bottomstrip + +--> +</div> +</body> +</html>
http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/bookkeeperOverview.pdf ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/bookkeeperOverview.pdf b/content/doc/r3.5.4-beta/bookkeeperOverview.pdf new file mode 100644 index 0000000..80aff7f Binary files /dev/null and b/content/doc/r3.5.4-beta/bookkeeperOverview.pdf differ http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/bookkeeperProgrammer.html ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/bookkeeperProgrammer.html b/content/doc/r3.5.4-beta/bookkeeperProgrammer.html new file mode 100644 index 0000000..acb0b2b --- /dev/null +++ b/content/doc/r3.5.4-beta/bookkeeperProgrammer.html @@ -0,0 +1,1083 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd";> +<html> +<head> +<META http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<meta content="Apache Forrest" name="Generator"> +<meta name="Forrest-version" content="0.9"> +<meta name="Forrest-skin-name" content="pelt"> +<title>BookKeeper Getting Started Guide</title> +<link type="text/css" href="skin/basic.css" rel="stylesheet"> +<link media="screen" type="text/css" href="skin/screen.css" rel="stylesheet"> +<link media="print" type="text/css" href="skin/print.css" rel="stylesheet"> +<link type="text/css" href="skin/profile.css" rel="stylesheet"> +<script src="skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="skin/fontsize.js" language="javascript" type="text/javascript"></script> +<link rel="shortcut icon" href="images/favicon.ico"> +</head> +<body onload="init()"> +<script type="text/javascript">ndeSetTextSize();</script> +<div id="top"> +<!--+ + |breadtrail + +--> +<div class="breadtrail"> +<a href="http://www.apache.org/";>Apache</a> > <a href="http://zookeeper.apache.org/";>ZooKeeper</a> > <a href="http://zookeeper.apache.org/";>ZooKeeper</a><script src="skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script> +</div> +<!--+ + |header + +--> +<div class="header"> +<!--+ + |start group logo + +--> +<div class="grouplogo"> +<a href="http://hadoop.apache.org/";><img class="logoImage" alt="Hadoop" src="images/hadoop-logo.jpg" title="Apache Hadoop"></a> +</div> +<!--+ + |end group logo + +--> +<!--+ + |start Project Logo + +--> +<div class="projectlogo"> +<a href="http://zookeeper.apache.org/";><img class="logoImage" alt="ZooKeeper" src="images/zookeeper_small.gif" title="ZooKeeper: distributed coordination"></a> +</div> +<!--+ + |end Project Logo + +--> +<!--+ + |start Search + +--> +<div class="searchbox"> +<form action="http://www.google.com/search"; method="get" class="roundtopsmall"> +<input value="zookeeper.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google"> + <input name="Search" value="Search" type="submit"> +</form> +</div> +<!--+ + |end search + +--> +<!--+ + |start Tabs + +--> +<ul id="tabs"> +<li> +<a class="unselected" href="http://zookeeper.apache.org/";>Project</a> +</li> +<li> +<a class="unselected" href="https://cwiki.apache.org/confluence/display/ZOOKEEPER/";>Wiki</a> +</li> +<li class="current"> +<a class="selected" href="index.html">ZooKeeper 3.4 Documentation</a> +</li> +</ul> +<!--+ + |end Tabs + +--> +</div> +</div> +<div id="main"> +<div id="publishedStrip"> +<!--+ + |start Subtabs + +--> +<div id="level2tabs"></div> +<!--+ + |end Endtabs + +--> +<script type="text/javascript"><!-- +document.write("Last Published: " + document.lastModified); +// --></script> +</div> +<!--+ + |breadtrail + +--> +<div class="breadtrail"> + + + </div> +<!--+ + |start Menu, mainarea + +--> +<!--+ + |start Menu + +--> +<div id="menu"> +<div onclick="SwitchMenu('menu_1.1', 'skin/')" id="menu_1.1Title" class="menutitle">Overview</div> +<div id="menu_1.1" class="menuitemgroup"> +<div class="menuitem"> +<a href="index.html">Welcome</a> +</div> +<div class="menuitem"> +<a href="zookeeperOver.html">Overview</a> +</div> +<div class="menuitem"> +<a href="zookeeperStarted.html">Getting Started</a> +</div> +<div class="menuitem"> +<a href="releasenotes.html">Release Notes</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.2', 'skin/')" id="menu_1.2Title" class="menutitle">Developer</div> +<div id="menu_1.2" class="menuitemgroup"> +<div class="menuitem"> +<a href="api/index.html">API Docs</a> +</div> +<div class="menuitem"> +<a href="zookeeperProgrammers.html">Programmer's Guide</a> +</div> +<div class="menuitem"> +<a href="javaExample.html">Java Example</a> +</div> +<div class="menuitem"> +<a href="zookeeperTutorial.html">Barrier and Queue Tutorial</a> +</div> +<div class="menuitem"> +<a href="recipes.html">Recipes</a> +</div> +</div> +<div onclick="SwitchMenu('menu_selected_1.3', 'skin/')" id="menu_selected_1.3Title" class="menutitle" style="background-image: url('skin/images/chapter_open.gif');">BookKeeper</div> +<div id="menu_selected_1.3" class="selectedmenuitemgroup" style="display: block;"> +<div class="menuitem"> +<a href="bookkeeperStarted.html">Getting started</a> +</div> +<div class="menuitem"> +<a href="bookkeeperOverview.html">Overview</a> +</div> +<div class="menuitem"> +<a href="bookkeeperConfig.html">Setup guide</a> +</div> +<div class="menupage"> +<div class="menupagetitle">Programmer's guide</div> +</div> +</div> +<div onclick="SwitchMenu('menu_1.4', 'skin/')" id="menu_1.4Title" class="menutitle">Admin & Ops</div> +<div id="menu_1.4" class="menuitemgroup"> +<div class="menuitem"> +<a href="zookeeperAdmin.html">Administrator's Guide</a> +</div> +<div class="menuitem"> +<a href="zookeeperQuotas.html">Quota Guide</a> +</div> +<div class="menuitem"> +<a href="zookeeperJMX.html">JMX</a> +</div> +<div class="menuitem"> +<a href="zookeeperObservers.html">Observers Guide</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.5', 'skin/')" id="menu_1.5Title" class="menutitle">Contributor</div> +<div id="menu_1.5" class="menuitemgroup"> +<div class="menuitem"> +<a href="zookeeperInternals.html">ZooKeeper Internals</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.6', 'skin/')" id="menu_1.6Title" class="menutitle">Miscellaneous</div> +<div id="menu_1.6" class="menuitemgroup"> +<div class="menuitem"> +<a href="https://cwiki.apache.org/confluence/display/ZOOKEEPER";>Wiki</a> +</div> +<div class="menuitem"> +<a href="https://cwiki.apache.org/confluence/display/ZOOKEEPER/FAQ";>FAQ</a> +</div> +<div class="menuitem"> +<a href="http://zookeeper.apache.org/mailing_lists.html";>Mailing Lists</a> +</div> +</div> +<div id="credit"></div> +<div id="roundbottom"> +<img style="display: none" class="corner" height="15" width="15" alt="" src="skin/images/rc-b-l-15-1body-2menu-3menu.png"></div> +<!--+ + |alternative credits + +--> +<div id="credit2"></div> +</div> +<!--+ + |end Menu + +--> +<!--+ + |start content + +--> +<div id="content"> +<div title="Portable Document Format" class="pdflink"> +<a class="dida" href="bookkeeperProgrammer.pdf"><img alt="PDF -icon" src="skin/images/pdfdoc.gif" class="skin"><br> + PDF</a> +</div> +<h1>BookKeeper Getting Started Guide</h1> +<div id="front-matter"> +<div id="minitoc-area"> +<ul class="minitoc"> +<li> +<a href="#bk_GettingStarted">Programming with BookKeeper</a> +<ul class="minitoc"> +<li> +<a href="#bk_instance"> Instantiating BookKeeper.</a> +</li> +<li> +<a href="#bk_createLedger"> Creating a ledger. </a> +</li> +<li> +<a href="#bk_writeLedger"> Adding entries to a ledger. </a> +</li> +<li> +<a href="#bk_closeLedger"> Closing a ledger. </a> +</li> +<li> +<a href="#bk_openLedger"> Opening a ledger. </a> +</li> +<li> +<a href="#bk_readLedger"> Reading from ledger </a> +</li> +<li> +<a href="#bk_deleteLedger"> Deleting a ledger </a> +</li> +</ul> +</li> +</ul> +</div> +</div> + + + + +<a name="bk_GettingStarted"></a> +<h2 class="h3">Programming with BookKeeper</h2> +<div class="section"> +<ul> + +<li> + +<p> +<a href="#bk_instance"> Instantiating BookKeeper.</a> +</p> + +</li> + + +<li> + +<p> +<a href="#bk_createLedger"> Creating a ledger. </a> +</p> + +</li> + + +<li> + +<p> +<a href="#bk_writeLedger"> Adding entries to a ledger. </a> +</p> + +</li> + + +<li> + +<p> +<a href="#bk_closeLedger"> Closing a ledger. </a> +</p> + +</li> + + +<li> + +<p> +<a href="#bk_openLedger"> Opening a ledger. </a> +</p> + +</li> + + +<li> + +<p> +<a href="#bk_readLedger"> Reading from ledger </a> +</p> + +</li> + + +<li> + +<p> +<a href="#bk_deleteLedger"> Deleting a ledger </a> +</p> + +</li> + + +</ul> +<a name="bk_instance"></a> +<h3 class="h4"> Instantiating BookKeeper.</h3> +<p> + The first step to use BookKeeper is to instantiate a BookKeeper object: + </p> +<p> + +<span class="codefrag computeroutput"> + org.apache.bookkeeper.BookKeeper + </span> + +</p> +<p> + There are three BookKeeper constructors: + </p> +<p> + +<span class="codefrag computeroutput"> + public BookKeeper(String servers) + throws KeeperException, IOException + </span> + +</p> +<p> + where: + </p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">servers</span> is a comma-separated list of ZooKeeper servers. + </p> + +</li> + +</ul> +<p> + +<span class="codefrag computeroutput"> + public BookKeeper(ZooKeeper zk) + throws InterruptedException, KeeperException + </span> + +</p> +<p> + where: + </p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">zk</span> is a ZooKeeper object. This constructor is useful when + the application also using ZooKeeper and wants to have a single instance of ZooKeeper. + </p> + +</li> + +</ul> +<p> + +<span class="codefrag computeroutput"> + public BookKeeper(ZooKeeper zk, ClientSocketChannelFactory channelFactory) + throws InterruptedException, KeeperException + </span> + +</p> +<p> + where: + </p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">zk</span> is a ZooKeeper object. This constructor is useful when + the application also using ZooKeeper and wants to have a single instance of ZooKeeper. + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">channelFactory</span> is a netty channel object + (<span class="codefrag computeroutput">org.jboss.netty.channel.socket</span>). + </p> + +</li> + +</ul> +<a name="bk_createLedger"></a> +<h3 class="h4"> Creating a ledger. </h3> +<p> Before writing entries to BookKeeper, it is necessary to create a ledger. + With the current BookKeeper API, it is possible to create a ledger both synchronously + or asynchronously. The following methods belong + to <span class="codefrag computeroutput">org.apache.bookkeeper.client.BookKeeper</span>. + </p> +<p> + +<strong>Synchronous call:</strong> + +</p> +<p> + +<span class="codefrag computeroutput"> + public LedgerHandle createLedger(int ensSize, int qSize, DigestType type, byte passwd[]) + throws KeeperException, InterruptedException, + IOException, BKException + </span> + +</p> +<p> + where: + </p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">ensSize</span> is the number of bookies (ensemble size); + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">qSize</span> is the write quorum size; + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">type</span> is the type of digest used with entries: either MAC or CRC32. + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">passwd</span> is a password that authorizes the client to write to the + ledger being created. + </p> + +</li> + +</ul> +<p> + All further operations on a ledger are invoked through the <span class="codefrag computeroutput">LedgerHandle</span> + object returned. + </p> +<p> + As a convenience, we provide a <span class="codefrag computeroutput">createLedger</span> with default parameters (3,2,VERIFIABLE), + and the only two input parameters it requires are a digest type and a password. + </p> +<p> + +<strong>Asynchronous call:</strong> + +</p> +<p> + +<span class="codefrag computeroutput"> + public void asyncCreateLedger(int ensSize, + int qSize, + DigestType type, + byte passwd[], + CreateCallback cb, + Object ctx + ) + </span> + +</p> +<p> + The parameters are the same of the synchronous version, with the + exception of <span class="codefrag computeroutput">cb</span> and <span class="codefrag computeroutput">ctx</span>. <span class="codefrag computeroutput">CreateCallback</span> + is an interface in <span class="codefrag computeroutput">org.apache.bookkeeper.client.AsyncCallback</span>, and + a class implementing it has to implement a method called <span class="codefrag computeroutput">createComplete</span> + that has the following signature: + </p> +<p> + +<span class="codefrag computeroutput"> + void createComplete(int rc, LedgerHandle lh, Object ctx); + </span> + +</p> +<p> + where: + </p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">rc</span> is a return code (please refer to <span class="codefrag computeroutput">org.apache.bookeeper.client.BKException</span> for a list); + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">lh</span> is a <span class="codefrag computeroutput">LedgerHandle</span> object to manipulate a ledger; + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">ctx</span> is a control object for accountability purposes. It can be essentially any object the application is happy with. + </p> + +</li> + +</ul> +<p> + The <span class="codefrag computeroutput">ctx</span> object passed as a parameter to the call to create a ledger + is the one same returned in the callback. + </p> +<a name="bk_writeLedger"></a> +<h3 class="h4"> Adding entries to a ledger. </h3> +<p> + Once we have a ledger handle <span class="codefrag computeroutput">lh</span> obtained through a call to create a ledger, we + can start writing entries. As with creating ledgers, we can write both synchronously and + asynchronously. The following methods belong + to <span class="codefrag computeroutput">org.apache.bookkeeper.client.LedgerHandle</span>. + </p> +<p> + +<strong>Synchronous call:</strong> + +</p> +<p> + +<span class="codefrag computeroutput"> + public long addEntry(byte[] data) + throws InterruptedException + </span> + +</p> +<p> + where: + </p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">data</span> is a byte array; + </p> + +</li> + +</ul> +<p> + A call to <span class="codefrag computeroutput">addEntry</span> returns the status of the operation (please refer to <span class="codefrag computeroutput">org.apache.bookeeper.client.BKDefs</span> for a list); + </p> +<p> + +<strong>Asynchronous call:</strong> + +</p> +<p> + +<span class="codefrag computeroutput"> + public void asyncAddEntry(byte[] data, AddCallback cb, Object ctx) + </span> + +</p> +<p> + It also takes a byte array as the sequence of bytes to be stored as an entry. Additionaly, it takes + a callback object <span class="codefrag computeroutput">cb</span> and a control object <span class="codefrag computeroutput">ctx</span>. The callback object must implement + the <span class="codefrag computeroutput">AddCallback</span> interface in <span class="codefrag computeroutput">org.apache.bookkeeper.client.AsyncCallback</span>, and + a class implementing it has to implement a method called <span class="codefrag computeroutput">addComplete</span> + that has the following signature: + </p> +<p> + +<span class="codefrag computeroutput"> + void addComplete(int rc, LedgerHandle lh, long entryId, Object ctx); + </span> + +</p> +<p> + where: + </p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">rc</span> is a return code (please refer to <span class="codefrag computeroutput">org.apache.bookeeper.client.BKDefs</span> for a list); + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">lh</span> is a <span class="codefrag computeroutput">LedgerHandle</span> object to manipulate a ledger; + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">entryId</span> is the identifier of entry associated with this request; + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">ctx</span> is control object used for accountability purposes. It can be any object the application is happy with. + </p> + +</li> + +</ul> +<a name="bk_closeLedger"></a> +<h3 class="h4"> Closing a ledger. </h3> +<p> + Once a client is done writing, it closes the ledger. The following methods belong + to <span class="codefrag computeroutput">org.apache.bookkeeper.client.LedgerHandle</span>. + </p> +<p> + +<strong>Synchronous close:</strong> + +</p> +<p> + +<span class="codefrag computeroutput"> + public void close() + throws InterruptedException + </span> + +</p> +<p> + It takes no input parameters. + </p> +<p> + +<strong>Asynchronous close:</strong> + +</p> +<p> + +<span class="codefrag computeroutput"> + public void asyncClose(CloseCallback cb, Object ctx) + throws InterruptedException + </span> + +</p> +<p> + It takes a callback object <span class="codefrag computeroutput">cb</span> and a control object <span class="codefrag computeroutput">ctx</span>. The callback object must implement + the <span class="codefrag computeroutput">CloseCallback</span> interface in <span class="codefrag computeroutput">org.apache.bookkeeper.client.AsyncCallback</span>, and + a class implementing it has to implement a method called <span class="codefrag computeroutput">closeComplete</span> + that has the following signature: + </p> +<p> + +<span class="codefrag computeroutput"> + void closeComplete(int rc, LedgerHandle lh, Object ctx) + </span> + +</p> +<p> + where: + </p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">rc</span> is a return code (please refer to <span class="codefrag computeroutput">org.apache.bookeeper.client.BKDefs</span> for a list); + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">lh</span> is a <span class="codefrag computeroutput">LedgerHandle</span> object to manipulate a ledger; + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">ctx</span> is control object used for accountability purposes. + </p> + +</li> + +</ul> +<a name="bk_openLedger"></a> +<h3 class="h4"> Opening a ledger. </h3> +<p> + To read from a ledger, a client must open it first. The following methods belong + to <span class="codefrag computeroutput">org.apache.bookkeeper.client.BookKeeper</span>. + </p> +<p> + +<strong>Synchronous open:</strong> + +</p> +<p> + +<span class="codefrag computeroutput"> + public LedgerHandle openLedger(long lId, DigestType type, byte passwd[]) + throws InterruptedException, BKException + </span> + +</p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">ledgerId</span> is the ledger identifier; + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">type</span> is the type of digest used with entries: either MAC or CRC32. + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">passwd</span> is a password to access the ledger (used only in the case of <span class="codefrag computeroutput">VERIFIABLE</span> ledgers); + </p> + +</li> + +</ul> +<p> + +<strong>Asynchronous open:</strong> + +</p> +<p> + +<span class="codefrag computeroutput"> + public void asyncOpenLedger(long lId, DigestType type, byte passwd[], OpenCallback cb, Object ctx) + </span> + +</p> +<p> + It also takes a a ledger identifier and a password. Additionaly, it takes a callback object + <span class="codefrag computeroutput">cb</span> and a control object <span class="codefrag computeroutput">ctx</span>. The callback object must implement + the <span class="codefrag computeroutput">OpenCallback</span> interface in <span class="codefrag computeroutput">org.apache.bookkeeper.client.AsyncCallback</span>, and + a class implementing it has to implement a method called <span class="codefrag computeroutput">openComplete</span> + that has the following signature: + </p> +<p> + +<span class="codefrag computeroutput"> + public void openComplete(int rc, LedgerHandle lh, Object ctx) + </span> + +</p> +<p> + where: + </p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">rc</span> is a return code (please refer to <span class="codefrag computeroutput">org.apache.bookeeper.client.BKDefs</span> for a list); + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">lh</span> is a <span class="codefrag computeroutput">LedgerHandle</span> object to manipulate a ledger; + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">ctx</span> is control object used for accountability purposes. + </p> + +</li> + +</ul> +<a name="bk_readLedger"></a> +<h3 class="h4"> Reading from ledger </h3> +<p> + Read calls may request one or more consecutive entries. The following methods belong + to <span class="codefrag computeroutput">org.apache.bookkeeper.client.LedgerHandle</span>. + </p> +<p> + +<strong>Synchronous read:</strong> + +</p> +<p> + +<span class="codefrag computeroutput"> + public Enumeration<LedgerEntry> readEntries(long firstEntry, long lastEntry) + throws InterruptedException, BKException + </span> + +</p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">firstEntry</span> is the identifier of the first entry in the sequence of entries to read; + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">lastEntry</span> is the identifier of the last entry in the sequence of entries to read. + </p> + +</li> + +</ul> +<p> + +<strong>Asynchronous read:</strong> + +</p> +<p> + +<span class="codefrag computeroutput"> + public void asyncReadEntries(long firstEntry, + long lastEntry, ReadCallback cb, Object ctx) + throws BKException, InterruptedException + </span> + +</p> +<p> + It also takes a first and a last entry identifiers. Additionaly, it takes a callback object + <span class="codefrag computeroutput">cb</span> and a control object <span class="codefrag computeroutput">ctx</span>. The callback object must implement + the <span class="codefrag computeroutput">ReadCallback</span> interface in <span class="codefrag computeroutput">org.apache.bookkeeper.client.AsyncCallback</span>, and + a class implementing it has to implement a method called <span class="codefrag computeroutput">readComplete</span> + that has the following signature: + </p> +<p> + +<span class="codefrag computeroutput"> + void readComplete(int rc, LedgerHandle lh, Enumeration<LedgerEntry> seq, Object ctx) + </span> + +</p> +<p> + where: + </p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">rc</span> is a return code (please refer to <span class="codefrag computeroutput">org.apache.bookeeper.client.BKDefs</span> for a list); + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">lh</span> is a <span class="codefrag computeroutput">LedgerHandle</span> object to manipulate a ledger; + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">seq</span> is a <span class="codefrag computeroutput">Enumeration<LedgerEntry> </span> object to containing the list of entries requested; + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">ctx</span> is control object used for accountability purposes. + </p> + +</li> + +</ul> +<a name="bk_deleteLedger"></a> +<h3 class="h4"> Deleting a ledger </h3> +<p> + Once a client is done with a ledger and is sure that nobody will ever need to read from it again, they can delete the ledger. + The following methods belong to <span class="codefrag computeroutput">org.apache.bookkeeper.client.BookKeeper</span>. + </p> +<p> + +<strong>Synchronous delete:</strong> + +</p> +<p> + +<span class="codefrag computeroutput"> + public void deleteLedger(long lId) throws InterruptedException, BKException + </span> + +</p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">lId</span> is the ledger identifier; + </p> + +</li> + +</ul> +<p> + +<strong>Asynchronous delete:</strong> + +</p> +<p> + +<span class="codefrag computeroutput"> + public void asyncDeleteLedger(long lId, DeleteCallback cb, Object ctx) + </span> + +</p> +<p> + It takes a ledger identifier. Additionally, it takes a callback object + <span class="codefrag computeroutput">cb</span> and a control object <span class="codefrag computeroutput">ctx</span>. The callback object must implement + the <span class="codefrag computeroutput">DeleteCallback</span> interface in <span class="codefrag computeroutput">org.apache.bookkeeper.client.AsyncCallback</span>, and + a class implementing it has to implement a method called <span class="codefrag computeroutput">deleteComplete</span> + that has the following signature: + </p> +<p> + +<span class="codefrag computeroutput"> + void deleteComplete(int rc, Object ctx) + </span> + +</p> +<p> + where: + </p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">rc</span> is a return code (please refer to <span class="codefrag computeroutput">org.apache.bookeeper.client.BKDefs</span> for a list); + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">ctx</span> is control object used for accountability purposes. + </p> + +</li> + +</ul> +</div> + +<p align="right"> +<font size="-2"></font> +</p> +</div> +<!--+ + |end content + +--> +<div class="clearboth"> </div> +</div> +<div id="footer"> +<!--+ + |start bottomstrip + +--> +<div class="lastmodified"> +<script type="text/javascript"><!-- +document.write("Last Published: " + document.lastModified); +// --></script> +</div> +<div class="copyright"> + Copyright © + 2008 <a href="http://www.apache.org/licenses/";>The Apache Software Foundation.</a> +</div> +<!--+ + |end bottomstrip + +--> +</div> +</body> +</html> http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/bookkeeperProgrammer.pdf ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/bookkeeperProgrammer.pdf b/content/doc/r3.5.4-beta/bookkeeperProgrammer.pdf new file mode 100644 index 0000000..8756828 Binary files /dev/null and b/content/doc/r3.5.4-beta/bookkeeperProgrammer.pdf differ http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/bookkeeperStarted.html ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/bookkeeperStarted.html b/content/doc/r3.5.4-beta/bookkeeperStarted.html new file mode 100644 index 0000000..d039ef4 --- /dev/null +++ b/content/doc/r3.5.4-beta/bookkeeperStarted.html @@ -0,0 +1,448 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd";> +<html> +<head> +<META http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<meta content="Apache Forrest" name="Generator"> +<meta name="Forrest-version" content="0.9"> +<meta name="Forrest-skin-name" content="pelt"> +<title>BookKeeper Getting Started Guide</title> +<link type="text/css" href="skin/basic.css" rel="stylesheet"> +<link media="screen" type="text/css" href="skin/screen.css" rel="stylesheet"> +<link media="print" type="text/css" href="skin/print.css" rel="stylesheet"> +<link type="text/css" href="skin/profile.css" rel="stylesheet"> +<script src="skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="skin/fontsize.js" language="javascript" type="text/javascript"></script> +<link rel="shortcut icon" href="images/favicon.ico"> +</head> +<body onload="init()"> +<script type="text/javascript">ndeSetTextSize();</script> +<div id="top"> +<!--+ + |breadtrail + +--> +<div class="breadtrail"> +<a href="http://www.apache.org/";>Apache</a> > <a href="http://zookeeper.apache.org/";>ZooKeeper</a> > <a href="http://zookeeper.apache.org/";>ZooKeeper</a><script src="skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script> +</div> +<!--+ + |header + +--> +<div class="header"> +<!--+ + |start group logo + +--> +<div class="grouplogo"> +<a href="http://hadoop.apache.org/";><img class="logoImage" alt="Hadoop" src="images/hadoop-logo.jpg" title="Apache Hadoop"></a> +</div> +<!--+ + |end group logo + +--> +<!--+ + |start Project Logo + +--> +<div class="projectlogo"> +<a href="http://zookeeper.apache.org/";><img class="logoImage" alt="ZooKeeper" src="images/zookeeper_small.gif" title="ZooKeeper: distributed coordination"></a> +</div> +<!--+ + |end Project Logo + +--> +<!--+ + |start Search + +--> +<div class="searchbox"> +<form action="http://www.google.com/search"; method="get" class="roundtopsmall"> +<input value="zookeeper.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google"> + <input name="Search" value="Search" type="submit"> +</form> +</div> +<!--+ + |end search + +--> +<!--+ + |start Tabs + +--> +<ul id="tabs"> +<li> +<a class="unselected" href="http://zookeeper.apache.org/";>Project</a> +</li> +<li> +<a class="unselected" href="https://cwiki.apache.org/confluence/display/ZOOKEEPER/";>Wiki</a> +</li> +<li class="current"> +<a class="selected" href="index.html">ZooKeeper 3.4 Documentation</a> +</li> +</ul> +<!--+ + |end Tabs + +--> +</div> +</div> +<div id="main"> +<div id="publishedStrip"> +<!--+ + |start Subtabs + +--> +<div id="level2tabs"></div> +<!--+ + |end Endtabs + +--> +<script type="text/javascript"><!-- +document.write("Last Published: " + document.lastModified); +// --></script> +</div> +<!--+ + |breadtrail + +--> +<div class="breadtrail"> + + + </div> +<!--+ + |start Menu, mainarea + +--> +<!--+ + |start Menu + +--> +<div id="menu"> +<div onclick="SwitchMenu('menu_1.1', 'skin/')" id="menu_1.1Title" class="menutitle">Overview</div> +<div id="menu_1.1" class="menuitemgroup"> +<div class="menuitem"> +<a href="index.html">Welcome</a> +</div> +<div class="menuitem"> +<a href="zookeeperOver.html">Overview</a> +</div> +<div class="menuitem"> +<a href="zookeeperStarted.html">Getting Started</a> +</div> +<div class="menuitem"> +<a href="releasenotes.html">Release Notes</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.2', 'skin/')" id="menu_1.2Title" class="menutitle">Developer</div> +<div id="menu_1.2" class="menuitemgroup"> +<div class="menuitem"> +<a href="api/index.html">API Docs</a> +</div> +<div class="menuitem"> +<a href="zookeeperProgrammers.html">Programmer's Guide</a> +</div> +<div class="menuitem"> +<a href="javaExample.html">Java Example</a> +</div> +<div class="menuitem"> +<a href="zookeeperTutorial.html">Barrier and Queue Tutorial</a> +</div> +<div class="menuitem"> +<a href="recipes.html">Recipes</a> +</div> +</div> +<div onclick="SwitchMenu('menu_selected_1.3', 'skin/')" id="menu_selected_1.3Title" class="menutitle" style="background-image: url('skin/images/chapter_open.gif');">BookKeeper</div> +<div id="menu_selected_1.3" class="selectedmenuitemgroup" style="display: block;"> +<div class="menupage"> +<div class="menupagetitle">Getting started</div> +</div> +<div class="menuitem"> +<a href="bookkeeperOverview.html">Overview</a> +</div> +<div class="menuitem"> +<a href="bookkeeperConfig.html">Setup guide</a> +</div> +<div class="menuitem"> +<a href="bookkeeperProgrammer.html">Programmer's guide</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.4', 'skin/')" id="menu_1.4Title" class="menutitle">Admin & Ops</div> +<div id="menu_1.4" class="menuitemgroup"> +<div class="menuitem"> +<a href="zookeeperAdmin.html">Administrator's Guide</a> +</div> +<div class="menuitem"> +<a href="zookeeperQuotas.html">Quota Guide</a> +</div> +<div class="menuitem"> +<a href="zookeeperJMX.html">JMX</a> +</div> +<div class="menuitem"> +<a href="zookeeperObservers.html">Observers Guide</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.5', 'skin/')" id="menu_1.5Title" class="menutitle">Contributor</div> +<div id="menu_1.5" class="menuitemgroup"> +<div class="menuitem"> +<a href="zookeeperInternals.html">ZooKeeper Internals</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.6', 'skin/')" id="menu_1.6Title" class="menutitle">Miscellaneous</div> +<div id="menu_1.6" class="menuitemgroup"> +<div class="menuitem"> +<a href="https://cwiki.apache.org/confluence/display/ZOOKEEPER";>Wiki</a> +</div> +<div class="menuitem"> +<a href="https://cwiki.apache.org/confluence/display/ZOOKEEPER/FAQ";>FAQ</a> +</div> +<div class="menuitem"> +<a href="http://zookeeper.apache.org/mailing_lists.html";>Mailing Lists</a> +</div> +</div> +<div id="credit"></div> +<div id="roundbottom"> +<img style="display: none" class="corner" height="15" width="15" alt="" src="skin/images/rc-b-l-15-1body-2menu-3menu.png"></div> +<!--+ + |alternative credits + +--> +<div id="credit2"></div> +</div> +<!--+ + |end Menu + +--> +<!--+ + |start content + +--> +<div id="content"> +<div title="Portable Document Format" class="pdflink"> +<a class="dida" href="bookkeeperStarted.pdf"><img alt="PDF -icon" src="skin/images/pdfdoc.gif" class="skin"><br> + PDF</a> +</div> +<h1>BookKeeper Getting Started Guide</h1> +<div id="front-matter"> +<div id="minitoc-area"> +<ul class="minitoc"> +<li> +<a href="#bk_GettingStarted">Getting Started: Setting up BookKeeper to write logs.</a> +<ul class="minitoc"> +<li> +<a href="#bk_Prerequisites">Pre-requisites</a> +</li> +<li> +<a href="#bk_Download">Download</a> +</li> +<li> +<a href="#bk_localBK">LocalBookKeeper</a> +</li> +<li> +<a href="#bk_setupBookies">Setting up bookies</a> +</li> +<li> +<a href="#bk_setupZK">Setting up ZooKeeper</a> +</li> +<li> +<a href="#bk_example">Example</a> +</li> +</ul> +</li> +</ul> +</div> +</div> + + + + +<a name="bk_GettingStarted"></a> +<h2 class="h3">Getting Started: Setting up BookKeeper to write logs.</h2> +<div class="section"> +<p>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 + <a href="bookkeeperProgrammer.html">BookKeeper Programmer's Guide</a>. + </p> +<a name="bk_Prerequisites"></a> +<h3 class="h4">Pre-requisites</h3> +<p>See <a href="bookkeeperConfig.html#bk_sysReq"> + System Requirements</a> in the Admin guide.</p> +<a name="bk_Download"></a> +<h3 class="h4">Download</h3> +<p> BookKeeper is distributed along with ZooKeeper. To get a ZooKeeper distribution, + download a recent + <a href="http://zookeeper.apache.org/releases.html";> + stable</a> release from one of the Apache Download + Mirrors.</p> +<a name="bk_localBK"></a> +<h3 class="h4">LocalBookKeeper</h3> +<p> 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. + </p> +<a name="bk_setupBookies"></a> +<h3 class="h4">Setting up bookies</h3> +<p> 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. + </p> +<p> + For each bookie, we need to execute a command like the following: + </p> +<p> +<span class="codefrag computeroutput"> + java -cp .:./zookeeper-<version>-bookkeeper.jar:./zookeeper-<version>.jar\ + :lib/slf4j-api-1.6.1.jar:lib/slf4j-log4j12-1.6.1.jar:lib/log4j-1.2.15.jar -Dlog4j.configuration=log4j.properties\ + org.apache.bookkeeper.proto.BookieServer 3181 127.0.0.1:2181 /path_to_log_device/\ + /path_to_ledger_device/ + </span> +</p> +<p> "/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. 127.0.0.1:2181 is the hostname:port + for the ZooKeeper server. In this example, the standalone ZooKeeper server is running locally on port 2181. + If we had multiple ZooKeeper servers, this parameter would be a comma separated list of all the hostname:port + values corresponding to them. + </p> +<a name="bk_setupZK"></a> +<h3 class="h4">Setting up ZooKeeper</h3> +<p> 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: + </p> +<ol> + +<li> + +<p> +<span class="codefrag computeroutput"> + /ledgers + </span> +</p> + +</li> + + +<li> + +<p> +<span class="codefrag computeroutput"> + /ledgers/available + </span> +</p> + +</li> + + +<li> + +<p> 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 + <span class="codefrag computeroutput">/ledgers/available/bookie.foo.com:3181</span>. + </p> + +</li> + +</ol> +<a name="bk_example"></a> +<h3 class="h4">Example</h3> +<p> + In the following excerpt of code, we: + </p> +<ol> + +<li> + +<p> + Create a ledger; + </p> + +</li> + + +<li> + +<p> + Write to the ledger; + </p> + +</li> + + +<li> + +<p> + Close the ledger; + </p> + +</li> + + +<li> + +<p> + Open the same ledger for reading; + </p> + +</li> + + +<li> + +<p> + Read from the ledger; + </p> + +</li> + + +<li> + +<p> + Close the ledger again; + </p> + +</li> + +</ol> +<pre class="code"> +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); + +Enumeration<LedgerEntry> 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(); + </pre> +</div> + +<p align="right"> +<font size="-2"></font> +</p> +</div> +<!--+ + |end content + +--> +<div class="clearboth"> </div> +</div> +<div id="footer"> +<!--+ + |start bottomstrip + +--> +<div class="lastmodified"> +<script type="text/javascript"><!-- +document.write("Last Published: " + document.lastModified); +// --></script> +</div> +<div class="copyright"> + Copyright © + 2008 <a href="http://www.apache.org/licenses/";>The Apache Software Foundation.</a> +</div> +<!--+ + |end bottomstrip + +--> +</div> +</body> +</html> http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/bookkeeperStarted.pdf ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/bookkeeperStarted.pdf b/content/doc/r3.5.4-beta/bookkeeperStarted.pdf new file mode 100644 index 0000000..42e4987 Binary files /dev/null and b/content/doc/r3.5.4-beta/bookkeeperStarted.pdf differ http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/bookkeeperStream.html ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/bookkeeperStream.html b/content/doc/r3.5.4-beta/bookkeeperStream.html new file mode 100644 index 0000000..0566340 --- /dev/null +++ b/content/doc/r3.5.4-beta/bookkeeperStream.html @@ -0,0 +1,612 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd";> +<html> +<head> +<META http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<meta content="Apache Forrest" name="Generator"> +<meta name="Forrest-version" content="0.9"> +<meta name="Forrest-skin-name" content="pelt"> +<title>Streaming with BookKeeper</title> +<link type="text/css" href="skin/basic.css" rel="stylesheet"> +<link media="screen" type="text/css" href="skin/screen.css" rel="stylesheet"> +<link media="print" type="text/css" href="skin/print.css" rel="stylesheet"> +<link type="text/css" href="skin/profile.css" rel="stylesheet"> +<script src="skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="skin/fontsize.js" language="javascript" type="text/javascript"></script> +<link rel="shortcut icon" href="images/favicon.ico"> +</head> +<body onload="init()"> +<script type="text/javascript">ndeSetTextSize();</script> +<div id="top"> +<!--+ + |breadtrail + +--> +<div class="breadtrail"> +<a href="http://www.apache.org/";>Apache</a> > <a href="http://zookeeper.apache.org/";>ZooKeeper</a> > <a href="http://zookeeper.apache.org/";>ZooKeeper</a><script src="skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script> +</div> +<!--+ + |header + +--> +<div class="header"> +<!--+ + |start group logo + +--> +<div class="grouplogo"> +<a href="http://hadoop.apache.org/";><img class="logoImage" alt="Hadoop" src="images/hadoop-logo.jpg" title="Apache Hadoop"></a> +</div> +<!--+ + |end group logo + +--> +<!--+ + |start Project Logo + +--> +<div class="projectlogo"> +<a href="http://zookeeper.apache.org/";><img class="logoImage" alt="ZooKeeper" src="images/zookeeper_small.gif" title="ZooKeeper: distributed coordination"></a> +</div> +<!--+ + |end Project Logo + +--> +<!--+ + |start Search + +--> +<div class="searchbox"> +<form action="http://www.google.com/search"; method="get" class="roundtopsmall"> +<input value="zookeeper.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google"> + <input name="Search" value="Search" type="submit"> +</form> +</div> +<!--+ + |end search + +--> +<!--+ + |start Tabs + +--> +<ul id="tabs"> +<li> +<a class="unselected" href="http://zookeeper.apache.org/";>Project</a> +</li> +<li> +<a class="unselected" href="https://cwiki.apache.org/confluence/display/ZOOKEEPER/";>Wiki</a> +</li> +<li class="current"> +<a class="selected" href="index.html">ZooKeeper 3.4 Documentation</a> +</li> +</ul> +<!--+ + |end Tabs + +--> +</div> +</div> +<div id="main"> +<div id="publishedStrip"> +<!--+ + |start Subtabs + +--> +<div id="level2tabs"></div> +<!--+ + |end Endtabs + +--> +<script type="text/javascript"><!-- +document.write("Last Published: " + document.lastModified); +// --></script> +</div> +<!--+ + |breadtrail + +--> +<div class="breadtrail"> + + + </div> +<!--+ + |start Menu, mainarea + +--> +<!--+ + |start Menu + +--> +<div id="menu"> +<div onclick="SwitchMenu('menu_1.1', 'skin/')" id="menu_1.1Title" class="menutitle">Overview</div> +<div id="menu_1.1" class="menuitemgroup"> +<div class="menuitem"> +<a href="index.html">Welcome</a> +</div> +<div class="menuitem"> +<a href="zookeeperOver.html">Overview</a> +</div> +<div class="menuitem"> +<a href="zookeeperStarted.html">Getting Started</a> +</div> +<div class="menuitem"> +<a href="releasenotes.html">Release Notes</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.2', 'skin/')" id="menu_1.2Title" class="menutitle">Developer</div> +<div id="menu_1.2" class="menuitemgroup"> +<div class="menuitem"> +<a href="api/index.html">API Docs</a> +</div> +<div class="menuitem"> +<a href="zookeeperProgrammers.html">Programmer's Guide</a> +</div> +<div class="menuitem"> +<a href="javaExample.html">Java Example</a> +</div> +<div class="menuitem"> +<a href="zookeeperTutorial.html">Barrier and Queue Tutorial</a> +</div> +<div class="menuitem"> +<a href="recipes.html">Recipes</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.3', 'skin/')" id="menu_1.3Title" class="menutitle">BookKeeper</div> +<div id="menu_1.3" class="menuitemgroup"> +<div class="menuitem"> +<a href="bookkeeperStarted.html">Getting started</a> +</div> +<div class="menuitem"> +<a href="bookkeeperOverview.html">Overview</a> +</div> +<div class="menuitem"> +<a href="bookkeeperConfig.html">Setup guide</a> +</div> +<div class="menuitem"> +<a href="bookkeeperProgrammer.html">Programmer's guide</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.4', 'skin/')" id="menu_1.4Title" class="menutitle">Admin & Ops</div> +<div id="menu_1.4" class="menuitemgroup"> +<div class="menuitem"> +<a href="zookeeperAdmin.html">Administrator's Guide</a> +</div> +<div class="menuitem"> +<a href="zookeeperQuotas.html">Quota Guide</a> +</div> +<div class="menuitem"> +<a href="zookeeperJMX.html">JMX</a> +</div> +<div class="menuitem"> +<a href="zookeeperObservers.html">Observers Guide</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.5', 'skin/')" id="menu_1.5Title" class="menutitle">Contributor</div> +<div id="menu_1.5" class="menuitemgroup"> +<div class="menuitem"> +<a href="zookeeperInternals.html">ZooKeeper Internals</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.6', 'skin/')" id="menu_1.6Title" class="menutitle">Miscellaneous</div> +<div id="menu_1.6" class="menuitemgroup"> +<div class="menuitem"> +<a href="https://cwiki.apache.org/confluence/display/ZOOKEEPER";>Wiki</a> +</div> +<div class="menuitem"> +<a href="https://cwiki.apache.org/confluence/display/ZOOKEEPER/FAQ";>FAQ</a> +</div> +<div class="menuitem"> +<a href="http://zookeeper.apache.org/mailing_lists.html";>Mailing Lists</a> +</div> +</div> +<div id="credit"></div> +<div id="roundbottom"> +<img style="display: none" class="corner" height="15" width="15" alt="" src="skin/images/rc-b-l-15-1body-2menu-3menu.png"></div> +<!--+ + |alternative credits + +--> +<div id="credit2"></div> +</div> +<!--+ + |end Menu + +--> +<!--+ + |start content + +--> +<div id="content"> +<div title="Portable Document Format" class="pdflink"> +<a class="dida" href="bookkeeperStream.pdf"><img alt="PDF -icon" src="skin/images/pdfdoc.gif" class="skin"><br> + PDF</a> +</div> +<h1>Streaming with BookKeeper</h1> +<div id="front-matter"> +<div id="minitoc-area"> +<ul class="minitoc"> +<li> +<a href="#bk_StreamSummary">Summary</a> +</li> +<li> +<a href="#bk_LedgerOutputStream">Writing a stream of bytes</a> +</li> +<li> +<a href="#bk_LedgerInputStream">Reading a stream of bytes</a> +</li> +</ul> +</div> +</div> + + + + +<a name="bk_StreamSummary"></a> +<h2 class="h3">Summary</h2> +<div class="section"> +<p> + When using the BookKeeper API, an application has to split the data to write into entries, each + entry being a byte array. This is natural for many applications. For example, when using BookKeeper + for write-ahead logging, an application typically wants to write the modifications corresponding + to a command or a transaction. Some other applications, however, might not have a natural boundary + for entries, and may prefer to write and read streams of bytes. This is exactly the purpose of the + stream API we have implemented on top of BookKeeper. + </p> +<p> + The stream API is implemented in the package <span class="codefrag computeroutput">Streaming</span>, and it contains two main classes: <span class="codefrag computeroutput">LedgerOutputStream</span> and + <span class="codefrag computeroutput">LedgerInputStream</span>. The class names are indicative of what they do. + </p> +</div> + + +<a name="bk_LedgerOutputStream"></a> +<h2 class="h3">Writing a stream of bytes</h2> +<div class="section"> +<p> + Class <span class="codefrag computeroutput">LedgerOutputStream</span> implements two constructors and five public methods: + </p> +<p> + +<span class="codefrag computeroutput"> + public LedgerOutputStream(LedgerHandle lh) + </span> + +</p> +<p> + where: + </p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">lh</span> is a ledger handle for a previously created and open ledger. + </p> + +</li> + +</ul> +<p> + +<span class="codefrag computeroutput"> + public LedgerOutputStream(LedgerHandle lh, int size) + </span> + +</p> +<p> + where: + </p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">lh</span> is a ledger handle for a previously created and open ledger. + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">size</span> is the size of the byte buffer to store written bytes before flushing. + </p> + +</li> + +</ul> +<p> + +<strong>Closing a stream.</strong> This call closes the stream by flushing the write buffer. + </p> +<p> + +<span class="codefrag computeroutput"> + public void close() + </span> + +</p> +<p> + which has no parameters. + </p> +<p> + +<strong>Flushing a stream.</strong> This call essentially flushes the write buffer. + </p> +<p> + +<span class="codefrag computeroutput"> + public synchronized void flush() + </span> + +</p> +<p> + which has no parameters. + </p> +<p> + +<strong>Writing bytes.</strong> There are three calls for writing bytes to a stream. + </p> +<p> + +<span class="codefrag computeroutput"> + public synchronized void write(byte[] b) + </span> + +</p> +<p> + where: + </p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">b</span> is an array of bytes to write. + </p> + +</li> + +</ul> +<p> + +<span class="codefrag computeroutput"> + public synchronized void write(byte[] b, int off, int len) + </span> + +</p> +<p> + where: + </p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">b</span> is an array of bytes to write. + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">off</span> is a buffer offset. + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">len</span> is the length to write. + </p> + +</li> + +</ul> +<p> + +<span class="codefrag computeroutput"> + public synchronized void write(int b) + </span> + +</p> +<p> + where: + </p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">b</span> contains a byte to write. The method writes the least significant byte of the integer four bytes. + </p> + +</li> + +</ul> +</div> + + +<a name="bk_LedgerInputStream"></a> +<h2 class="h3">Reading a stream of bytes</h2> +<div class="section"> +<p> + Class <span class="codefrag computeroutput">LedgerOutputStream</span> implements two constructors and four public methods: + </p> +<p> + +<span class="codefrag computeroutput"> + public LedgerInputStream(LedgerHandle lh) + throws BKException, InterruptedException + </span> + +</p> +<p> + where: + </p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">lh</span> is a ledger handle for a previously created and open ledger. + </p> + +</li> + +</ul> +<p> + +<span class="codefrag computeroutput"> + public LedgerInputStream(LedgerHandle lh, int size) + throws BKException, InterruptedException + </span> + +</p> +<p> + where: + </p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">lh</span> is a ledger handle for a previously created and open ledger. + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">size</span> is the size of the byte buffer to store bytes that the application + will eventually read. + </p> + +</li> + +</ul> +<p> + +<strong>Closing.</strong> There is one call to close an input stream, but the call + is currently empty and the application is responsible for closing the ledger handle. + </p> +<p> + +<span class="codefrag computeroutput"> + public void close() + </span> + +</p> +<p> + which has no parameters. + </p> +<p> + +<strong>Reading.</strong> There are three calls to read from the stream. + </p> +<p> + +<span class="codefrag computeroutput"> + public synchronized int read() + throws IOException + </span> + +</p> +<p> + which has no parameters. + </p> +<p> + +<span class="codefrag computeroutput"> + public synchronized int read(byte[] b) + throws IOException + </span> + +</p> +<p> + where: + </p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">b</span> is a byte array to write to. + </p> + +</li> + +</ul> +<p> + +<span class="codefrag computeroutput"> + public synchronized int read(byte[] b, int off, int len) + throws IOException + </span> + +</p> +<p> + where: + </p> +<ul> + +<li> + +<p> + +<span class="codefrag computeroutput">b</span> is a byte array to write to. + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">off</span> is an offset for byte array <span class="codefrag computeroutput">b</span>. + </p> + +</li> + + +<li> + +<p> + +<span class="codefrag computeroutput">len</span> is the length in bytes to write to <span class="codefrag computeroutput">b</span>. + </p> + +</li> + +</ul> +</div> + +<p align="right"> +<font size="-2"></font> +</p> +</div> +<!--+ + |end content + +--> +<div class="clearboth"> </div> +</div> +<div id="footer"> +<!--+ + |start bottomstrip + +--> +<div class="lastmodified"> +<script type="text/javascript"><!-- +document.write("Last Published: " + document.lastModified); +// --></script> +</div> +<div class="copyright"> + Copyright © + 2008 <a href="http://www.apache.org/licenses/";>The Apache Software Foundation.</a> +</div> +<!--+ + |end bottomstrip + +--> +</div> +</body> +</html> http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/bookkeeperStream.pdf ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/bookkeeperStream.pdf b/content/doc/r3.5.4-beta/bookkeeperStream.pdf new file mode 100644 index 0000000..87aad97 Binary files /dev/null and b/content/doc/r3.5.4-beta/bookkeeperStream.pdf differ http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/broken-links.xml ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/broken-links.xml b/content/doc/r3.5.4-beta/broken-links.xml new file mode 100644 index 0000000..f95aa9b --- /dev/null +++ b/content/doc/r3.5.4-beta/broken-links.xml @@ -0,0 +1,2 @@ +<broken-links> +</broken-links> http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/images/2pc.jpg ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/images/2pc.jpg b/content/doc/r3.5.4-beta/images/2pc.jpg new file mode 100644 index 0000000..fe4488f Binary files /dev/null and b/content/doc/r3.5.4-beta/images/2pc.jpg differ http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/images/bk-overview.jpg ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/images/bk-overview.jpg b/content/doc/r3.5.4-beta/images/bk-overview.jpg new file mode 100644 index 0000000..6e12fb4 Binary files /dev/null and b/content/doc/r3.5.4-beta/images/bk-overview.jpg differ http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/images/built-with-forrest-button.png ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/images/built-with-forrest-button.png b/content/doc/r3.5.4-beta/images/built-with-forrest-button.png new file mode 100644 index 0000000..4a787ab Binary files /dev/null and b/content/doc/r3.5.4-beta/images/built-with-forrest-button.png differ http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/images/favicon.ico ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/images/favicon.ico b/content/doc/r3.5.4-beta/images/favicon.ico new file mode 100644 index 0000000..161bcf7 Binary files /dev/null and b/content/doc/r3.5.4-beta/images/favicon.ico differ http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/images/hadoop-logo.jpg ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/images/hadoop-logo.jpg b/content/doc/r3.5.4-beta/images/hadoop-logo.jpg new file mode 100644 index 0000000..809525d Binary files /dev/null and b/content/doc/r3.5.4-beta/images/hadoop-logo.jpg differ http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/images/instruction_arrow.png ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/images/instruction_arrow.png b/content/doc/r3.5.4-beta/images/instruction_arrow.png new file mode 100644 index 0000000..0fbc724 Binary files /dev/null and b/content/doc/r3.5.4-beta/images/instruction_arrow.png differ http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/images/state_dia.jpg ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/images/state_dia.jpg b/content/doc/r3.5.4-beta/images/state_dia.jpg new file mode 100644 index 0000000..b6f4a8b Binary files /dev/null and b/content/doc/r3.5.4-beta/images/state_dia.jpg differ http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/images/zkcomponents.jpg ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/images/zkcomponents.jpg b/content/doc/r3.5.4-beta/images/zkcomponents.jpg new file mode 100644 index 0000000..7690578 Binary files /dev/null and b/content/doc/r3.5.4-beta/images/zkcomponents.jpg differ http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/images/zknamespace.jpg ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/images/zknamespace.jpg b/content/doc/r3.5.4-beta/images/zknamespace.jpg new file mode 100644 index 0000000..05534bc Binary files /dev/null and b/content/doc/r3.5.4-beta/images/zknamespace.jpg differ http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/images/zkperfRW-3.2.jpg ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/images/zkperfRW-3.2.jpg b/content/doc/r3.5.4-beta/images/zkperfRW-3.2.jpg new file mode 100644 index 0000000..594b50b Binary files /dev/null and b/content/doc/r3.5.4-beta/images/zkperfRW-3.2.jpg differ http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/images/zkperfRW.jpg ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/images/zkperfRW.jpg b/content/doc/r3.5.4-beta/images/zkperfRW.jpg new file mode 100644 index 0000000..ad3019f Binary files /dev/null and b/content/doc/r3.5.4-beta/images/zkperfRW.jpg differ http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/images/zkperfreliability.jpg ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/images/zkperfreliability.jpg b/content/doc/r3.5.4-beta/images/zkperfreliability.jpg new file mode 100644 index 0000000..232bba8 Binary files /dev/null and b/content/doc/r3.5.4-beta/images/zkperfreliability.jpg differ http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/images/zkservice.jpg ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/images/zkservice.jpg b/content/doc/r3.5.4-beta/images/zkservice.jpg new file mode 100644 index 0000000..1ec9154 Binary files /dev/null and b/content/doc/r3.5.4-beta/images/zkservice.jpg differ http://git-wip-us.apache.org/repos/asf/zookeeper/blob/ec4ec140/content/doc/r3.5.4-beta/images/zookeeper_small.gif ---------------------------------------------------------------------- diff --git a/content/doc/r3.5.4-beta/images/zookeeper_small.gif b/content/doc/r3.5.4-beta/images/zookeeper_small.gif new file mode 100644 index 0000000..4e8014f Binary files /dev/null and b/content/doc/r3.5.4-beta/images/zookeeper_small.gif differ
