Added an async version for AtomicValue and misc javadoc improvements
Change-Id: Idc401964a726d221c01ecda0cc42c4a92551113f
diff --git a/core/api/src/main/java/org/onosproject/store/service/AsyncAtomicValue.java b/core/api/src/main/java/org/onosproject/store/service/AsyncAtomicValue.java
new file mode 100644
index 0000000..531721a
--- /dev/null
+++ b/core/api/src/main/java/org/onosproject/store/service/AsyncAtomicValue.java
@@ -0,0 +1,78 @@
+/*
+ * 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.concurrent.CompletableFuture;
+
+/**
+ * Distributed version of java.util.concurrent.atomic.AtomicReference.
+ * <p>
+ * All methods of this interface return a {@link CompletableFuture future} immediately
+ * after a successful invocation. The operation itself is executed asynchronous and
+ * the returned future will be {@link CompletableFuture#complete completed} when the
+ * operation finishes.
+ *
+ * @param <V> value type
+ */
+public interface AsyncAtomicValue<V> {
+
+ /**
+ * Atomically sets the value to the given updated value if the current value is equal to the expected value.
+ * <p>
+ * IMPORTANT: Equality is based on the equality of the serialized {code byte[]} representations.
+ * <p>
+ * @param expect the expected value
+ * @param update the new value
+ * @return CompletableFuture that will be completed with {@code true} if update was successful. Otherwise future
+ * will be completed with a value of {@code false}
+ */
+ CompletableFuture<Boolean> compareAndSet(V expect, V update);
+
+ /**
+ * Gets the current value.
+ * @return CompletableFuture that will be completed with the value
+ */
+ CompletableFuture<V> get();
+
+ /**
+ * Atomically sets to the given value and returns the old value.
+ * @param value the new value
+ * @return CompletableFuture that will be completed with the previous value
+ */
+ CompletableFuture<V> getAndSet(V value);
+
+ /**
+ * Sets to the given value.
+ * @param value value to set
+ * @return CompletableFuture that will be completed when the operation finishes
+ */
+ CompletableFuture<Void> set(V value);
+
+ /**
+ * Registers the specified listener to be notified whenever the atomic value is updated.
+ * @param listener listener to notify about events
+ * @return CompletableFuture that will be completed when the operation finishes
+ */
+ CompletableFuture<Void> addListener(AtomicValueEventListener<V> listener);
+
+ /**
+ * Unregisters the specified listener such that it will no longer
+ * receive atomic value update notifications.
+ * @param listener listener to unregister
+ * @return CompletableFuture that will be completed when the operation finishes
+ */
+ CompletableFuture<Void> removeListener(AtomicValueEventListener<V> listener);
+}
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 5e54eec..c7b6eac 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
@@ -17,6 +17,7 @@
package org.onosproject.store.service;
import java.util.Collection;
+import java.util.Objects;
import java.util.Map.Entry;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
@@ -42,7 +43,11 @@
* </p><p>
* This map does not allow null values. All methods can throw a ConsistentMapException
* (which extends RuntimeException) to indicate failures.
- *
+ * <p>
+ * All methods of this interface return a {@link CompletableFuture future} immediately
+ * after a successful invocation. The operation itself is executed asynchronous and
+ * the returned future will be {@link CompletableFuture#complete completed} when the
+ * operation finishes.
*/
public interface AsyncConsistentMap<K, V> {
@@ -58,7 +63,9 @@
*
* @return a future whose value will be true if map has no entries, false otherwise.
*/
- CompletableFuture<Boolean> isEmpty();
+ default CompletableFuture<Boolean> isEmpty() {
+ return size().thenApply(s -> s == 0);
+ }
/**
* Returns true if this map contains a mapping for the specified key.
@@ -97,8 +104,10 @@
* @return the current (existing or computed) value associated with the specified key,
* or null if the computed value is null
*/
- CompletableFuture<Versioned<V>> computeIfAbsent(K key,
- Function<? super K, ? extends V> mappingFunction);
+ default CompletableFuture<Versioned<V>> computeIfAbsent(K key,
+ Function<? super K, ? extends V> mappingFunction) {
+ return computeIf(key, Objects::isNull, (k, v) -> mappingFunction.apply(k));
+ }
/**
* If the value for the specified key is present and non-null, attempts to compute a new
@@ -110,8 +119,10 @@
* @param remappingFunction the function to compute a value
* @return the new value associated with the specified key, or null if computed value is null
*/
- CompletableFuture<Versioned<V>> computeIfPresent(K key,
- BiFunction<? super K, ? super V, ? extends V> remappingFunction);
+ default CompletableFuture<Versioned<V>> computeIfPresent(K key,
+ BiFunction<? super K, ? super V, ? extends V> remappingFunction) {
+ return computeIf(key, Objects::nonNull, remappingFunction);
+ }
/**
* Attempts to compute a mapping for the specified key and its current mapped value (or
@@ -123,8 +134,10 @@
* @param remappingFunction the function to compute a value
* @return the new value associated with the specified key, or null if computed value is null
*/
- CompletableFuture<Versioned<V>> compute(K key,
- BiFunction<? super K, ? super V, ? extends V> remappingFunction);
+ default CompletableFuture<Versioned<V>> compute(K key,
+ BiFunction<? super K, ? super V, ? extends V> remappingFunction) {
+ return computeIf(key, v -> true, remappingFunction);
+ }
/**
* If the value for the specified key satisfies a condition, attempts to compute a new
@@ -280,14 +293,16 @@
* Registers the specified listener to be notified whenever the map is updated.
*
* @param listener listener to notify about map events
+ * @return future that will be completed when the operation finishes
*/
- void addListener(MapEventListener<K, V> listener);
+ CompletableFuture<Void> addListener(MapEventListener<K, V> listener);
/**
* Unregisters the specified listener such that it will no longer
* receive map change notifications.
*
* @param listener listener to unregister
+ * @return future that will be completed when the operation finishes
*/
- void removeListener(MapEventListener<K, V> listener);
+ CompletableFuture<Void> removeListener(MapEventListener<K, V> listener);
}
diff --git a/core/api/src/main/java/org/onosproject/store/service/AtomicValueBuilder.java b/core/api/src/main/java/org/onosproject/store/service/AtomicValueBuilder.java
index 3478ce0..d5f226f 100644
--- a/core/api/src/main/java/org/onosproject/store/service/AtomicValueBuilder.java
+++ b/core/api/src/main/java/org/onosproject/store/service/AtomicValueBuilder.java
@@ -68,6 +68,15 @@
AtomicValueBuilder<V> withMeteringDisabled();
/**
+ * Builds a AsyncAtomicValue based on the configuration options
+ * supplied to this builder.
+ *
+ * @return new AsyncAtomicValue
+ * @throws java.lang.RuntimeException if a mandatory parameter is missing
+ */
+ AsyncAtomicValue<V> buildAsyncValue();
+
+ /**
* Builds a AtomicValue based on the configuration options
* supplied to this builder.
*
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 9a6d409..93abf78 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
@@ -298,4 +298,4 @@
* @return java.util.Map
*/
Map<K, V> asJavaMap();
-}
\ No newline at end of file
+}
diff --git a/core/api/src/main/java/org/onosproject/store/service/ConsistentMapBuilder.java b/core/api/src/main/java/org/onosproject/store/service/ConsistentMapBuilder.java
index 847adaf..466c8f1 100644
--- a/core/api/src/main/java/org/onosproject/store/service/ConsistentMapBuilder.java
+++ b/core/api/src/main/java/org/onosproject/store/service/ConsistentMapBuilder.java
@@ -18,7 +18,7 @@
import org.onosproject.core.ApplicationId;
/**
- * Builder for consistent maps.
+ * Builder for {@link ConsistentMap} instances.
*
* @param <K> type for map key
* @param <V> type for map value
@@ -28,19 +28,20 @@
/**
* Sets the name of the map.
* <p>
- * Each consistent map is identified by a unique map name.
+ * Each map is identified by a unique map name. Different instances with the same name are all backed by the
+ * same backend state.
* </p>
* <p>
- * Note: This is a mandatory parameter.
+ * <b>Note:</b> This is a mandatory parameter.
* </p>
*
- * @param name name of the consistent map
+ * @param name name of the map
* @return this ConsistentMapBuilder
*/
ConsistentMapBuilder<K, V> withName(String name);
/**
- * Sets the owner applicationId for the map.
+ * Sets the identifier of the application that owns this map instance.
* <p>
* Note: If {@code purgeOnUninstall} option is enabled, applicationId
* must be specified.
diff --git a/core/api/src/main/java/org/onosproject/store/service/Versioned.java b/core/api/src/main/java/org/onosproject/store/service/Versioned.java
index 89bd302..0eec3ff 100644
--- a/core/api/src/main/java/org/onosproject/store/service/Versioned.java
+++ b/core/api/src/main/java/org/onosproject/store/service/Versioned.java
@@ -111,6 +111,16 @@
return versioned == null ? defaultValue : versioned.value();
}
+ /**
+ * Returns the value of the specified Versioned object if non-null or else returns null.
+ * @param versioned versioned object
+ * @param <U> type of the versioned value
+ * @return versioned value or null if versioned object is null
+ */
+ public static <U> U valueOrNull(Versioned<U> versioned) {
+ return valueOrElse(versioned, null);
+ }
+
@Override
public int hashCode() {
return Objects.hashCode(value, version, creationTime);