Skip to main content

BP-42: New Client API - list ledgers

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.