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