[bookkeeper] branch master updated: ISSUE #366: [DOCUMENTATION] LedgerHandleAdv

[si...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

sijie pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/bookkeeper.git


The following commit(s) were added to refs/heads/master by this push:
     new 188d7e5  ISSUE #366: [DOCUMENTATION] LedgerHandleAdv
188d7e5 is described below

commit 188d7e5fb8d8beb137f13a49b7df8a9cd861cefc
Author: Sijie Guo <si...@apache.org>
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 <si...@apache.org>
    
    Reviewers: Jia Zhai <None>, Matteo Merli <mm...@apache.org>
    
    This closes #401 from sijie/issue_366, closes #366
---
 site/_data/sidebar.yaml                |  2 +
 site/docs/latest/api/ledger-adv-api.md | 82 ++++++++++++++++++++++++++++++++++
 site/docs/latest/api/overview.md       | 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/ledger-adv-api.md b/site/docs/latest/api/ledger-adv-api.md
new file mode 100644
index 0000000..f46950d
--- /dev/null
+++ b/site/docs/latest/api/ledger-adv-api.md
@@ -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:
+
+```java
+byte[] passwd = "some-passwd".getBytes();
+LedgerHandleAdv handle = bkClient.createLedgerAdv(
+    3, 3, 2, // replica settings
+    DigestType.CRC32,
+    passwd);
+```
+
+You can also create advanced ledgers asynchronously.
+
+```java
+class LedgerCreationCallback implements AsyncCallback.CreateCallback {
+    public void createComplete(int returnCode, LedgerHandle handle, Object ctx) {
+        System.out.println("Ledger successfully created");
+    }
+}
+client.asyncCreateLedgerAdv(
+        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 ledgers.
+
+```java
+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 id,
+> 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.
+
+```java
+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/overview.md b/site/docs/latest/api/overview.md
index 2940750..3eb6492 100644
--- a/site/docs/latest/api/overview.md
+++ b/site/docs/latest/api/overview.md
@@ -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 abstractions.
 
 ## 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
['"commits@bookkeeper.apache.org" <co...@bookkeeper.apache.org>'].