eolivelli commented on a change in pull request #742: Issue-744 BP-18 introduce write flags URL: https://github.com/apache/bookkeeper/pull/742#discussion_r154375957
########## File path: site/docs/latest/api/ledger-api.md ########## @@ -471,3 +471,304 @@ mvn exec:java -Dexec.mainClass=org.apache.bookkeeper.Dice Value = 3, isLeader = true Value = 1, isLeader = false ``` + +## New API + +Since 4.6 BookKeeper provides a new client API which leverages Java8 [CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html) facility. +[WriteHandle](../javadoc/org/apache/bookkeeper/client/api/WriteHandle), [WriteAdvHandle](../javadoc/org/apache/bookkeeper/client/api/WriteAdvHandle), [ReadHandle](../javadoc/org/apache/bookkeeper/client/api/ReadHandle) are introduced for replacing the generic [LedgerHandle](../javadoc/org/apache/bookkeeper/client/LedgerHandle). + +> All the new API now is available in `org.apache.bookkeeper.client.api`. You should only use interfaces defined in this package. + +*Beware* that this API in 4.6 is still experimental API and can be subject to changes in next minor releases. + +### Create a new client + +In order to create a new [`BookKeeper`](../javadoc/org/apache/bookkeeper/client/api/BookKeeper) client object, you need to construct a [`ClientConfiguration`](../javadoc/org/apache/bookkeeper/conf/ClientConfiguration) object and set a [connection string](#connection-string) first, and then use [`BookKeeperBuilder`](../javadoc/org/apache/bookkeeper/client/api/BookKeeperBuilder) to build the client. + +Here is an example building the bookkeeper client. + +```java +// construct a client configuration instance +ClientConfiguration conf = new ClientConfiguration(); +conf.setZkServers(zkConnectionString); +conf.setZkLedgersRootPath("/path/to/ledgers/root"); + +// build the bookkeeper client +BookKeeper bk = BookKeeper.newBuilder(conf) + .statsLogger(...) + ... + .build(); + +``` + +### Create ledgers + +the easiest way to create a {% pop ledger %} using the java client is via the [`createbuilder`](../javadoc/org/apache/bookkeeper/client/api/createbuilder). you must specify at least +a [`digesttype`](../javadoc/org/apache/bookkeeper/client/api/digesttype) and a password. + +here's an example: + +```java +BookKeeper bk = ...; + +byte[] password = "some-password".getBytes(); + +WriteHandle wh = bk.newCreateLedgerOp() + .withDigestType(DigestType.CRC32) + .withPassword(password) + .withEnsembleSize(3) + .withWriteQuorumSize(3) + .withAckQuorumSize(2) + .execute() // execute the creation op + .get(); // wait for the execution to complete +``` + +A [`WriteHandle`](../javadoc/org/apache/bookkeeper/client/api/WriteHandle) is returned for applications to write and read entries to and from the ledger. + +### Write flags + +You can specify behaviour of the writer by setting [`WriteFlags`](../javadoc/org/apache/bookkeeper/client/api/WriteFlag) at ledger creation type. +These flags are applied only during write operations and are not recorded on metadata. + +For instance we have the [`DEFERRED_SYNC`](../javadoc/org/apache/bookkeeper/client/api/WriteFlag#DEFERRED_SYNC) write flag which allows writes to be acknowledged by the server early, without waiting for Review comment: I have tried to add a table, but tables are an extension of Jekyll and in the laptop I have today I have no working Jekyll, I will re-check on next days. I will be back to confirm the change works, sorry :-( ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
