[GitHub] eolivelli commented on a change in pull request #742: Issue-744 BP-18 introduce write flags
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
[GitHub] eolivelli commented on a change in pull request #742: Issue-744 BP-18 introduce write flags
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_r154375634 ## 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 Review comment: @sijie should I do something to address this comment ? Can you give me an hint please ? 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
[GitHub] eolivelli commented on a change in pull request #742: Issue-744 BP-18 introduce write flags
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_r154369538
##
File path: site/docs/latest/api/ledger-api.md
##
@@ -36,12 +36,12 @@ If you're using [Gradle](https://gradle.org/), add this to
your [`build.gradle`]
```groovy
dependencies {
-compile group: 'org.apache.bookkeeper', name: 'bookkeeper-server',
version: '{{ site.latest_version }}'
+compile group: 'org.apache.bookkeeper', name: 'bookkeeper-server',
version: '4.6.0'
}
// Alternatively:
dependencies {
-compile 'org.apache.bookkeeper:bookkeeper-server:{{ site.latest_version }}'
+compile 'org.apache.bookkeeper:bookkeeper-server:4.6.0'
Review comment:
done
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
[GitHub] eolivelli commented on a change in pull request #742: Issue-744 BP-18 introduce write flags
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_r154369521
##
File path: site/docs/latest/api/ledger-api.md
##
@@ -20,7 +20,7 @@ If you're using [Maven](https://maven.apache.org/), add this
to your [`pom.xml`]
```xml
-{{ site.latest_version }}
+4.6.0
Review comment:
done
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
[GitHub] eolivelli commented on a change in pull request #742: Issue-744 BP-18 introduce write flags
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_r154369476 ## File path: site/.ruby-version ## @@ -0,0 +1 @@ +2.4.1 Review comment: it is my local ruby "rbenv", will drop it 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
[GitHub] eolivelli commented on a change in pull request #742: Issue-744 BP-18 introduce write flags
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_r153552849
##
File path:
bookkeeper-server/src/main/java/org/apache/bookkeeper/client/api/WriteFlag.java
##
@@ -0,0 +1,70 @@
+/**
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ */
+package org.apache.bookkeeper.client.api;
+
+import java.util.EnumSet;
+import lombok.Getter;
+
+/**
+ * Flags to specify the behaviour of writes
+ */
+@Getter
+public enum WriteFlag {
+
+/**
+ * Writes will be acknowledged after writing to the filesystem
+ * but not yet been persisted to disks.
+ */
+DEFERRED_SYNC(0x1 << 0);
Review comment:
This is a very long story...I have already sent patches for this change but
I have to rewrite all.
But I am not moving forward and rewrite the whole stuff without merging one
step at a time.
If you want me to send next patches I will do but please first make this
patch fully approved by every stakeholder, even without merging
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
[GitHub] eolivelli commented on a change in pull request #742: Issue-744 BP-18 introduce write flags
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_r153552867
##
File path:
bookkeeper-server/src/main/java/org/apache/bookkeeper/client/api/WriteFlag.java
##
@@ -0,0 +1,70 @@
+/**
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ */
+package org.apache.bookkeeper.client.api;
+
+import java.util.EnumSet;
+import lombok.Getter;
+
+/**
+ * Flags to specify the behaviour of writes
+ */
+@Getter
+public enum WriteFlag {
+
+/**
+ * Writes will be acknowledged after writing to the filesystem
+ * but not yet been persisted to disks.
+ */
+DEFERRED_SYNC(0x1 << 0);
Review comment:
This is a very long story...I have already sent patches for this change but
I have to rewrite all.
But I am not moving forward and rewrite the whole stuff without merging one
step at a time.
If you want me to send next patches I will do but please first make this
patch fully approved by every stakeholder, even without merging
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
[GitHub] eolivelli commented on a change in pull request #742: Issue-744 BP-18 introduce write flags
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_r153552837
##
File path:
bookkeeper-server/src/main/java/org/apache/bookkeeper/client/api/WriteFlag.java
##
@@ -0,0 +1,70 @@
+/**
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ */
+package org.apache.bookkeeper.client.api;
+
+import java.util.EnumSet;
+import lombok.Getter;
+
+/**
+ * Flags to specify the behaviour of writes
+ */
+@Getter
+public enum WriteFlag {
+
+/**
+ * Writes will be acknowledged after writing to the filesystem
+ * but not yet been persisted to disks.
+ */
+DEFERRED_SYNC(0x1 << 0);
Review comment:
This is a very long story...I have already sent patches for this change but
I have to rewrite all.
But I am not moving forward and rewrite the whole stuff without merging one
step at a time.
If you want me to send next patches I will do but please first make this
patch fully approved by every stakeholder, even without merging
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
[GitHub] eolivelli commented on a change in pull request #742: Issue-744 BP-18 introduce write flags
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_r152822846
##
File path:
bookkeeper-server/src/main/java/org/apache/bookkeeper/client/api/WriteFlag.java
##
@@ -0,0 +1,72 @@
+/**
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ */
+package org.apache.bookkeeper.client.api;
+
+import static com.google.common.base.Preconditions.checkArgument;
+
+import java.util.EnumSet;
+import lombok.Getter;
+
+/**
+ * Flags to specify the behaviour of writes
+ */
+@Getter
+public enum WriteFlag {
+
+/**
+ * Writes will be ackknowledged by the server even if the entry
+ * has not been persisted durably.
+ */
+DEFERRED_FORCE(0x1 << 0);
Review comment:
renamed to DEFERRED_SYNC as decided on slack
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
[GitHub] eolivelli commented on a change in pull request #742: Issue-744 BP-18 introduce write flags
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_r152333935
##
File path:
bookkeeper-server/src/main/java/org/apache/bookkeeper/client/api/WriteFlag.java
##
@@ -0,0 +1,72 @@
+/**
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ */
+package org.apache.bookkeeper.client.api;
+
+import static com.google.common.base.Preconditions.checkArgument;
+
+import java.util.EnumSet;
+import lombok.Getter;
+
+/**
+ * Flags to specify the behaviour of writes
+ */
+@Getter
+public enum WriteFlag {
+
+/**
+ * Writes will be ackknowledged by the server even if the entry
+ * has not been persisted durably.
+ */
+DEFERRED_FORCE(0x1 << 0);
Review comment:
I saw so many comments on this topic.
I like the word "sync" it is more "filesystem stuff" foe me.
The new API will be "force()" as in Java NIO API (FileChannel.force).
Honestly I would prefer something like "EXPLICIT_FORCE", because with this
flag you have to call explicitly "WriteHandle#force"
I know this is very important because we cannot change this name in the
future, but I would like to move forward
@jvrao @ivankelly @sijie
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
[GitHub] eolivelli commented on a change in pull request #742: Issue-744 BP-18 introduce write flags
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_r152332174
##
File path:
bookkeeper-server/src/test/java/org/apache/bookkeeper/client/api/WriteFlagTest.java
##
@@ -20,34 +20,29 @@
*/
package org.apache.bookkeeper.client.api;
-import java.util.EnumSet;
import static org.apache.bookkeeper.client.api.WriteFlag.DEFERRED_FORCE;
+import static org.junit.Assert.assertEquals;
+
+import java.util.EnumSet;
import org.junit.Test;
-import static org.junit.Assert.*;
/**
* Utit tests for WriteFlag
*/
public class WriteFlagTest {
+private final static int NONE = 0;
Review comment:
donr
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
[GitHub] eolivelli commented on a change in pull request #742: Issue-744 BP-18 introduce write flags
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_r152332135
##
File path:
bookkeeper-server/src/main/java/org/apache/bookkeeper/client/api/WriteFlag.java
##
@@ -20,14 +20,22 @@
*/
package org.apache.bookkeeper.client.api;
-import com.google.common.base.Preconditions;
+import static com.google.common.base.Preconditions.checkArgument;
+
import java.util.EnumSet;
+import lombok.Getter;
/**
* Flags to specify the behaviour of writes
*/
+@Getter
public enum WriteFlag {
-DEFERRED_FORCE(1);
+
+/**
+ * Writes will be ackknowledged by the server even if the entry
Review comment:
done
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
[GitHub] eolivelli commented on a change in pull request #742: Issue-744 BP-18 introduce write flags
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_r152331321 ## File path: bookkeeper-server/src/main/java/org/apache/bookkeeper/client/api/CreateBuilder.java ## @@ -100,6 +101,16 @@ * @return the builder itself */ CreateBuilder withWriteFlags(EnumSet writeFlags); +/** Review comment: done 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
[GitHub] eolivelli commented on a change in pull request #742: Issue-744 BP-18 introduce write flags
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_r152331090
##
File path: bookkeeper-proto/src/main/proto/BookkeeperProtocol.proto
##
@@ -112,6 +112,7 @@ message AddRequest {
required int64 entryId = 2;
required bytes masterKey = 3;
required bytes body = 4;
+optional int64 writeFlags = 5;
Review comment:
done
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
