Improve the client api to a type-safe api (YahooArchive#15)

api/src/main/java/org/apache/distributedlog/api/StorageClient.java

@@ -22,7 +22,7 @@
 import org.apache.bookkeeper.common.annotation.InterfaceAudience.Public;
 import org.apache.bookkeeper.common.annotation.InterfaceStability.Evolving;
 import org.apache.bookkeeper.common.util.AutoAsyncCloseable;
-import org.apache.distributedlog.api.kv.Table;
+import org.apache.distributedlog.api.kv.PTable;
 
 /**
  * The stream storage client.
@@ -31,6 +31,6 @@
 @Evolving
 public interface StorageClient extends AutoAsyncCloseable {
 
-    CompletableFuture<Table> openTable(String table);
+    CompletableFuture<PTable> openPTable(String table);
 
 }

api/src/main/java/org/apache/distributedlog/api/kv/Table.java → api/src/main/java/org/apache/distributedlog/api/kv/PTable.java

@@ -16,11 +16,15 @@
 
 import org.apache.bookkeeper.common.annotation.InterfaceAudience;
 import org.apache.bookkeeper.common.annotation.InterfaceStability;
+import org.apache.distributedlog.api.kv.op.OpFactory;
 
 /**
- * Interface of kv client talking to kv spaces.
+ * Interface of kv client talking to partitioned table.
  */
 @InterfaceAudience.Public
 @InterfaceStability.Evolving
-public interface Table extends ReadView, WriteView {
+public interface PTable<K, V> extends PTableReadView<K, V>, PTableWriteView<K, V> {
+
+    OpFactory<K, V> opFactory();
+
 }

api/src/main/java/org/apache/distributedlog/api/kv/ReadView.java → api/src/main/java/org/apache/distributedlog/api/kv/PTableReadView.java

@@ -14,21 +14,20 @@
 
 package org.apache.distributedlog.api.kv;
 
-import io.netty.buffer.ByteBuf;
 import java.util.concurrent.CompletableFuture;
 import org.apache.bookkeeper.common.annotation.InterfaceAudience;
 import org.apache.bookkeeper.common.annotation.InterfaceStability;
-import org.apache.distributedlog.api.kv.options.GetOption;
-import org.apache.distributedlog.api.kv.result.GetResult;
+import org.apache.distributedlog.api.kv.options.RangeOption;
+import org.apache.distributedlog.api.kv.result.RangeResult;
 
 /**
  * A review view of a key/value space.
  */
 @InterfaceAudience.Public
 @InterfaceStability.Evolving
-public interface ReadView extends AutoCloseable {
+public interface PTableReadView<K, V> extends AutoCloseable {
 
-  CompletableFuture<GetResult> get(ByteBuf pKey, ByteBuf lKey, GetOption option);
+  CompletableFuture<RangeResult<K, V>> get(K pKey, K lKey, RangeOption<K> option);
 
   void close();
 

api/src/main/java/org/apache/distributedlog/api/kv/WriteView.java → api/src/main/java/org/apache/distributedlog/api/kv/PTableWriteView.java

@@ -14,7 +14,6 @@
 
 package org.apache.distributedlog.api.kv;
 
-import io.netty.buffer.ByteBuf;
 import java.util.concurrent.CompletableFuture;
 import org.apache.bookkeeper.common.annotation.InterfaceAudience;
 import org.apache.bookkeeper.common.annotation.InterfaceStability;
@@ -28,11 +27,13 @@
  */
 @InterfaceAudience.Public
 @InterfaceStability.Evolving
-public interface WriteView extends AutoCloseable {
+public interface PTableWriteView<K, V> extends AutoCloseable {
 
-  CompletableFuture<PutResult> put(ByteBuf pKey, ByteBuf lKey, ByteBuf value, PutOption option);
+  CompletableFuture<PutResult<K, V>> put(K pKey, K lKey, V value, PutOption option);
 
-  CompletableFuture<DeleteResult> delete(ByteBuf pKey, ByteBuf lKey, DeleteOption option);
+  CompletableFuture<DeleteResult<K, V>> delete(K pKey, K lKey, DeleteOption<K> option);
+
+  Txn<K, V> txn(K pKey);
 
   void close();
 

api/src/main/java/org/apache/distributedlog/api/kv/Txn.java

@@ -0,0 +1,95 @@
+/*
+ * 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.distributedlog.api.kv;
+
+
+import java.util.concurrent.CompletableFuture;
+import org.apache.distributedlog.api.kv.op.CompareOp;
+import org.apache.distributedlog.api.kv.op.Op;
+import org.apache.distributedlog.api.kv.result.TxnResult;
+
+/**
+ * Txn is the interface that wraps mini-transactions.
+ *
+ * <h3>Usage examples</h3>
+ *
+ * <pre>{@code
+ * txn.If(
+ *    new Cmp(KEY, Cmp.Op.GREATER, CmpTarget.value(VALUE)),
+ *    new Cmp(KEY, cmp.Op.EQUAL, CmpTarget.version(2))
+ * ).Then(
+ *    Op.put(KEY2, VALUE2, PutOption.DEFAULT),
+ *    Op.put(KEY3, VALUE3, PutOption.DEFAULT)
+ * ).Else(
+ *    Op.put(KEY4, VALUE4, PutOption.DEFAULT),
+ *    Op.put(KEY4, VALUE4, PutOption.DEFAULT)
+ * ).commit();
+ * }</pre>
+ *
+ * <p>Txn also supports If, Then, and Else chaining. e.g.
+ * <pre>{@code
+ * txn.If(
+ *    new Cmp(KEY, Cmp.Op.GREATER, CmpTarget.value(VALUE))
+ * ).If(
+ *    new Cmp(KEY, cmp.Op.EQUAL, CmpTarget.version(VERSION))
+ * ).Then(
+ *    Op.put(KEY2, VALUE2, PutOption.DEFAULT)
+ * ).Then(
+ *    Op.put(KEY3, VALUE3, PutOption.DEFAULT)
+ * ).Else(
+ *    Op.put(KEY4, VALUE4, PutOption.DEFAULT)
+ * ).Else(
+ *    Op.put(KEY4, VALUE4, PutOption.DEFAULT)
+ * ).commit();
+ * }</pre>
+ */
+public interface Txn<K, V> {
+
+    /**
+     * takes a list of comparison. If all comparisons passed in succeed,
+     * the operations passed into Then() will be executed. Or the operations
+     * passed into Else() will be executed.
+     */
+    // CHECKSTYLE.OFF: MethodName
+    Txn<K, V> If(CompareOp<K, V>... cmps);
+    // CHECKSTYLE.ON: MethodName
+
+    /**
+     * takes a list of operations. The Ops list will be executed, if the
+     * comparisons passed in If() succeed.
+     */
+    // CHECKSTYLE.OFF: MethodName
+    Txn<K, V> Then(Op<K, V>... ops);
+    // CHECKSTYLE.ON: MethodName
+
+    /**
+     * takes a list of operations. The Ops list will be executed, if the
+     * comparisons passed in If() fail.
+     */
+    // CHECKSTYLE.OFF: MethodName
+    Txn<K, V> Else(Op<K, V>... ops);
+    // CHECKSTYLE.OFF: MethodName
+
+    /**
+     * tries to commit the transaction.
+     *
+     * @return a TxnResponse wrapped in CompletableFuture
+     */
+    CompletableFuture<TxnResult<K, V>> commit();
+
+}

api/src/main/java/org/apache/distributedlog/api/kv/op/CompareOp.java

@@ -0,0 +1,44 @@
+/*
+ * 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.distributedlog.api.kv.op;
+
+import org.apache.bookkeeper.common.annotation.InterfaceAudience.Public;
+import org.apache.bookkeeper.common.annotation.InterfaceStability.Evolving;
+
+/**
+ * A compare operator used in a {@link org.apache.distributedlog.api.kv.Txn}.
+ *
+ * @param <K> key type
+ * @param <V> value type
+ */
+@Public
+@Evolving
+public interface CompareOp<K, V> extends AutoCloseable {
+
+    CompareTarget target();
+
+    CompareResult result();
+
+    K key();
+
+    V value();
+
+    long revision();
+
+}

api/src/main/java/org/apache/distributedlog/api/kv/op/CompareResult.java

@@ -0,0 +1,35 @@
+/*
+ * 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.distributedlog.api.kv.op;
+
+
+import org.apache.bookkeeper.common.annotation.InterfaceAudience.Public;
+import org.apache.bookkeeper.common.annotation.InterfaceStability.Evolving;
+
+/**
+ * Define the compare result for a given {@link CompareOp}.
+ */
+@Public
+@Evolving
+public enum CompareResult {
+    EQUAL,
+    GREATER,
+    LESS,
+    NOT_EQUAL
+}

api/src/main/java/org/apache/distributedlog/api/kv/op/CompareTarget.java

@@ -0,0 +1,31 @@
+/*
+ * 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.distributedlog.api.kv.op;
+
+/**
+ * Target to compare.
+ */
+public enum CompareTarget {
+
+    VERSION,
+    CREATE,
+    MOD,
+    VALUE
+
+}

api/src/main/java/org/apache/distributedlog/api/kv/op/DeleteOp.java

@@ -0,0 +1,35 @@
+/*
+ * 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.distributedlog.api.kv.op;
+
+import org.apache.distributedlog.api.kv.options.DeleteOption;
+
+/**
+ * A delete operator to delete a single key or a key range.
+ *
+ * @param <K> key type
+ * @param <V> value type.
+ */
+public interface DeleteOp<K, V> extends Op<K, V> {
+
+    K key();
+
+    DeleteOption<K> option();
+
+}

api/src/main/java/org/apache/distributedlog/api/kv/op/Op.java

@@ -0,0 +1,33 @@
+/*
+ * 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.distributedlog.api.kv.op;
+
+import org.apache.bookkeeper.common.annotation.InterfaceAudience.Public;
+import org.apache.bookkeeper.common.annotation.InterfaceStability.Evolving;
+
+/**
+ * Abstract Operation.
+ */
+@Public
+@Evolving
+public interface Op<K, V> extends AutoCloseable {
+
+    OpType type();
+
+}