Page History

WORK-IN-PROGRESS

this document is currently subject to changes

Motivation

Currently (in BookKeeper 4.5) we have several overloaded versions of the methods createLedger/createLedegerAdv/asyncCreateLeader/asyncCreateLeaderAdv. This methods are present because from version to version we added new configuration options for the Ledger.

In order to support new features in the future we need to have a more extensible API.

Proposed Change

We can use the Builder design pattern to define a new unified createLedger and asyncCreateLedger APISo we will introduce a new set of APIs to construct Ledgers, in the future this pattern will be extended to other operations, like delete/close/addEntry.

This is an example of the new APIhow the client code will look like:

        BookKeeper bookeeper = ....;
 CreateBuilder       LedgerConfiguration ledgerConfiguration builder = LedgerConfigurationbookkeeper.buildercreateBuilder();
 CompletableFuture<LedgerHandler> future                                                                        = builder
    .ensembleSize(3)
                                                                              .writeQuorumSize(2)
                                                                              .ackQuorumSize(1)
                                                                              .digestType(DigestType.CRC32)                                       
																			    .customMetadata(Map<String, byte[]> metadata)
    .password(password)
    .advanced(true|false)
    .build();
LedgerHandler lh = future.get();

Migration Plan and Compatibility

No issue about migration and compatibility.

Legacy methods will be retained. No @Deprecated annotation will be added. Further removal of existing APIs will be evaluated in the future, maybe while starting a new major release, like 5.0.0

Rejected Alternatives

This is an example of an alternative API which has been rejected, as it will not be really extensible in the future

        BookKeeper bookeeper = ....;
        LedgerConfiguration ledgerConfiguration                                           .password(password= LedgerConfiguration.builder()
                                                                              .advancedensembleSize(true|false3);
        LedgerHandle ledger = bookeeper.createLedger(ledgerConfiguration);
        bookeeper.createLedgerAsync(ledgerConfiguration, createCallback,  ctx);
        CompletableFuture<LedgerHandle> future = bookeeper.asyncCreateLedger(ledgerConfiguration);

So we will introduce a new LedgerConfiguration class which defines the configuration options of the Ledger and we will support a new simple API which takes that structure.

Existing API will be supported, and maybe it will be deprecated and finally dropped in new major releases (5.0.0)

New or Changed Public Interfaces

We are going to introduce the LedgerConfiguration class which defines the specification for new ledgers.

public final LedgerConfiguration  {    
               private final int ensembleSize = 1;
               private final int writeQuorumSize = 1;.writeQuorumSize(2)
               private final int ackQuorumSize = 1;
               private final DigestType digestType = DigestType.CRC32;
               private final byte[] password = EMPTY_ARRAY;
               private final boolean advanced = false;
               private final Map<String, byte[]> customMetadata = null;   (will be an un-modifiable Map)
 .ackQuorumSize(1)
                       /**
               * Create a new LedgerConfiguration with default values

               **/

               public static Builder builder.digestType(DigestType.CRC32) { return new Builder(); }
               /**
               * Create a new LedgerConfiguration using another configuration as starting values

 
																			  .customMetadata(Map<String, byte[]> metadata)
               **/

              public static Builder cloning(LedgerConfiguration configuration) {......}

              public static final class Builder() {
                         ... builder methods...
                         public LedgerConfiguration build() throws BKException;

password(password)
              } 
}

This new class will be immutable and it will provide only getters.

On BookKeeper class we are going to introduce this new methods

public LedgerHandle createLedger(LedgerConfiguration ledgerConfiguration);

public void asyncCreateLedger(LedgerConfiguration ledgerConfiguration, CreateCallback callback, Object context);

public CompletableFuture<LedgerHandle> asyncCreateLedger(LedgerConfiguration ledgerConfiguration);

Migration Plan and Compatibility

No issue about migration and compatibility.

Legacy methods will be retained. No @Deprecated annotation will be added. Futher removal of existing APIs will be evaluated in the future, maybe while starting a new major release, like 5.0.0

Rejected Alternatives

An alternative is not to explicitly add a LedgerConfiguration class but to add some builder method to the BookKeper class, like

BookKeeper bookkeeper =.....;
CompletableFuture<LedgerHandle> lh = bookkeeper.newLedgerBuilder()
                                               .ensembleSizeadvanced(5true|false);
        LedgerHandle ledger                                      = bookeeper.createLedger(ledgerConfiguration);

...