[bookkeeper] branch master updated: BP-42: new api list ledgers

[eo...@apache.org]

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

eolivelli 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 41412bc  BP-42: new api list ledgers
41412bc is described below

commit 41412bc647f94d6e13d8dde6daa3081c010d0806
Author: Nicolò Boschi <bo...@gmail.com>
AuthorDate: Fri Oct 9 17:37:44 2020 +0200

    BP-42: new api list ledgers
    
    Descriptions of the changes in this PR:
    
    
    
    ### Motivation
    
    
    The new Client API (org.apache.bookkeeper.client.api.BookKeeper) aims to replace obsolete BookKeeper API but some features are not implemented yet, like the functionalities provided by BookKeeperAdmin.
    For example, it does not expose a method to list available ledgers, comparable to BookKeeperAdmin#listLedgers().
    low.
    
    ### Changes
    
    - Ledgers listing
    - Simpler access to LedgerMetadata
    - Ledger id inside LedgerMetadata
    
    Master Issue: #2422
    
    
    
    Reviewers: Enrico Olivelli <eo...@gmail.com>, Sijie Guo <si...@apache.org>
    
    This closes #2423 from nicoloboschi/bp42-new-api-list-ledgers
---
 site/bps/BP-42-new-api-list-ledgers.md | 94 ++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)

diff --git a/site/bps/BP-42-new-api-list-ledgers.md b/site/bps/BP-42-new-api-list-ledgers.md
new file mode 100644
index 0000000..2262ae2
--- /dev/null
+++ b/site/bps/BP-42-new-api-list-ledgers.md
@@ -0,0 +1,94 @@
+---
+title: "BP-42: New Client API - list ledgers"
+issue: https://github.com/apache/bookkeeper/issues/2422
+state: "Under Discussion"
+release: "N/A"
+---
+
+### Motivation
+
+The new Client API (`org.apache.bookkeeper.client.api.BookKeeper`) aims to replace obsolete BookKeeper API but some features are not implemented yet, like the functionalities provided by `BookKeeperAdmin`. 
+For example, it does not expose a method to list available ledgers, comparable to `BookKeeperAdmin#listLedgers()`.
+
+#### Ledgers listing 
+The goal here is to extend the Client API for listing ledgers. Moreover current method  `BookKeeperAdmin#listLedgers()` does not report errors from the metadata driver; for instance, if an IOException occurs during iterator flow, the error is not visible to the caller and the iteration is stopped (e.g. hasNext will return false). However there is no intention to change this behaviour in this proposal.
+
+#### Simpler access to LedgerMetadata
+The goal here is to streamline the access to `LedgerMetadata`, directly from BookKeeper interface.
+
+#### Ledger id inside LedgerMetadata
+Currently there is no `ledgerId` property inside `LedgerMetadata` interface, this can be helpful in some contexts.
+
+
+### Public Interfaces
+
+This proposal adds new interfaces to `org.apache.bookkeeper.client.api` package, similar to `org.apache.bookkeeper.client.api.BookKeeper` methods. 
+
+    // new interface
+    interface LedgersIterator {
+
+        boolean hasNext() throws IOException;
+
+        long next() throws IOException;
+    }
+
+    // new interface
+    interface ListLedgersResult extends AutoCloseable {
+
+        LedgersIterator iterator();
+
+        Iterable<Long> toIterable();
+    }
+
+    // new interface
+    interface ListLedgersResultBuilder extends OpBuilder<Void>{
+
+        // empty now, maybe some filters in future
+    }
+
+    interface BookKeeper {
+
+        ....
+
+        ListLedgersResultBuilder newListLedgersOp();
+
+        CompleatableFuture<LedgerMetadata> getLedgerMetadata(long ledgerId);
+
+    }
+
+    interface LedgerMetadata {
+        
+        ....
+
+        long getLedgerId();
+
+    }
+
+### Proposed Changes
+
+#### Ledgers listing
+
+The implementation is pretty similar to `BookKeeperAdmin#listLedgers()` but there are few enhancements:
+- Handle metadata driver errors, since the IOException is directly thrown up to caller, allowing user to handle network errors in a more suitable way.
+- Leave the possibility to restrict/filter returned ledgers in future, without API breaking changes   
+- Dispose some resources needed to retrieve ledgers (`ListLedgersResult` extends `AutoCloseable`)) (will be empty for current implementations)
+
+The implementation will be the same used in BookKeeperAdmin, iterating over `LedgerRangeIterator`, which already handles ledgers search properly.
+
+#### Simpler access to LedgerMetadata
+The implementation will use LedgerManager to retrieve metadata for a specified ledgerId.  
+
+#### Ledger id inside LedgerMetadata
+Each time a LedgerMetadata instance is created, the ledgerId is known, so it is trivial to set it in the instance.
+
+### Compatibility, Deprecation, and Migration Plan
+
+No impact for current API, the proposal does not aim to explicit deprecate `BookKeeperAdmin#listLedgers()` method.
+
+### Test Plan
+
+This proposal needs only new unit tests, other tests must continue pass without any changes.
+
+### Rejected Alternatives
+
+An alternative could be creates a new API similar to BookKeeperAdmin but it is better to invest enhancing `org.apache.bookkeeper.client.api.BookKeeper` API.