Misc improvements. Primarily Javadoc.
Change-Id: I083bbf559d53fa25f79d4e1e53eb15c6b96290f2
diff --git a/core/api/src/main/java/org/onosproject/store/service/AtomicCounter.java b/core/api/src/main/java/org/onosproject/store/service/AtomicCounter.java
index 1b71b5a..f620e08 100644
--- a/core/api/src/main/java/org/onosproject/store/service/AtomicCounter.java
+++ b/core/api/src/main/java/org/onosproject/store/service/AtomicCounter.java
@@ -16,7 +16,7 @@
package org.onosproject.store.service;
/**
- * An atomic counter dispenses monotonically increasing values.
+ * Distributed version of java.util.concurrent.atomic.AtomicLong.
*/
public interface AtomicCounter {
diff --git a/core/api/src/main/java/org/onosproject/store/service/EventuallyConsistentMapEvent.java b/core/api/src/main/java/org/onosproject/store/service/EventuallyConsistentMapEvent.java
index 8f63325..f4ba859 100644
--- a/core/api/src/main/java/org/onosproject/store/service/EventuallyConsistentMapEvent.java
+++ b/core/api/src/main/java/org/onosproject/store/service/EventuallyConsistentMapEvent.java
@@ -20,15 +20,23 @@
import java.util.Objects;
/**
- * Event object signalling that the map was modified.
+ * Representation of a EventuallyConsistentMap update notification.
*/
public class EventuallyConsistentMapEvent<K, V> {
public enum Type {
+ /**
+ * Entry added to map or existing entry updated.
+ */
PUT,
+
+ /**
+ * Entry removed from map.
+ */
REMOVE
}
+ private final String name;
private final Type type;
private final K key;
private final V value;
@@ -36,17 +44,28 @@
/**
* Creates a new event object.
*
+ * @param name map name
* @param type the type of the event
* @param key the key the event concerns
- * @param value the value related to the key, or null for remove events
+ * @param value the value mapped to the key
*/
- public EventuallyConsistentMapEvent(Type type, K key, V value) {
+ public EventuallyConsistentMapEvent(String name, Type type, K key, V value) {
+ this.name = name;
this.type = type;
this.key = key;
this.value = value;
}
/**
+ * Returns the map name.
+ *
+ * @return name of map
+ */
+ public String name() {
+ return name;
+ }
+
+ /**
* Returns the type of the event.
*
* @return the type of the event
@@ -65,9 +84,11 @@
}
/**
- * Returns the value associated with this event.
+ * Returns the value associated with this event. If type is REMOVE,
+ * this is the value that was removed. If type is PUT, this is
+ * the new value.
*
- * @return the value, or null if the event was REMOVE
+ * @return the value
*/
public V value() {
return value;
diff --git a/core/api/src/main/java/org/onosproject/store/service/EventuallyConsistentMapListener.java b/core/api/src/main/java/org/onosproject/store/service/EventuallyConsistentMapListener.java
index 1f6a5e0..b2399a4 100644
--- a/core/api/src/main/java/org/onosproject/store/service/EventuallyConsistentMapListener.java
+++ b/core/api/src/main/java/org/onosproject/store/service/EventuallyConsistentMapListener.java
@@ -16,8 +16,7 @@
package org.onosproject.store.service;
/**
- * Listener interested in receiving modification events for an
- * EventuallyConsistentMap.
+ * Listener to be notified about updates to a EventuallyConsistentMap.
*/
public interface EventuallyConsistentMapListener<K, V> {
diff --git a/core/api/src/main/java/org/onosproject/store/service/LogicalClockService.java b/core/api/src/main/java/org/onosproject/store/service/LogicalClockService.java
index 0114b02..7592b12 100644
--- a/core/api/src/main/java/org/onosproject/store/service/LogicalClockService.java
+++ b/core/api/src/main/java/org/onosproject/store/service/LogicalClockService.java
@@ -20,7 +20,7 @@
/**
* Service that issues logical timestamps.
* <p>
- * The logical timestamps are useful for establishing a total ordering of
+ * Logical timestamps are useful for establishing a total ordering of
* arbitrary cluster wide events without relying on a fully synchronized
* system clock (wall clock)
*/
diff --git a/core/api/src/main/java/org/onosproject/store/service/MapEvent.java b/core/api/src/main/java/org/onosproject/store/service/MapEvent.java
index bb45572..6e67135 100644
--- a/core/api/src/main/java/org/onosproject/store/service/MapEvent.java
+++ b/core/api/src/main/java/org/onosproject/store/service/MapEvent.java
@@ -56,9 +56,9 @@
* Creates a new event object.
*
* @param name map name
- * @param type the type of the event
- * @param key the key the event concerns
- * @param value the value related to the key, or null for remove events
+ * @param type type of event
+ * @param key key the event concerns
+ * @param value value key is mapped to
*/
public MapEvent(String name, Type type, K key, Versioned<V> value) {
this.name = name;
@@ -79,7 +79,7 @@
/**
* Returns the type of the event.
*
- * @return the type of the event
+ * @return the type of event
*/
public Type type() {
return type;
@@ -120,7 +120,7 @@
@Override
public int hashCode() {
- return Objects.hash(type, key, value);
+ return Objects.hash(name, type, key, value);
}
@Override
diff --git a/core/api/src/main/java/org/onosproject/store/service/MapEventListener.java b/core/api/src/main/java/org/onosproject/store/service/MapEventListener.java
index 0b36b68..359f465 100644
--- a/core/api/src/main/java/org/onosproject/store/service/MapEventListener.java
+++ b/core/api/src/main/java/org/onosproject/store/service/MapEventListener.java
@@ -16,7 +16,7 @@
package org.onosproject.store.service;
/**
- * Listener to be notified about updates to a ConsitentMap.
+ * Listener to be notified about updates to a ConsistentMap.
*/
public interface MapEventListener<K, V> {
/**
diff --git a/core/api/src/main/java/org/onosproject/store/service/SetEvent.java b/core/api/src/main/java/org/onosproject/store/service/SetEvent.java
index 6d855c0..e294bae 100644
--- a/core/api/src/main/java/org/onosproject/store/service/SetEvent.java
+++ b/core/api/src/main/java/org/onosproject/store/service/SetEvent.java
@@ -22,7 +22,7 @@
/**
* Representation of a DistributedSet update notification.
*
- * @param <E> element type
+ * @param <E> set element type
*/
public class SetEvent<E> {
@@ -49,8 +49,8 @@
* Creates a new event object.
*
* @param name set name
- * @param type the type of the event
- * @param entry the entry the event concerns
+ * @param type type of the event
+ * @param entry entry the event concerns
*/
public SetEvent(String name, Type type, E entry) {
this.name = name;
@@ -70,7 +70,7 @@
/**
* Returns the type of the event.
*
- * @return the type of the event
+ * @return type of the event
*/
public Type type() {
return type;
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 9ba8780..f6b411d 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
@@ -13,19 +13,15 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-
package org.onosproject.store.service;
-
/**
* Storage service.
* <p>
- * This service provides operations for creating key-value stores.
- * One can chose to create key-value stores with varying properties such
- * as strongly consistent vs eventually consistent, durable vs volatile.
+ * This service provides builders for various distributed primitives.
* <p>
- * Various store implementations should leverage the data structures provided
- * by this service
+ * It is expected that services and applications will leverage the primitives indirectly provided by
+ * this service for their distributed state management and coordination.
*/
public interface StorageService {
@@ -48,7 +44,7 @@
<K, V> ConsistentMapBuilder<K, V> consistentMapBuilder();
/**
- * Creates a new distributed set builder.
+ * Creates a new DistributedSetBuilder.
*
* @param <E> set element type
* @return builder for an distributed set
@@ -56,7 +52,7 @@
<E> DistributedSetBuilder<E> setBuilder();
/**
- * Creates a new distributed queue builder.
+ * Creates a new DistributedQueueBuilder.
*
* @param <E> queue entry type
* @return builder for an distributed queue
diff --git a/core/store/dist/src/main/java/org/onosproject/store/ecmap/EventuallyConsistentMapImpl.java b/core/store/dist/src/main/java/org/onosproject/store/ecmap/EventuallyConsistentMapImpl.java
index d1f4f2a..2de8947 100644
--- a/core/store/dist/src/main/java/org/onosproject/store/ecmap/EventuallyConsistentMapImpl.java
+++ b/core/store/dist/src/main/java/org/onosproject/store/ecmap/EventuallyConsistentMapImpl.java
@@ -310,7 +310,7 @@
MapValue<V> newValue = new MapValue<>(value, timestampProvider.apply(key, value));
if (putInternal(key, newValue)) {
notifyPeers(new UpdateEntry<>(key, newValue), peerUpdateFunction.apply(key, value));
- notifyListeners(new EventuallyConsistentMapEvent<>(PUT, key, value));
+ notifyListeners(new EventuallyConsistentMapEvent<>(mapName, PUT, key, value));
}
}
@@ -335,7 +335,7 @@
if (previousValue != null) {
notifyPeers(new UpdateEntry<>(key, tombstone), peerUpdateFunction.apply(key, previousValue.get()));
if (previousValue.isAlive()) {
- notifyListeners(new EventuallyConsistentMapEvent<>(REMOVE, key, previousValue.get()));
+ notifyListeners(new EventuallyConsistentMapEvent<>(mapName, REMOVE, key, previousValue.get()));
}
}
return previousValue != null ? previousValue.get() : null;
@@ -406,7 +406,7 @@
? previousValue.get() == null ? null : previousValue.get().get()
: computedValue.get();
if (value != null) {
- notifyListeners(new EventuallyConsistentMapEvent<>(updateType, key, value));
+ notifyListeners(new EventuallyConsistentMapEvent<>(mapName, updateType, key, value));
}
}
return computedValue.get();
@@ -609,7 +609,7 @@
Optional.empty(),
MapValue.tombstone(remoteValueDigest.timestamp()));
if (previousValue != null && previousValue.isAlive()) {
- externalEvents.add(new EventuallyConsistentMapEvent<>(REMOVE, key, previousValue.get()));
+ externalEvents.add(new EventuallyConsistentMapEvent<>(mapName, REMOVE, key, previousValue.get()));
}
}
});
@@ -626,10 +626,10 @@
if (value.isTombstone()) {
MapValue<V> previousValue = removeInternal(key, Optional.empty(), value);
if (previousValue != null && previousValue.isAlive()) {
- notifyListeners(new EventuallyConsistentMapEvent<>(REMOVE, key, previousValue.get()));
+ notifyListeners(new EventuallyConsistentMapEvent<>(mapName, REMOVE, key, previousValue.get()));
}
} else if (putInternal(key, value)) {
- notifyListeners(new EventuallyConsistentMapEvent<>(PUT, key, value.get()));
+ notifyListeners(new EventuallyConsistentMapEvent<>(mapName, PUT, key, value.get()));
}
});
}
diff --git a/core/store/dist/src/test/java/org/onosproject/store/ecmap/EventuallyConsistentMapImplTest.java b/core/store/dist/src/test/java/org/onosproject/store/ecmap/EventuallyConsistentMapImplTest.java
index c6ad750..b5696a2 100644
--- a/core/store/dist/src/test/java/org/onosproject/store/ecmap/EventuallyConsistentMapImplTest.java
+++ b/core/store/dist/src/test/java/org/onosproject/store/ecmap/EventuallyConsistentMapImplTest.java
@@ -274,9 +274,9 @@
EventuallyConsistentMapListener<String, String> listener
= getListener();
listener.event(new EventuallyConsistentMapEvent<>(
- EventuallyConsistentMapEvent.Type.PUT, KEY1, VALUE1));
+ MAP_NAME, EventuallyConsistentMapEvent.Type.PUT, KEY1, VALUE1));
listener.event(new EventuallyConsistentMapEvent<>(
- EventuallyConsistentMapEvent.Type.PUT, KEY1, VALUE2));
+ MAP_NAME, EventuallyConsistentMapEvent.Type.PUT, KEY1, VALUE2));
replay(listener);
ecMap.addListener(listener);
@@ -325,11 +325,11 @@
EventuallyConsistentMapListener<String, String> listener
= getListener();
listener.event(new EventuallyConsistentMapEvent<>(
- EventuallyConsistentMapEvent.Type.REMOVE, KEY1, VALUE1));
+ MAP_NAME, EventuallyConsistentMapEvent.Type.REMOVE, KEY1, VALUE1));
listener.event(new EventuallyConsistentMapEvent<>(
- EventuallyConsistentMapEvent.Type.PUT, KEY1, VALUE1));
+ MAP_NAME, EventuallyConsistentMapEvent.Type.PUT, KEY1, VALUE1));
listener.event(new EventuallyConsistentMapEvent<>(
- EventuallyConsistentMapEvent.Type.PUT, KEY2, VALUE2));
+ MAP_NAME, EventuallyConsistentMapEvent.Type.PUT, KEY2, VALUE2));
replay(listener);
ecMap.addListener(listener);
@@ -388,11 +388,11 @@
EventuallyConsistentMapListener<String, String> listener
= getListener();
listener.event(new EventuallyConsistentMapEvent<>(
- EventuallyConsistentMapEvent.Type.PUT, KEY1, VALUE1));
+ MAP_NAME, EventuallyConsistentMapEvent.Type.PUT, KEY1, VALUE1));
listener.event(new EventuallyConsistentMapEvent<>(
- EventuallyConsistentMapEvent.Type.REMOVE, KEY1, VALUE1));
+ MAP_NAME, EventuallyConsistentMapEvent.Type.REMOVE, KEY1, VALUE1));
listener.event(new EventuallyConsistentMapEvent<>(
- EventuallyConsistentMapEvent.Type.PUT, KEY2, VALUE2));
+ MAP_NAME, EventuallyConsistentMapEvent.Type.PUT, KEY2, VALUE2));
replay(listener);
ecMap.addListener(listener);
@@ -457,9 +457,9 @@
EventuallyConsistentMapListener<String, String> listener
= getListener();
listener.event(new EventuallyConsistentMapEvent<>(
- EventuallyConsistentMapEvent.Type.PUT, KEY1, VALUE1));
+ MAP_NAME, EventuallyConsistentMapEvent.Type.PUT, KEY1, VALUE1));
listener.event(new EventuallyConsistentMapEvent<>(
- EventuallyConsistentMapEvent.Type.PUT, KEY2, VALUE2));
+ MAP_NAME, EventuallyConsistentMapEvent.Type.PUT, KEY2, VALUE2));
replay(listener);
ecMap.addListener(listener);
@@ -485,9 +485,9 @@
EventuallyConsistentMapListener<String, String> listener
= getListener();
listener.event(new EventuallyConsistentMapEvent<>(
- EventuallyConsistentMapEvent.Type.REMOVE, KEY1, VALUE1));
+ MAP_NAME, EventuallyConsistentMapEvent.Type.REMOVE, KEY1, VALUE1));
listener.event(new EventuallyConsistentMapEvent<>(
- EventuallyConsistentMapEvent.Type.REMOVE, KEY2, VALUE2));
+ MAP_NAME, EventuallyConsistentMapEvent.Type.REMOVE, KEY2, VALUE2));
replay(listener);
// clear() on an empty map is a no-op - no messages will be sent