BookKeeper (bookkeeper 4.4.0-SNAPSHOT API)

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.Builder

static class BookKeeper.DigestType
There are 2 digest types that can be used for verification.

Nested Classes
Modifier and Type	Class and Description
`static class`	`BookKeeper.Builder`
`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`	`asyncIsClosed(long lId, AsyncCallback.IsClosedCallback cb, Object ctx)` Check asynchronously whether the ledger with identifier lId has been closed.
`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.
`static BookKeeper.Builder`	`forConfig(ClientConfiguration conf)`
`protected ClientConfiguration`	`getConf()`
`boolean`	`isClosed(long lId)` Check whether the ledger with identifier lId has been closed.
`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
  - forConfig
```
public static BookKeeper.Builder forConfig(ClientConfiguration conf)
```
  - 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
  - asyncIsClosed
```
public void asyncIsClosed(long lId,
                 AsyncCallback.IsClosedCallback cb,
                 Object ctx)
```
    Check asynchronously whether the ledger with identifier lId has been closed.
    
    Parameters:
    lId - ledger identifier
    cb - callback method
  - isClosed
```
public boolean isClosed(long lId)
                 throws BKException,
                        InterruptedException
```
    Check whether the ledger with identifier lId has been closed.
    
    Parameters:
    lId -
    
    Returns:
    boolean true if ledger has been closed
    
    Throws:
    
    BKException
    
    InterruptedException
  - close
```
public void close()
           throws InterruptedException,
                  BKException
```
    Shuts down client.
    
    Throws:
    
    InterruptedException
    
    BKException

Class BookKeeper

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

BookKeeper

BookKeeper

BookKeeper

BookKeeper

Method Detail

forConfig

getConf

asyncCreateLedger

asyncCreateLedger

createLedger

createLedger

createLedger

asyncOpenLedger

asyncOpenLedgerNoRecovery

openLedger

openLedgerNoRecovery

asyncDeleteLedger

deleteLedger

asyncIsClosed

isClosed

close