In release 4.5.0, Apache BookKeeper introduces a few advanced API for advanced usage. This sections covers these advanced APIs.

Before learn the advanced API, please read Ledger API first.


LedgerHandleAdv is an advanced extension of LedgerHandle. It allows user passing in an entryId when adding an entry.

Creating advanced ledgers

Here’s an exmaple:

byte[] passwd = "some-passwd".getBytes();
LedgerHandleAdv handle = bkClient.createLedgerAdv(
    3, 3, 2, // replica settings

You can also create advanced ledgers asynchronously.

class LedgerCreationCallback implements AsyncCallback.CreateCallback {
    public void createComplete(int returnCode, LedgerHandle handle, Object ctx) {
        System.out.println("Ledger successfully created");
        3, // ensemble size
        3, // write quorum size
        2, // ack quorum size
        new LedgerCreationCallback(),
        "some context"

Besides the APIs above, BookKeeper allows users providing ledger-id when creating advanced ledgers.

long ledgerId = ...; // the ledger id is generated externally.

byte[] passwd = "some-passwd".getBytes();
LedgerHandleAdv handle = bkClient.createLedgerAdv(
    ledgerId, // ledger id generated externally
    3, 3, 2, // replica settings

Please note, it is users’ responsibility to provide a unique ledger id when using the API above. If a ledger already exists when users try to create an advanced ledger with same ledger id, a LedgerExistsException is thrown by the bookkeeper client.

Add Entries

The normal add entries api in advanced ledgers are disabled. Instead, when users want to add entries to advanced ledgers, an entry id is required to pass in along with the entry data when adding an entry.

long entryId = ...; // entry id generated externally

ledger.addEntry(entryId, "Some entry data".getBytes());

A few notes when using this API:

  • The entry id has to be non-negative.
  • Clients are okay to add entries out of order.
  • However, the entries are only acknowledged in a monotonic order starting from 0.

Read Entries

The read entries api in advanced ledgers remain same as normal ledgers.

An entry is a sequence of bytes (plus some metadata) written to a BookKeeper ledger. Entries are also known as records.

A ledger is a sequence of entries written to BookKeeper. Entries are written sequentially to ledgers and at most once, giving ledgers append-only semantics.

A bookie is an individual BookKeeper storage server.

Bookies store the content of ledgers and act as a distributed ensemble.

A subsystem that runs in the background on bookies to ensure that ledgers are fully replicated even if one bookie from the ensemble is down.

Striping is the process of distributing BookKeeper ledgers to sub-groups of bookies rather than to all bookies in a BookKeeper ensemble.

Striping is essential to ensuring fast performance.

A journal file stores BookKeeper transaction logs.

When a reader forces a ledger to close, preventing any further entries from being written to the ledger.

A record is a sequence of bytes (plus some metadata) written to a BookKeeper ledger. Records are also known as entries.