Misc improvements. Primarily Javadoc.

Change-Id: I083bbf559d53fa25f79d4e1e53eb15c6b96290f2

@@ -16,7 +16,7 @@
 package org.onosproject.store.service;
 package org.onosproject.store.service;
 
 
 /**
 /**
- * An atomic counter dispenses monotonically increasing values.
+ * Distributed version of java.util.concurrent.atomic.AtomicLong.
  */
  */
 public interface AtomicCounter {
 public interface AtomicCounter {
 
 

@@ -20,15 +20,23 @@ import com.google.common.base.MoreObjects;
 import java.util.Objects;
 import java.util.Objects;
 
 
 /**
 /**
- * Event object signalling that the map was modified.
+ * Representation of a EventuallyConsistentMap update notification.
  */
  */
 public class EventuallyConsistentMapEvent<K, V> {
 public class EventuallyConsistentMapEvent<K, V> {
 
 
     public enum Type {
     public enum Type {
+        /**
+         * Entry added to map or existing entry updated.
+         */
         PUT,
         PUT,
+
+        /**
+         * Entry removed from map.
+         */
         REMOVE
         REMOVE
     }
     }
 
 
+    private final String name;
     private final Type type;
     private final Type type;
     private final K key;
     private final K key;
     private final V value;
     private final V value;
@@ -36,17 +44,28 @@ public class EventuallyConsistentMapEvent<K, V> {
     /**
     /**
      * Creates a new event object.
      * Creates a new event object.
      *
      *
+     * @param name map name
      * @param type the type of the event
      * @param type the type of the event
      * @param key the key the event concerns
      * @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.type = type;
         this.key = key;
         this.key = key;
         this.value = value;
         this.value = value;
     }
     }
 
 
     /**
     /**
+     * Returns the map name.
+     *
+     * @return name of map
+     */
+    public String name() {
+        return name;
+    }
+
+    /**
      * Returns the type of the event.
      * Returns the type of the event.
      *
      *
      * @return the type of the event
      * @return the type of the event
@@ -65,9 +84,11 @@ public class EventuallyConsistentMapEvent<K, V> {
     }
     }
 
 
     /**
     /**
-     * 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() {
     public V value() {
         return value;
         return value;

@@ -16,8 +16,7 @@
 package org.onosproject.store.service;
 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> {
 public interface EventuallyConsistentMapListener<K, V> {
 
 

@@ -20,7 +20,7 @@ import org.onosproject.store.Timestamp;
 /**
 /**
  * Service that issues logical timestamps.
  * Service that issues logical timestamps.
  * <p>
  * <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
  * arbitrary cluster wide events without relying on a fully synchronized
  * system clock (wall clock)
  * system clock (wall clock)
  */
  */

@@ -56,9 +56,9 @@ public class MapEvent<K, V> {
      * Creates a new event object.
      * Creates a new event object.
      *
      *
      * @param name map name
      * @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) {
     public MapEvent(String name, Type type, K key, Versioned<V> value) {
         this.name = name;
         this.name = name;
@@ -79,7 +79,7 @@ public class MapEvent<K, V> {
     /**
     /**
      * Returns the type of the event.
      * Returns the type of the event.
      *
      *
-     * @return the type of the event
+     * @return the type of event
      */
      */
     public Type type() {
     public Type type() {
         return type;
         return type;
@@ -120,7 +120,7 @@ public class MapEvent<K, V> {
 
 
     @Override
     @Override
     public int hashCode() {
     public int hashCode() {
-        return Objects.hash(type, key, value);
+        return Objects.hash(name, type, key, value);
     }
     }
 
 
     @Override
     @Override

@@ -16,7 +16,7 @@
 package org.onosproject.store.service;
 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> {
 public interface MapEventListener<K, V> {
     /**
     /**

@@ -22,7 +22,7 @@ import com.google.common.base.MoreObjects;
 /**
 /**
  * Representation of a DistributedSet update notification.
  * Representation of a DistributedSet update notification.
  *
  *
- * @param <E> element type
+ * @param <E> set element type
  */
  */
 public class SetEvent<E> {
 public class SetEvent<E> {
 
 
@@ -49,8 +49,8 @@ public class SetEvent<E> {
      * Creates a new event object.
      * Creates a new event object.
      *
      *
      * @param name set name
      * @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) {
     public SetEvent(String name, Type type, E entry) {
         this.name = name;
         this.name = name;
@@ -70,7 +70,7 @@ public class SetEvent<E> {
     /**
     /**
      * Returns the type of the event.
      * Returns the type of the event.
      *
      *
-     * @return the type of the event
+     * @return type of the event
      */
      */
     public Type type() {
     public Type type() {
         return type;
         return type;

@@ -13,19 +13,15 @@
  * See the License for the specific language governing permissions and
  * See the License for the specific language governing permissions and
  * limitations under the License.
  * limitations under the License.
  */
  */
-
 package org.onosproject.store.service;
 package org.onosproject.store.service;
 
 
-
 /**
 /**
  * Storage service.
  * Storage service.
  * <p>
  * <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>
  * <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 {
 public interface StorageService {
 
 
@@ -48,7 +44,7 @@ public interface StorageService {
     <K, V> ConsistentMapBuilder<K, V> consistentMapBuilder();
     <K, V> ConsistentMapBuilder<K, V> consistentMapBuilder();
 
 
     /**
     /**
-     * Creates a new distributed set builder.
+     * Creates a new DistributedSetBuilder.
      *
      *
      * @param <E> set element type
      * @param <E> set element type
      * @return builder for an distributed set
      * @return builder for an distributed set
@@ -56,7 +52,7 @@ public interface StorageService {
     <E> DistributedSetBuilder<E> setBuilder();
     <E> DistributedSetBuilder<E> setBuilder();
 
 
     /**
     /**
-     * Creates a new distributed queue builder.
+     * Creates a new DistributedQueueBuilder.
      *
      *
      * @param <E> queue entry type
      * @param <E> queue entry type
      * @return builder for an distributed queue
      * @return builder for an distributed queue

@@ -310,7 +310,7 @@ public class EventuallyConsistentMapImpl<K, V>
         MapValue<V> newValue = new MapValue<>(value, timestampProvider.apply(key, value));
         MapValue<V> newValue = new MapValue<>(value, timestampProvider.apply(key, value));
         if (putInternal(key, newValue)) {
         if (putInternal(key, newValue)) {
             notifyPeers(new UpdateEntry<>(key, newValue), peerUpdateFunction.apply(key, value));
             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 @@ public class EventuallyConsistentMapImpl<K, V>
         if (previousValue != null) {
         if (previousValue != null) {
             notifyPeers(new UpdateEntry<>(key, tombstone), peerUpdateFunction.apply(key, previousValue.get()));
             notifyPeers(new UpdateEntry<>(key, tombstone), peerUpdateFunction.apply(key, previousValue.get()));
             if (previousValue.isAlive()) {
             if (previousValue.isAlive()) {
-                notifyListeners(new EventuallyConsistentMapEvent<>(REMOVE, key, previousValue.get()));
+                notifyListeners(new EventuallyConsistentMapEvent<>(mapName, REMOVE, key, previousValue.get()));
             }
             }
         }
         }
         return previousValue != null ? previousValue.get() : null;
         return previousValue != null ? previousValue.get() : null;
@@ -406,7 +406,7 @@ public class EventuallyConsistentMapImpl<K, V>
                     ? previousValue.get() == null ? null : previousValue.get().get()
                     ? previousValue.get() == null ? null : previousValue.get().get()
                     : computedValue.get();
                     : computedValue.get();
             if (value != null) {
             if (value != null) {
-                notifyListeners(new EventuallyConsistentMapEvent<>(updateType, key, value));
+                notifyListeners(new EventuallyConsistentMapEvent<>(mapName, updateType, key, value));
             }
             }
         }
         }
         return computedValue.get();
         return computedValue.get();
@@ -609,7 +609,7 @@ public class EventuallyConsistentMapImpl<K, V>
                                                            Optional.empty(),
                                                            Optional.empty(),
                                                            MapValue.tombstone(remoteValueDigest.timestamp()));
                                                            MapValue.tombstone(remoteValueDigest.timestamp()));
                 if (previousValue != null && previousValue.isAlive()) {
                 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 @@ public class EventuallyConsistentMapImpl<K, V>
             if (value.isTombstone()) {
             if (value.isTombstone()) {
                 MapValue<V> previousValue = removeInternal(key, Optional.empty(), value);
                 MapValue<V> previousValue = removeInternal(key, Optional.empty(), value);
                 if (previousValue != null && previousValue.isAlive()) {
                 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)) {
             } else if (putInternal(key, value)) {
-                notifyListeners(new EventuallyConsistentMapEvent<>(PUT, key, value.get()));
+                notifyListeners(new EventuallyConsistentMapEvent<>(mapName, PUT, key, value.get()));
             }
             }
         });
         });
     }
     }

@@ -274,9 +274,9 @@ public class EventuallyConsistentMapImplTest {
         EventuallyConsistentMapListener<String, String> listener
         EventuallyConsistentMapListener<String, String> listener
                 = getListener();
                 = getListener();
         listener.event(new EventuallyConsistentMapEvent<>(
         listener.event(new EventuallyConsistentMapEvent<>(
-                EventuallyConsistentMapEvent.Type.PUT, KEY1, VALUE1));
+                MAP_NAME, EventuallyConsistentMapEvent.Type.PUT, KEY1, VALUE1));
         listener.event(new EventuallyConsistentMapEvent<>(
         listener.event(new EventuallyConsistentMapEvent<>(
-                EventuallyConsistentMapEvent.Type.PUT, KEY1, VALUE2));
+                MAP_NAME, EventuallyConsistentMapEvent.Type.PUT, KEY1, VALUE2));
         replay(listener);
         replay(listener);
 
 
         ecMap.addListener(listener);
         ecMap.addListener(listener);
@@ -325,11 +325,11 @@ public class EventuallyConsistentMapImplTest {
         EventuallyConsistentMapListener<String, String> listener
         EventuallyConsistentMapListener<String, String> listener
                 = getListener();
                 = getListener();
         listener.event(new EventuallyConsistentMapEvent<>(
         listener.event(new EventuallyConsistentMapEvent<>(
-                EventuallyConsistentMapEvent.Type.REMOVE, KEY1, VALUE1));
+                MAP_NAME, EventuallyConsistentMapEvent.Type.REMOVE, KEY1, VALUE1));
         listener.event(new EventuallyConsistentMapEvent<>(
         listener.event(new EventuallyConsistentMapEvent<>(
-                EventuallyConsistentMapEvent.Type.PUT, KEY1, VALUE1));
+                MAP_NAME, EventuallyConsistentMapEvent.Type.PUT, KEY1, VALUE1));
         listener.event(new EventuallyConsistentMapEvent<>(
         listener.event(new EventuallyConsistentMapEvent<>(
-                EventuallyConsistentMapEvent.Type.PUT, KEY2, VALUE2));
+                MAP_NAME, EventuallyConsistentMapEvent.Type.PUT, KEY2, VALUE2));
         replay(listener);
         replay(listener);
 
 
         ecMap.addListener(listener);
         ecMap.addListener(listener);
@@ -388,11 +388,11 @@ public class EventuallyConsistentMapImplTest {
         EventuallyConsistentMapListener<String, String> listener
         EventuallyConsistentMapListener<String, String> listener
                 = getListener();
                 = getListener();
         listener.event(new EventuallyConsistentMapEvent<>(
         listener.event(new EventuallyConsistentMapEvent<>(
-                EventuallyConsistentMapEvent.Type.PUT, KEY1, VALUE1));
+                MAP_NAME, EventuallyConsistentMapEvent.Type.PUT, KEY1, VALUE1));
         listener.event(new EventuallyConsistentMapEvent<>(
         listener.event(new EventuallyConsistentMapEvent<>(
-                EventuallyConsistentMapEvent.Type.REMOVE, KEY1, VALUE1));
+                MAP_NAME, EventuallyConsistentMapEvent.Type.REMOVE, KEY1, VALUE1));
         listener.event(new EventuallyConsistentMapEvent<>(
         listener.event(new EventuallyConsistentMapEvent<>(
-                EventuallyConsistentMapEvent.Type.PUT, KEY2, VALUE2));
+                MAP_NAME, EventuallyConsistentMapEvent.Type.PUT, KEY2, VALUE2));
         replay(listener);
         replay(listener);
 
 
         ecMap.addListener(listener);
         ecMap.addListener(listener);
@@ -457,9 +457,9 @@ public class EventuallyConsistentMapImplTest {
         EventuallyConsistentMapListener<String, String> listener
         EventuallyConsistentMapListener<String, String> listener
                 = getListener();
                 = getListener();
         listener.event(new EventuallyConsistentMapEvent<>(
         listener.event(new EventuallyConsistentMapEvent<>(
-                EventuallyConsistentMapEvent.Type.PUT, KEY1, VALUE1));
+                MAP_NAME, EventuallyConsistentMapEvent.Type.PUT, KEY1, VALUE1));
         listener.event(new EventuallyConsistentMapEvent<>(
         listener.event(new EventuallyConsistentMapEvent<>(
-                EventuallyConsistentMapEvent.Type.PUT, KEY2, VALUE2));
+                MAP_NAME, EventuallyConsistentMapEvent.Type.PUT, KEY2, VALUE2));
         replay(listener);
         replay(listener);
 
 
         ecMap.addListener(listener);
         ecMap.addListener(listener);
@@ -485,9 +485,9 @@ public class EventuallyConsistentMapImplTest {
         EventuallyConsistentMapListener<String, String> listener
         EventuallyConsistentMapListener<String, String> listener
                 = getListener();
                 = getListener();
         listener.event(new EventuallyConsistentMapEvent<>(
         listener.event(new EventuallyConsistentMapEvent<>(
-                EventuallyConsistentMapEvent.Type.REMOVE, KEY1, VALUE1));
+                MAP_NAME, EventuallyConsistentMapEvent.Type.REMOVE, KEY1, VALUE1));
         listener.event(new EventuallyConsistentMapEvent<>(
         listener.event(new EventuallyConsistentMapEvent<>(
-                EventuallyConsistentMapEvent.Type.REMOVE, KEY2, VALUE2));
+                MAP_NAME, EventuallyConsistentMapEvent.Type.REMOVE, KEY2, VALUE2));
         replay(listener);
         replay(listener);
 
 
         // clear() on an empty map is a no-op - no messages will be sent
         // clear() on an empty map is a no-op - no messages will be sent