bookkeeper-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [bookkeeper] branch branch-4.5 updated: ISSUE #366: [DOCUMENTATION] LedgerHandleAdv
Date Mon, 07 Aug 2017 18:36:01 GMT
This is an automated email from the ASF dual-hosted git repository.

sijie pushed a commit to branch branch-4.5
in repository

The following commit(s) were added to refs/heads/branch-4.5 by this push:
     new 747d3c0  ISSUE #366: [DOCUMENTATION] LedgerHandleAdv
747d3c0 is described below

commit 747d3c09a67caf5de92d93443b01d115aaf75258
Author: Sijie Guo <>
AuthorDate: Mon Aug 7 11:32:22 2017 -0700

    ISSUE #366: [DOCUMENTATION] LedgerHandleAdv
    Descriptions of the changes in this PR:
    - add documentation about LedgerHandleAdv
    - update overview
    Author: Sijie Guo <>
    Reviewers: Jia Zhai <None>, Matteo Merli <>
    This closes #401 from sijie/issue_366, closes #366
 site/_data/sidebar.yaml                |  2 +
 site/docs/latest/api/ | 82 ++++++++++++++++++++++++++++++++++
 site/docs/latest/api/       | 11 +++--
 3 files changed, 91 insertions(+), 4 deletions(-)

diff --git a/site/_data/sidebar.yaml b/site/_data/sidebar.yaml
index ec7bf17..0138070 100644
--- a/site/_data/sidebar.yaml
+++ b/site/_data/sidebar.yaml
@@ -39,6 +39,8 @@ groups:
     endpoint: overview
   - name: Ledger API
     endpoint: ledger-api
+  - name: Advanced Ledger API
+    endpoint: ledger-adv-api
   - name: DistributedLog
     endpoint: distributedlog-api
 - name: Development
diff --git a/site/docs/latest/api/ b/site/docs/latest/api/
new file mode 100644
index 0000000..f46950d
--- /dev/null
+++ b/site/docs/latest/api/
@@ -0,0 +1,82 @@
+title: The Advanced Ledger API
+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](../ledger-api) first.
+## LedgerHandleAdv
+[`LedgerHandleAdv`](../javadoc/org/apache/bookkeeper/client/LedgerHandleAdv) is an advanced
extension of [`LedgerHandle`](../javadoc/org/apache/bookkeeper/client/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
+    DigestType.CRC32,
+    passwd);
+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
+        BookKeeper.DigestType.CRC32,
+        password,
+        new LedgerCreationCallback(),
+        "some context"
+Besides the APIs above, BookKeeper allows users providing `ledger-id` when creating advanced
+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
+    DigestType.CRC32,
+    passwd);
+> 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
+> a [LedgerExistsException](../javadoc/org/apache/bookkeeper/client/BKException.BKLedgerExistException.html)
is thrown by the bookkeeper client.
+### Add Entries
+The normal [add entries api](ledger-api/#adding-entries-to-ledgers) 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](../ledger-api/#reading-entries-from-ledgers).
diff --git a/site/docs/latest/api/ b/site/docs/latest/api/
index 2940750..3eb6492 100644
--- a/site/docs/latest/api/
+++ b/site/docs/latest/api/
@@ -1,14 +1,17 @@
-title: The ledger API vs. the DistributedLog API
+title: BookKeeper API
-BookKeeper offers two APIs that applications can use to interact with it:
+BookKeeper offers a few APIs that applications can use to interact with it:
 * The [ledger API](../ledger-api) is a lower-level API that enables you to interact with
{% pop ledgers %} directly
+* The [Ledger Advanced API)(../ledger-adv-api) is an advanced extension to [Ledger API](../ledger-api)
to provide more flexibilities to applications.
 * The [DistributedLog API](../distributedlog-api) is a higher-level API that provides convenient
 ## Trade-offs
-The advantage of the ledger API is that it provides direct access to ledgers and thus enables
you to use BookKeeper however you'd like. The disadvantage is that it requires you to manage
things like leader election on your own.
+The `Ledger API` provides direct access to ledgers and thus enables you to use BookKeeper
however you'd like.
-The advantage of the DistributedLog API is that it's easier to use, with semantics resembling
a simple key/value store from the standpoint of applications. The disadvantage is that 
\ No newline at end of file
+However, in most of use cases, if you want a `log stream`-like abstraction, it requires you
to manage things like tracking list of ledgers,
+managing rolling ledgers and data retention on your own. In such cases, you are recommended
to use [DistributedLog API](../distributedlog-api),
+with semantics resembling continous log streams from the standpoint of applications.

To stop receiving notification emails like this one, please contact
['"" <>'].

View raw message