AsyncConsistentMap methods for supporting transactional updates
Change-Id: Iaeb0aa0abf9f52d514a2c040598599a5b8a55ee8
diff --git a/core/api/src/main/java/org/onosproject/store/primitives/MapUpdate.java b/core/api/src/main/java/org/onosproject/store/primitives/MapUpdate.java
new file mode 100644
index 0000000..c8151e3
--- /dev/null
+++ b/core/api/src/main/java/org/onosproject/store/primitives/MapUpdate.java
@@ -0,0 +1,247 @@
+/*
+ * Copyright 2015 Open Networking Laboratory
+ *
+ * Licensed 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.onosproject.store.primitives;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+import static com.google.common.base.Preconditions.checkState;
+
+import java.util.function.Function;
+
+import com.google.common.base.MoreObjects;
+
+/**
+ * Map update operation.
+ *
+ * @param <K> map key type
+ * @param <V> map value type
+ *
+ */
+public final class MapUpdate<K, V> {
+
+ /**
+ * Type of database update operation.
+ */
+ public enum Type {
+ /**
+ * Insert/Update entry without any checks.
+ */
+ PUT,
+ /**
+ * Insert an entry iff there is no existing entry for that key.
+ */
+ PUT_IF_ABSENT,
+
+ /**
+ * Update entry if the current version matches specified version.
+ */
+ PUT_IF_VERSION_MATCH,
+
+ /**
+ * Update entry if the current value matches specified value.
+ */
+ PUT_IF_VALUE_MATCH,
+
+ /**
+ * Remove entry without any checks.
+ */
+ REMOVE,
+
+ /**
+ * Remove entry if the current version matches specified version.
+ */
+ REMOVE_IF_VERSION_MATCH,
+
+ /**
+ * Remove entry if the current value matches specified value.
+ */
+ REMOVE_IF_VALUE_MATCH,
+ }
+
+ private String mapName;
+ private Type type;
+ private K key;
+ private V value;
+ private V currentValue;
+ private long currentVersion = -1;
+
+ /**
+ * Returns the name of the map.
+ *
+ * @return map name
+ */
+ public String mapName() {
+ return mapName;
+ }
+
+ /**
+ * Returns the type of update operation.
+ * @return type of update.
+ */
+ public Type type() {
+ return type;
+ }
+
+ /**
+ * Returns the item key being updated.
+ * @return item key
+ */
+ public K key() {
+ return key;
+ }
+
+ /**
+ * Returns the new value.
+ * @return item's target value.
+ */
+ public V value() {
+ return value;
+ }
+
+ /**
+ * Returns the expected current value for the key.
+ * @return current value in database.
+ */
+ public V currentValue() {
+ return currentValue;
+ }
+
+ /**
+ * Returns the expected current version in the database for the key.
+ * @return expected version.
+ */
+ public long currentVersion() {
+ return currentVersion;
+ }
+
+ /**
+ * Transforms this instance into an instance of different paramterized types.
+ *
+ * @param keyMapper transcoder for key type
+ * @param valueMapper transcoder to value type
+ * @return new instance
+ * @param <S> key type of returned instance
+ * @param <T> value type of returned instance
+ */
+ public <S, T> MapUpdate<S, T> map(Function<K, S> keyMapper, Function<V, T> valueMapper) {
+ return MapUpdate.<S, T>newBuilder()
+ .withMapName(mapName)
+ .withType(type)
+ .withKey(keyMapper.apply(key))
+ .withValue(value == null ? null : valueMapper.apply(value))
+ .withCurrentValue(currentValue == null ? null : valueMapper.apply(currentValue))
+ .withCurrentVersion(currentVersion)
+ .build();
+ }
+
+ @Override
+ public String toString() {
+ return MoreObjects.toStringHelper(this)
+ .add("mapName", mapName)
+ .add("type", type)
+ .add("key", key)
+ .add("value", value)
+ .add("currentValue", currentValue)
+ .add("currentVersion", currentVersion)
+ .toString();
+ }
+
+ /**
+ * Creates a new builder instance.
+ *
+ * @param <K> key type
+ * @param <V> value type
+ * @return builder.
+ */
+ public static <K, V> Builder<K, V> newBuilder() {
+ return new Builder<>();
+ }
+
+ /**
+ * MapUpdate builder.
+ *
+ * @param <K> key type
+ * @param <V> value type
+ */
+ public static final class Builder<K, V> {
+
+ private MapUpdate<K, V> update = new MapUpdate<>();
+
+ public MapUpdate<K, V> build() {
+ validateInputs();
+ return update;
+ }
+
+ public Builder<K, V> withMapName(String name) {
+ update.mapName = checkNotNull(name, "name cannot be null");
+ return this;
+ }
+
+ public Builder<K, V> withType(Type type) {
+ update.type = checkNotNull(type, "type cannot be null");
+ return this;
+ }
+
+ public Builder<K, V> withKey(K key) {
+ update.key = checkNotNull(key, "key cannot be null");
+ return this;
+ }
+
+ public Builder<K, V> withCurrentValue(V value) {
+ update.currentValue = value;
+ return this;
+ }
+
+ public Builder<K, V> withValue(V value) {
+ update.value = value;
+ return this;
+ }
+
+ public Builder<K, V> withCurrentVersion(long version) {
+ update.currentVersion = version;
+ return this;
+ }
+
+ private void validateInputs() {
+ checkNotNull(update.type, "type must be specified");
+ checkNotNull(update.key, "key must be specified");
+ switch (update.type) {
+ case PUT:
+ case PUT_IF_ABSENT:
+ checkNotNull(update.value, "value must be specified.");
+ break;
+ case PUT_IF_VERSION_MATCH:
+ checkNotNull(update.value, "value must be specified.");
+ checkState(update.currentVersion >= 0, "current version must be specified");
+ break;
+ case PUT_IF_VALUE_MATCH:
+ checkNotNull(update.value, "value must be specified.");
+ checkNotNull(update.currentValue, "currentValue must be specified.");
+ break;
+ case REMOVE:
+ break;
+ case REMOVE_IF_VERSION_MATCH:
+ checkState(update.currentVersion >= 0, "current version must be specified");
+ break;
+ case REMOVE_IF_VALUE_MATCH:
+ checkNotNull(update.currentValue, "currentValue must be specified.");
+ break;
+ default:
+ throw new IllegalStateException("Unknown operation type");
+ }
+ }
+ }
+}
diff --git a/core/api/src/main/java/org/onosproject/store/service/AsyncConsistentMap.java b/core/api/src/main/java/org/onosproject/store/service/AsyncConsistentMap.java
index 8e2bae0..a914d0c 100644
--- a/core/api/src/main/java/org/onosproject/store/service/AsyncConsistentMap.java
+++ b/core/api/src/main/java/org/onosproject/store/service/AsyncConsistentMap.java
@@ -26,6 +26,7 @@
import java.util.function.Predicate;
import org.onosproject.store.primitives.DefaultConsistentMap;
+import org.onosproject.store.primitives.TransactionId;
/**
* A distributed, strongly consistent map whose methods are all executed asynchronously.
@@ -319,6 +320,37 @@
CompletableFuture<Void> removeListener(MapEventListener<K, V> listener);
/**
+ * Prepares a transaction for commitment.
+ * @param transaction transaction
+ * @return {@code true} if prepare is successful and transaction is ready to be committed;
+ * {@code false} otherwise
+ */
+ CompletableFuture<Boolean> prepare(MapTransaction<K, V> transaction);
+
+ /**
+ * Commits a previously prepared transaction.
+ * @param transactionId transaction identifier
+ * @return future that will be completed when the operation finishes
+ */
+ CompletableFuture<Void> commit(TransactionId transactionId);
+
+ /**
+ * Aborts a previously prepared transaction.
+ * @param transactionId transaction identifier
+ * @return future that will be completed when the operation finishes
+ */
+ CompletableFuture<Void> rollback(TransactionId transactionId);
+
+ /**
+ * Returns a new {@link ConsistentMap} that is backed by this instance.
+ *
+ * @return new {@code ConsistentMap} instance
+ */
+ default ConsistentMap<K, V> asConsistentMap() {
+ return asConsistentMap(DistributedPrimitive.DEFAULT_OPERTATION_TIMEOUT_MILLIS);
+ }
+
+ /**
* Returns a new {@link ConsistentMap} that is backed by this instance.
*
* @param timeoutMillis timeout duration for the returned ConsistentMap operations
diff --git a/core/api/src/main/java/org/onosproject/store/service/MapTransaction.java b/core/api/src/main/java/org/onosproject/store/service/MapTransaction.java
new file mode 100644
index 0000000..3c4f743
--- /dev/null
+++ b/core/api/src/main/java/org/onosproject/store/service/MapTransaction.java
@@ -0,0 +1,74 @@
+/*
+ * Copyright 2016 Open Networking Laboratory
+ *
+ * Licensed 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.onosproject.store.service;
+
+import java.util.List;
+import java.util.function.Function;
+
+import org.onosproject.store.primitives.MapUpdate;
+import org.onosproject.store.primitives.TransactionId;
+
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.Lists;
+
+/**
+ * Collection of map updates to be committed atomically.
+ *
+ * @param <K> key type
+ * @param <V> value type
+ */
+public class MapTransaction<K, V> {
+
+ private final TransactionId transactionId;
+ private final List<MapUpdate<K, V>> updates;
+
+ public MapTransaction(TransactionId transactionId, List<MapUpdate<K, V>> updates) {
+ this.transactionId = transactionId;
+ this.updates = ImmutableList.copyOf(updates);
+ }
+
+ /**
+ * Returns the transaction identifier.
+ *
+ * @return transaction id
+ */
+ public TransactionId transactionId() {
+ return transactionId;
+ }
+
+ /**
+ * Returns the list of map updates.
+ *
+ * @return map updates
+ */
+ public List<MapUpdate<K, V>> updates() {
+ return updates;
+ }
+
+ /**
+ * Maps this instance to another {@code MapTransaction} with different key and value types.
+ *
+ * @param keyMapper function for mapping key types
+ * @param valueMapper function for mapping value types
+ * @return newly typed instance
+ *
+ * @param <S> key type of returned instance
+ * @param <T> value type of returned instance
+ */
+ public <S, T> MapTransaction<S, T> map(Function<K, S> keyMapper, Function<V, T> valueMapper) {
+ return new MapTransaction<>(transactionId, Lists.transform(updates, u -> u.map(keyMapper, valueMapper)));
+ }
+}
diff --git a/core/api/src/test/java/org/onosproject/store/primitives/MapUpdateTest.java b/core/api/src/test/java/org/onosproject/store/primitives/MapUpdateTest.java
new file mode 100644
index 0000000..b8ce039
--- /dev/null
+++ b/core/api/src/test/java/org/onosproject/store/primitives/MapUpdateTest.java
@@ -0,0 +1,127 @@
+/*
+ * Copyright 2015 Open Networking Laboratory
+ *
+ * Licensed 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.onosproject.store.primitives;
+
+import com.google.common.testing.EqualsTester;
+
+import org.junit.Test;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.is;
+
+/**
+ * Unit Tests for MapUpdate class.
+ */
+
+public class MapUpdateTest {
+
+ private final MapUpdate<String, byte[]> stats1 = MapUpdate.<String, byte[]>newBuilder()
+ .withCurrentValue("1".getBytes())
+ .withValue("2".getBytes())
+ .withCurrentVersion(3)
+ .withKey("4")
+ .withMapName("5")
+ .withType(MapUpdate.Type.PUT)
+ .build();
+
+ private final MapUpdate<String, byte[]> stats2 = MapUpdate.<String, byte[]>newBuilder()
+ .withCurrentValue("1".getBytes())
+ .withValue("2".getBytes())
+ .withCurrentVersion(3)
+ .withKey("4")
+ .withMapName("5")
+ .withType(MapUpdate.Type.REMOVE)
+ .build();
+
+ private final MapUpdate<String, byte[]> stats3 = MapUpdate.<String, byte[]>newBuilder()
+ .withCurrentValue("1".getBytes())
+ .withValue("2".getBytes())
+ .withCurrentVersion(3)
+ .withKey("4")
+ .withMapName("5")
+ .withType(MapUpdate.Type.REMOVE_IF_VALUE_MATCH)
+ .build();
+
+ private final MapUpdate<String, byte[]> stats4 = MapUpdate.<String, byte[]>newBuilder()
+ .withCurrentValue("1".getBytes())
+ .withValue("2".getBytes())
+ .withCurrentVersion(3)
+ .withKey("4")
+ .withMapName("5")
+ .withType(MapUpdate.Type.REMOVE_IF_VERSION_MATCH)
+ .build();
+
+ private final MapUpdate<String, byte[]> stats5 = MapUpdate.<String, byte[]>newBuilder()
+ .withCurrentValue("1".getBytes())
+ .withValue("2".getBytes())
+ .withCurrentVersion(3)
+ .withKey("4")
+ .withMapName("5")
+ .withType(MapUpdate.Type.PUT_IF_VALUE_MATCH)
+ .build();
+
+ private final MapUpdate<String, byte[]> stats6 = MapUpdate.<String, byte[]>newBuilder()
+ .withCurrentValue("1".getBytes())
+ .withValue("2".getBytes())
+ .withCurrentVersion(3)
+ .withKey("4")
+ .withMapName("5")
+ .withType(MapUpdate.Type.PUT_IF_VERSION_MATCH)
+ .build();
+
+ /**
+ * Tests the constructor for the class.
+ */
+ @Test
+ public void testConstruction() {
+ assertThat(stats1.currentValue(), is("1".getBytes()));
+ assertThat(stats1.value(), is("2".getBytes()));
+ assertThat(stats1.currentVersion(), is(3L));
+ assertThat(stats1.key(), is("4"));
+ assertThat(stats1.mapName(), is("5"));
+ assertThat(stats1.type(), is(MapUpdate.Type.PUT));
+ }
+
+ /**
+ * Tests the equals, hashCode and toString methods using Guava EqualsTester.
+ */
+ @Test
+ public void testEquals() {
+ new EqualsTester()
+ .addEqualityGroup(stats1, stats1)
+ .addEqualityGroup(stats2)
+ .testEquals();
+
+ new EqualsTester()
+ .addEqualityGroup(stats3, stats3)
+ .addEqualityGroup(stats4)
+ .testEquals();
+
+ new EqualsTester()
+ .addEqualityGroup(stats5, stats5)
+ .addEqualityGroup(stats6)
+ .testEquals();
+ }
+
+ /**
+ * Tests if the toString method returns a consistent value for hashing.
+ */
+ @Test
+ public void testToString() {
+ assertThat(stats1.toString(), is(stats1.toString()));
+ }
+
+}