Abstract

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.

Getting Started: Setting up BookKeeper to write logs.

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 BookKeeper Programmer's Guide.

Pre-requisites

See System Requirements the Admin guide.

Download

BookKeeper trunk can be downloaded from subversion. See "Version Control:http://zookeeper.apache.org/bookkeeper/svn.html.

LocalBookKeeper

BookKeeper provides a utility program to start a standalone ZooKeeper ensemble and a number of bookies on a local machine. As this all runs on a local machine, throughput will be very low. It should only be used for testing.

To start a local bookkeeper ensemble with 5 bookies:

bookkeeper-server/bin/bookkeeper localbookie 5

Setting up bookies

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.

For each bookie, we need to execute a command like the following:

bookkeeper-server/bin/bookkeeper bookie

This command will use the default directories for storing ledgers and the write ahead log, and will look for a zookeeper server on localhost:2181. See the Admin Guide for more details.

To see the default values of these configuration variables, run:

bookkeeper-server/bin/bookkeeper help

Setting up ZooKeeper

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:

1. /ledgers
2. /ledgers/available

We provide a way of bootstrapping it automatically. See the Admin Guide for a description of how to bootstrap automatically, and in particular the shell metaformat command.

Example

In the following excerpt of code, we:

1. Open a bookkeeper client;
2. Create a ledger;
3. Write to the ledger;
4. Close the ledger;
5. Open the same ledger for reading;
6. Read from the ledger;
7. Close the ledger again;
8. Close the bookkeeper client.

BookKeeper bkc = new BookKeeper("localhost:2181");
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();
bkc.close();