WIP: Revamped transaction API. Introduces a transaction context for running blocks of code that can be committed
atomically.
Change-Id: I6ba21050a2644a42f3c073fa04ff776ef2c5ff4c
diff --git a/core/api/src/main/java/org/onosproject/store/service/ConsistentMap.java b/core/api/src/main/java/org/onosproject/store/service/ConsistentMap.java
index a375fe0..e0ed4bc 100644
--- a/core/api/src/main/java/org/onosproject/store/service/ConsistentMap.java
+++ b/core/api/src/main/java/org/onosproject/store/service/ConsistentMap.java
@@ -17,7 +17,6 @@
package org.onosproject.store.service;
import java.util.Collection;
-import java.util.List;
import java.util.Set;
import java.util.Map.Entry;
@@ -37,13 +36,6 @@
* concurrency by allowing conditional updates that take into consideration
* the version or value that was previously read.
* </p><p>
- * The map also supports atomic batch updates (transactions). One can provide a list
- * of updates to be applied atomically if and only if all the operations are guaranteed
- * to succeed i.e. all their preconditions are met. For example, the precondition
- * for a putIfAbsent API call is absence of a mapping for the key. Similarly, the
- * precondition for a conditional replace operation is the presence of an expected
- * version or value
- * </p><p>
* This map does not allow null values. All methods can throw a ConsistentMapException
* (which extends RuntimeException) to indicate failures.
*
@@ -202,15 +194,4 @@
* @return true if the value was replaced
*/
boolean replace(K key, long oldVersion, V newValue);
-
- /**
- * Atomically apply the specified list of updates to the map.
- * If any of the updates cannot be applied due to a precondition
- * violation, none of the updates will be applied and the state of
- * the map remains unaltered.
- *
- * @param updates list of updates to apply atomically.
- * @return true if the map was updated.
- */
- boolean batchUpdate(List<UpdateOperation<K, V>> updates);
}
diff --git a/core/api/src/main/java/org/onosproject/store/service/StorageService.java b/core/api/src/main/java/org/onosproject/store/service/StorageService.java
index 32512c8..c99b7b8 100644
--- a/core/api/src/main/java/org/onosproject/store/service/StorageService.java
+++ b/core/api/src/main/java/org/onosproject/store/service/StorageService.java
@@ -39,5 +39,9 @@
*/
<K, V> ConsistentMap<K , V> createConsistentMap(String name, Serializer serializer);
- // TODO: add API for creating Eventually Consistent Map.
+ /**
+ * Creates a new transaction context.
+ * @return transaction context
+ */
+ TransactionContext createTransactionContext();
}
\ No newline at end of file
diff --git a/core/api/src/main/java/org/onosproject/store/service/TransactionContext.java b/core/api/src/main/java/org/onosproject/store/service/TransactionContext.java
new file mode 100644
index 0000000..4fbeeeb
--- /dev/null
+++ b/core/api/src/main/java/org/onosproject/store/service/TransactionContext.java
@@ -0,0 +1,64 @@
+/*
+ * 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.service;
+
+/**
+ * Provides a context for transactional operations.
+ * <p>
+ * A transaction context provides a boundary within which transactions
+ * are run. It also is a place where all modifications made within a transaction
+ * are cached until the point when the transaction commits or aborts. It thus ensures
+ * isolation of work happening with in the transaction boundary.
+ * <p>
+ * A transaction context is a vehicle for grouping operations into a unit with the
+ * properties of atomicity, isolation, and durability. Transactions also provide the
+ * ability to maintain an application's invariants or integrity constraints,
+ * supporting the property of consistency. Together these properties are known as ACID.
+ */
+public interface TransactionContext {
+
+ /**
+ * Returns if this transaction context is open.
+ * @return true if open, false otherwise.
+ */
+ boolean isOpen();
+
+ /**
+ * Starts a new transaction.
+ */
+ void begin();
+
+ /**
+ * Commits a transaction that was previously started thereby making its changes permanent
+ * and externally visible.
+ * @throws TransactionException if transaction fails to commit.
+ */
+ void commit();
+
+ /**
+ * Rolls back the current transaction, discarding all its changes.
+ */
+ void rollback();
+
+ /**
+ * Creates a new transactional map.
+ * @param mapName name of the transactional map.
+ * @param serializer serializer to use for encoding/decoding keys and vaulues.
+ * @return new Transactional Map.
+ */
+ <K, V> TransactionalMap<K, V> createTransactionalMap(String mapName, Serializer serializer);
+}
\ No newline at end of file
diff --git a/core/api/src/main/java/org/onosproject/store/service/TransactionException.java b/core/api/src/main/java/org/onosproject/store/service/TransactionException.java
new file mode 100644
index 0000000..8261fbd
--- /dev/null
+++ b/core/api/src/main/java/org/onosproject/store/service/TransactionException.java
@@ -0,0 +1,48 @@
+/*
+ * 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.service;
+
+/**
+ * Top level exception for Transaction failures.
+ */
+@SuppressWarnings("serial")
+public class TransactionException extends RuntimeException {
+ public TransactionException() {
+ }
+
+ public TransactionException(Throwable t) {
+ super(t);
+ }
+
+ /**
+ * Transaction timeout.
+ */
+ public static class Timeout extends TransactionException {
+ }
+
+ /**
+ * Transaction interrupted.
+ */
+ public static class Interrupted extends TransactionException {
+ }
+
+ /**
+ * Transaction failure due to optimistic concurrency failure.
+ */
+ public static class OptimisticConcurrencyFailure extends TransactionException {
+ }
+}
\ No newline at end of file
diff --git a/core/api/src/main/java/org/onosproject/store/service/TransactionalMap.java b/core/api/src/main/java/org/onosproject/store/service/TransactionalMap.java
new file mode 100644
index 0000000..c59600c
--- /dev/null
+++ b/core/api/src/main/java/org/onosproject/store/service/TransactionalMap.java
@@ -0,0 +1,166 @@
+/*
+ * 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.service;
+
+import java.util.Collection;
+import java.util.Set;
+import java.util.Map.Entry;
+
+/**
+ * Transactional Map data structure.
+ * <p>
+ * A TransactionalMap is created by invoking {@link TransactionContext#createTransactionalMap createTransactionalMap}
+ * method. All operations performed on this map with in a transaction boundary are invisible externally
+ * until the point when the transaction commits. A commit usually succeeds in the absence of conflicts.
+ *
+ * @param <K> type of key.
+ * @param <V> type of value.
+ */
+public interface TransactionalMap<K, V> {
+
+ /**
+ * Returns the number of entries in the map.
+ *
+ * @return map size.
+ */
+ int size();
+
+ /**
+ * Returns true if the map is empty.
+ *
+ * @return true if map has no entries, false otherwise.
+ */
+ boolean isEmpty();
+
+ /**
+ * Returns true if this map contains a mapping for the specified key.
+ *
+ * @param key key
+ * @return true if map contains key, false otherwise.
+ */
+ boolean containsKey(K key);
+
+ /**
+ * Returns true if this map contains the specified value.
+ *
+ * @param value value
+ * @return true if map contains value, false otherwise.
+ */
+ boolean containsValue(V value);
+
+ /**
+ * Returns the value to which the specified key is mapped, or null if this
+ * map contains no mapping for the key.
+ *
+ * @param key the key whose associated value is to be returned
+ * @return the value to which the specified key is mapped, or null if
+ * this map contains no mapping for the key
+ */
+ V get(K key);
+
+ /**
+ * Associates the specified value with the specified key in this map (optional operation).
+ * If the map previously contained a mapping for the key, the old value is replaced by the
+ * specified value.
+ *
+ * @param key key with which the specified value is to be associated
+ * @param value value to be associated with the specified key
+ * @return the previous value associated with key, or null if there was
+ * no mapping for key.
+ */
+ V put(K key, V value);
+
+ /**
+ * Removes the mapping for a key from this map if it is present (optional operation).
+ *
+ * @param key key whose value is to be removed from the map
+ * @return the value to which this map previously associated the key,
+ * or null if the map contained no mapping for the key.
+ */
+ V remove(K key);
+
+ /**
+ * Removes all of the mappings from this map (optional operation).
+ * The map will be empty after this call returns.
+ */
+ void clear();
+
+ /**
+ * Returns a Set view of the keys contained in this map.
+ * This method differs from the behavior of java.util.Map.keySet() in that
+ * what is returned is a unmodifiable snapshot view of the keys in the ConsistentMap.
+ * Attempts to modify the returned set, whether direct or via its iterator,
+ * result in an UnsupportedOperationException.
+ *
+ * @return a set of the keys contained in this map
+ */
+ Set<K> keySet();
+
+ /**
+ * Returns the collection of values contained in this map.
+ * This method differs from the behavior of java.util.Map.values() in that
+ * what is returned is a unmodifiable snapshot view of the values in the ConsistentMap.
+ * Attempts to modify the returned collection, whether direct or via its iterator,
+ * result in an UnsupportedOperationException.
+ *
+ * @return a collection of the values contained in this map
+ */
+ Collection<V> values();
+
+ /**
+ * Returns the set of entries contained in this map.
+ * This method differs from the behavior of java.util.Map.entrySet() in that
+ * what is returned is a unmodifiable snapshot view of the entries in the ConsistentMap.
+ * Attempts to modify the returned set, whether direct or via its iterator,
+ * result in an UnsupportedOperationException.
+ *
+ * @return set of entries contained in this map.
+ */
+ Set<Entry<K, V>> entrySet();
+
+ /**
+ * If the specified key is not already associated with a value
+ * associates it with the given value and returns null, else returns the current value.
+ *
+ * @param key key with which the specified value is to be associated
+ * @param value value to be associated with the specified key
+ * @return the previous value associated with the specified key or null
+ * if key does not already mapped to a value.
+ */
+ V putIfAbsent(K key, V value);
+
+ /**
+ * Removes the entry for the specified key only if it is currently
+ * mapped to the specified value.
+ *
+ * @param key key with which the specified value is associated
+ * @param value value expected to be associated with the specified key
+ * @return true if the value was removed
+ */
+ boolean remove(K key, V value);
+
+ /**
+ * Replaces the entry for the specified key only if currently mapped
+ * to the specified value.
+ *
+ * @param key key with which the specified value is associated
+ * @param oldValue value expected to be associated with the specified key
+ * @param newValue value to be associated with the specified key
+ * @return true if the value was replaced
+ */
+ boolean replace(K key, V oldValue, V newValue);
+}
\ No newline at end of file