Versions Compared

Old Version 11

changes.mady.by.user Unknown User (eolivelli)

Saved on

compared with

New Version Current

changes.mady.by.user Unknown User (eolivelli)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Code Block
 BookKeeper bookeeper = ....;
 CompletableFuture<WriteHandler> future = bookkeeper.createLedger()
    .withEnsembleSize(3)
    .withWriteQuorumSize(2)
    .withAckQuorumSize(1)
    .withDigestType(DigestType.CRC32)                                       
    .withCustomMetadata(metadata)
    .withPassword(password)
    .apply();
IWriterHandlerWriteHandler lh = future.get();

 CompletableFuture<WriteHandlerAdv>CompletableFuture<WriteAdvHandler> future = bookkeeper.createLedger()
    .withEnsembleSize(3)
    .withWriteQuorumSize(2)
    .withAckQuorumSize(1)
    .withDigestType(DigestType.CRC32)                                       
    .withCustomMetadata(metadata)
    .withPassword(password)
    .withLedgerId(ledgerId)
    .makeAdv()
    .apply();
IWriterHandlerAdvWriteAdvHandler lh = future.get();
 

In order to achieve this goal we are going to introduce a ICreateBuilder CreateBuilder and ICreateAdvBuilder CreateBuilderAdv interfaces

Code Block
interface ICreateBuilderCreateBuilder {
     ICreateBuilderCreateBuilder withEnsembleSize(...);
     ICreateBuilderCreateBuilder withWriteQuorumSize(...);
     ...
     ICreateAdvBuilderCreateAdvBuilder makeAdv();

     // old style callbacks
     void execute(CreateCallback callback, Object ctx);
     // support java8 completable future
     CompletableFuture<IWriteHandler>CompletableFuture<WriteHandler> apply();
     // sync method
     IWriteHandlerWriteHandler create() throws BKException, InterruptedException;
 }
interface ICreateAdvBuilderCreateAdvBuilder {
     // old style callbacks
     void execute(CreateCallback callback, Object ctx);
     // support java8 completable future
     CompletableFuture<IWriteHandlerAdv>CompletableFuture<WriteAdvHandler> apply();
     // sync method
     IWriteHandlerAdvWriteAdvHandler create() throws BKException, InterruptedException;

}
interface OpenBuilder {
     OpenBuilder withRecovery(boolean)
     OpenBuilder withPassword(password) 
     OpenBuilder withDigestType(digestType)
     CompletableFuture<ReadHandler> apply(long ledgerId)
     void open(long ledgerId, OpenCallback cb, Object ctx)
     ReadHandler open(long ledgerId)
}

And we will make CrateLedgerOp implement such interfaces.

We are going to introduce an IBookKeeper a new BookKeeper interface

Code Block
interface IBookKeeperBookKeeper extends AutoCloseable { 
      ICreateBuilderCreateBuilder createLedger();
      IOpenBuilderOpenBuilder   openLedger();
}

We are going to introduce IWriteHandler WriteHandler and IWriteHandlerAdv WriteHandlerAdv interfaces which contains only the API related to writing to a Ledger, following the LedgerHandler/LedgerHandlerAdv semantics.

In a similar way we are going to introduce a IReadHandler a ReadHandler which contains only the API related to reading to a Ledger and a IOpenBuilderOpenBuilder.

Please note that IWriteHandler WriteHandler and IWriteHandlerAdv WriteAdvHandler will extend IReadHandler ReadHandler as writer need to be able to read its own writes.

A common ILedgerHandler Handler interface will be a base interface for IReadHandler ReadHandler and it will contain basic operations like 'close'

Code Block
 interface IOpenBuilderHandler {
extends     IOpenBuilder withRecovery(boolean)AutoCloseable {
     IOpenBuildervoid withPasswordclose(password) ;
     IOpenBuilder withDigestType(digestType)
     CompleableFuture<IReadHandler> apply(long ledgerId)
     void open(long ledgerId, OpenCallback asyncClose(CloseCallback cb, Object ctx)
     IReadHandler open(long ledgerId)
}

interface ILedgerHandler {
     void close();
     void asyncClose();
}

interface IReadHandlerReadHandler extends ILedgerHandlerHandler {
     void readEntries();
     long readLastAddConfirmed();
     .....
     
}
interface IWriteHandlerWriteHandler extends IReadHandlerReadHandler {
     void addEntry(byte[] data)
     void sync(...)
}
interface IWriteHandlerAdvWriteAdvHandler extends IReadHandlerReadHandler {
     void addEntry(long entryID, byte[] data)
     void sync(...)
}

...

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

...

We can create similar API style for addEntry, readEntries and other operations which need an extensible API.

We would leverage CompletableFuture for operations like close, delete, addEntry, readEntries....

Rejected Alternatives

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

...