org.apache.bookkeeper.client

Class BookKeeper

java.lang.Object

org.apache.bookkeeper.client.BookKeeper

public class BookKeeper
extends Object

BookKeeper client. We assume there is one single writer to a ledger at any time. There are four possible operations: start a new ledger, write to a ledger, read from a ledger and delete a ledger. The exceptions resulting from synchronous calls and error code resulting from asynchronous calls can be found in the class BKException.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	BookKeeper.DigestType There are 2 digest types that can be used for verification.

Constructor Summary

Constructors

Constructor and Description
BookKeeper(ClientConfiguration conf) Create a bookkeeper client using a configuration object.
BookKeeper(ClientConfiguration conf, org.apache.zookeeper.ZooKeeper zk) Create a bookkeeper client but use the passed in zookeeper client instead of instantiating one.
BookKeeper(ClientConfiguration conf, org.apache.zookeeper.ZooKeeper zk, org.jboss.netty.channel.socket.ClientSocketChannelFactory channelFactory) Create a bookkeeper client but use the passed in zookeeper client and client socket channel factory instead of instantiating those.
BookKeeper(String servers) Create a bookkeeper client.

Method Summary

Methods

Modifier and Type	Method and Description
void	asyncCreateLedger(int ensSize, int writeQuorumSize, BookKeeper.DigestType digestType, byte[] passwd, AsyncCallback.CreateCallback cb, Object ctx) Creates a new ledger asynchronously.
void	asyncCreateLedger(int ensSize, int writeQuorumSize, int ackQuorumSize, BookKeeper.DigestType digestType, byte[] passwd, AsyncCallback.CreateCallback cb, Object ctx) Creates a new ledger asynchronously.
void	asyncDeleteLedger(long lId, AsyncCallback.DeleteCallback cb, Object ctx) Deletes a ledger asynchronously.
void	asyncOpenLedger(long lId, BookKeeper.DigestType digestType, byte[] passwd, AsyncCallback.OpenCallback cb, Object ctx) Open existing ledger asynchronously for reading.
void	asyncOpenLedgerNoRecovery(long lId, BookKeeper.DigestType digestType, byte[] passwd, AsyncCallback.OpenCallback cb, Object ctx) Open existing ledger asynchronously for reading, but it does not try to recover the ledger if it is not yet closed.
void	close() Shuts down client.
LedgerHandle	createLedger(BookKeeper.DigestType digestType, byte[] passwd) Creates a new ledger.
LedgerHandle	createLedger(int ensSize, int qSize, BookKeeper.DigestType digestType, byte[] passwd) Synchronous call to create ledger.
LedgerHandle	createLedger(int ensSize, int writeQuorumSize, int ackQuorumSize, BookKeeper.DigestType digestType, byte[] passwd) Synchronous call to create ledger.
void	deleteLedger(long lId) Synchronous call to delete a ledger.
protected ClientConfiguration	getConf()
LedgerHandle	openLedger(long lId, BookKeeper.DigestType digestType, byte[] passwd) Synchronous open ledger call
LedgerHandle	openLedgerNoRecovery(long lId, BookKeeper.DigestType digestType, byte[] passwd) Synchronous, unsafe open ledger call

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BookKeeper

public BookKeeper(String servers)
           throws IOException,
                  InterruptedException,
                  org.apache.zookeeper.KeeperException

Create a bookkeeper client. A zookeeper client and a client socket factory will be instantiated as part of this constructor.

Parameters:

servers - A list of one of more servers on which zookeeper is running. The client assumes that the running bookies have been registered with zookeeper under the path BookieWatcher.bookieRegistrationPath

Throws:

IOException

InterruptedException

org.apache.zookeeper.KeeperException

BookKeeper

public BookKeeper(ClientConfiguration conf)
           throws IOException,
                  InterruptedException,
                  org.apache.zookeeper.KeeperException

Create a bookkeeper client using a configuration object. A zookeeper client and a client socket factory will be instantiated as part of this constructor.

Parameters:

conf - Client Configuration object

Throws:

IOException

InterruptedException

org.apache.zookeeper.KeeperException

BookKeeper

public BookKeeper(ClientConfiguration conf,
          org.apache.zookeeper.ZooKeeper zk)
           throws IOException,
                  InterruptedException,
                  org.apache.zookeeper.KeeperException

Create a bookkeeper client but use the passed in zookeeper client instead of instantiating one.

Parameters:

conf - Client Configuration object ClientConfiguration

zk - Zookeeper client instance connected to the zookeeper with which the bookies have registered

Throws:

IOException

InterruptedException

org.apache.zookeeper.KeeperException

BookKeeper

public BookKeeper(ClientConfiguration conf,
          org.apache.zookeeper.ZooKeeper zk,
          org.jboss.netty.channel.socket.ClientSocketChannelFactory channelFactory)
           throws IOException,
                  InterruptedException,
                  org.apache.zookeeper.KeeperException

Create a bookkeeper client but use the passed in zookeeper client and client socket channel factory instead of instantiating those.

Parameters:

conf - Client Configuration Object ClientConfiguration

zk - Zookeeper client instance connected to the zookeeper with which the bookies have registered. The ZooKeeper client must be connected before it is passed to BookKeeper. Otherwise a KeeperException is thrown.

channelFactory - A factory that will be used to create connections to the bookies

Throws:

IOException

InterruptedException

org.apache.zookeeper.KeeperException - if the passed zk handle is not connected

Method Detail

getConf

protected ClientConfiguration getConf()

asyncCreateLedger

public void asyncCreateLedger(int ensSize,
                     int writeQuorumSize,
                     BookKeeper.DigestType digestType,
                     byte[] passwd,
                     AsyncCallback.CreateCallback cb,
                     Object ctx)

Creates a new ledger asynchronously. To create a ledger, we need to specify the ensemble size, the quorum size, the digest type, a password, a callback implementation, and an optional control object. The ensemble size is how many bookies the entries should be striped among and the quorum size is the degree of replication of each entry. The digest type is either a MAC or a CRC. Note that the CRC option is not able to protect a client against a bookie that replaces an entry. The password is used not only to authenticate access to a ledger, but also to verify entries in ledgers.

Parameters:

ensSize - number of bookies over which to stripe entries

writeQuorumSize - number of bookies each entry will be written to. each of these bookies must acknowledge the entry before the call is completed.

digestType - digest type, either MAC or CRC32

passwd - password

cb - createCallback implementation

ctx - optional control object

asyncCreateLedger

public void asyncCreateLedger(int ensSize,
                     int writeQuorumSize,
                     int ackQuorumSize,
                     BookKeeper.DigestType digestType,
                     byte[] passwd,
                     AsyncCallback.CreateCallback cb,
                     Object ctx)

Creates a new ledger asynchronously. Ledgers created with this call have a separate write quorum and ack quorum size. The write quorum must be larger than the ack quorum. Separating the write and the ack quorum allows the BookKeeper client to continue writing when a bookie has failed but the failure has not yet been detected. Detecting a bookie has failed can take a number of seconds, as configured by the read timeout ClientConfiguration.getReadTimeout(). Once the bookie failure is detected, that bookie will be removed from the ensemble. The other parameters match those of asyncCreateLedger(int, int, DigestType, byte[], AsyncCallback.CreateCallback, Object)

Parameters:

ensSize - number of bookies over which to stripe entries

writeQuorumSize - number of bookies each entry will be written to

ackQuorumSize - number of bookies which must acknowledge an entry before the call is completed

digestType - digest type, either MAC or CRC32

passwd - password

cb - createCallback implementation

ctx - optional control object

createLedger

public LedgerHandle createLedger(BookKeeper.DigestType digestType,
                        byte[] passwd)
                          throws BKException,
                                 InterruptedException

Creates a new ledger. Default of 3 servers, and quorum of 2 servers.

Parameters:

digestType - digest type, either MAC or CRC32

passwd - password

Returns:

a handle to the newly created ledger

Throws:

InterruptedException

BKException

createLedger

public LedgerHandle createLedger(int ensSize,
                        int qSize,
                        BookKeeper.DigestType digestType,
                        byte[] passwd)
                          throws InterruptedException,
                                 BKException

Synchronous call to create ledger. Parameters match those of asyncCreateLedger(int, int, DigestType, byte[], AsyncCallback.CreateCallback, Object)

Parameters:

ensSize -

qSize -

digestType -

passwd -

Returns:

a handle to the newly created ledger

Throws:

InterruptedException

BKException

createLedger

public LedgerHandle createLedger(int ensSize,
                        int writeQuorumSize,
                        int ackQuorumSize,
                        BookKeeper.DigestType digestType,
                        byte[] passwd)
                          throws InterruptedException,
                                 BKException

Synchronous call to create ledger. Parameters match those of asyncCreateLedger(int, int, int, DigestType, byte[], AsyncCallback.CreateCallback, Object)

Parameters:

ensSize -

writeQuorumSize -

ackQuorumSize -

digestType -

passwd -

Returns:

a handle to the newly created ledger

Throws:

InterruptedException

BKException

asyncOpenLedger

public void asyncOpenLedger(long lId,
                   BookKeeper.DigestType digestType,
                   byte[] passwd,
                   AsyncCallback.OpenCallback cb,
                   Object ctx)

Open existing ledger asynchronously for reading. Opening a ledger with this method invokes fencing and recovery on the ledger if the ledger has not been closed. Fencing will block all other clients from writing to the ledger. Recovery will make sure that the ledger is closed before reading from it. Recovery also makes sure that any entries which reached one bookie, but not a quorum, will be replicated to a quorum of bookies. This occurs in cases were the writer of a ledger crashes after sending a write request to one bookie but before being able to send it to the rest of the bookies in the quorum. If the ledger is already closed, neither fencing nor recovery will be applied.

Parameters:

lId - ledger identifier

digestType - digest type, either MAC or CRC32

passwd - password

ctx - optional control object

See Also:

LedgerHandle.asyncClose(org.apache.bookkeeper.client.AsyncCallback.CloseCallback, java.lang.Object)

asyncOpenLedgerNoRecovery

public void asyncOpenLedgerNoRecovery(long lId,
                             BookKeeper.DigestType digestType,
                             byte[] passwd,
                             AsyncCallback.OpenCallback cb,
                             Object ctx)

Open existing ledger asynchronously for reading, but it does not try to recover the ledger if it is not yet closed. The application needs to use it carefully, since the writer might have crashed and ledger will remain unsealed forever if there is no external mechanism to detect the failure of the writer and the ledger is not open in a safe manner, invoking the recovery procedure. Opening a ledger without recovery does not fence the ledger. As such, other clients can continue to write to the ledger. This method returns a read only ledger handle. It will not be possible to add entries to the ledger. Any attempt to add entries will throw an exception. Reads from the returned ledger will only be able to read entries up until the lastConfirmedEntry at the point in time at which the ledger was opened.

Parameters:

lId - ledger identifier

digestType - digest type, either MAC or CRC32

passwd - password

ctx - optional control object

openLedger

public LedgerHandle openLedger(long lId,
                      BookKeeper.DigestType digestType,
                      byte[] passwd)
                        throws BKException,
                               InterruptedException

Synchronous open ledger call

Parameters:

lId - ledger identifier

digestType - digest type, either MAC or CRC32

passwd - password

Returns:

a handle to the open ledger

Throws:

InterruptedException

BKException

See Also:

asyncOpenLedger(long, org.apache.bookkeeper.client.BookKeeper.DigestType, byte[], org.apache.bookkeeper.client.AsyncCallback.OpenCallback, java.lang.Object)

openLedgerNoRecovery

public LedgerHandle openLedgerNoRecovery(long lId,
                                BookKeeper.DigestType digestType,
                                byte[] passwd)
                                  throws BKException,
                                         InterruptedException

Synchronous, unsafe open ledger call

Parameters:

lId - ledger identifier

digestType - digest type, either MAC or CRC32

passwd - password

Returns:

a handle to the open ledger

Throws:

InterruptedException

BKException

See Also:

asyncOpenLedgerNoRecovery(long, org.apache.bookkeeper.client.BookKeeper.DigestType, byte[], org.apache.bookkeeper.client.AsyncCallback.OpenCallback, java.lang.Object)

asyncDeleteLedger

public void asyncDeleteLedger(long lId,
                     AsyncCallback.DeleteCallback cb,
                     Object ctx)

Deletes a ledger asynchronously.

Parameters:

lId - ledger Id

cb - deleteCallback implementation

ctx - optional control object

deleteLedger

public void deleteLedger(long lId)
                  throws InterruptedException,
                         BKException

Synchronous call to delete a ledger. Parameters match those of asyncDeleteLedger(long, AsyncCallback.DeleteCallback, Object)

Parameters:

lId - ledgerId

Throws:

InterruptedException

BKException.BKNoSuchLedgerExistsException - if the ledger doesn't exist

BKException

close

public void close()
           throws InterruptedException,
                  BKException

Shuts down client.

Throws:

InterruptedException

BKException