Javadoc updates to DocumentTree classes

Change-Id: Id55d317de95fc6b50849de58a1d813a7cc1216e7

@@ -16,45 +16,41 @@
 
 package org.onosproject.store.service;
 
-import com.google.common.base.Preconditions;
-import com.google.common.collect.ImmutableList;
-import com.google.common.collect.Lists;
-
-import java.util.ArrayList;
 import java.util.Iterator;
 import java.util.List;
 import java.util.Objects;
 
+import com.google.common.base.Preconditions;
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.Lists;
+
 /**
- * A path class for identifying nodes within the {@code DocumentTree}.
- *
- * Note: indexing is ONE based so the root is the 1st level, to retrieve the
- * root one should query level 1.
+ * Unique key for nodes in the {@link DocumentTree}.
  */
-public class DocumentPath implements Comparable {
+public class DocumentPath implements Comparable<DocumentPath> {
 
-    private final ArrayList<String> tokens = Lists.newArrayList();
+    private final List<String> pathElements = Lists.newArrayList();
 
     /**
      * Private utility constructor for internal generation of partial paths only.
      *
-     * @param path
+     * @param pathElements list of path elements
      */
-    private DocumentPath(List<String> path) {
-        Preconditions.checkNotNull(path);
-        this.tokens.addAll(path);
+    private DocumentPath(List<String> pathElements) {
+        Preconditions.checkNotNull(pathElements);
+        this.pathElements.addAll(pathElements);
     }
 
     /**
-     * Constructor to generate new {@DocumentPath}, new paths must contain at
-     * least one name and string names may NOT contain any '.'s. If one field
-     * is null that field will be ignored.
+     * Constructs a {@DocumentPath}.
+     * <p>
+     * New paths must contain at least one name and string names may NOT contain any period characters.
+     * If one field is {@code null} that field will be ignored.
      *
-     * @throws IllegalDocumentNameException if both parameters are null or the string
-     * name contains an illegal character ('.')
      * @param nodeName the name of the last level of this path
-     * @param parentPath the path representing the parents leading up to this
-     *                   node, in the case of the root this should be null
+     * @param parentPath the path representing the parent leading up to this
+     *                   node, in the case of the root this should be {@code null}
+     * @throws IllegalDocumentNameException if both parameters are null or name contains an illegal character ('.')
      */
     public DocumentPath(String nodeName, DocumentPath parentPath) {
         if (nodeName.contains(".")) {
@@ -62,12 +58,12 @@ public class DocumentPath implements Comparable {
                     "Periods are not allowed in names.");
         }
         if (parentPath != null) {
-            tokens.addAll(parentPath.path());
+            pathElements.addAll(parentPath.pathElements());
         }
         if (nodeName != null) {
-            tokens.add(nodeName);
+            pathElements.add(nodeName);
         }
-        if (tokens.isEmpty()) {
+        if (pathElements.isEmpty()) {
             throw new IllegalDocumentNameException("A document path must contain at" +
                                                    "least one non-null" +
                                                    "element.");
@@ -75,39 +71,37 @@ public class DocumentPath implements Comparable {
     }
 
     /**
-     * Returns a path from the root to the parent of this node, if this node is
-     * the root this call returns null.
+     * Returns a path for the parent of this node.
      *
-     * @return a {@code DocumentPath} representing a path to this paths parent,
-     * null if this a root path
+     * @return parent node path. If this path is for the root, returns {@code null}.
      */
     public DocumentPath parent() {
-        if (tokens.size() <= 1) {
+        if (pathElements.size() <= 1) {
             return null;
         }
-        return new DocumentPath(this.tokens.subList(0, tokens.size() - 1));
+        return new DocumentPath(this.pathElements.subList(0, pathElements.size() - 1));
     }
 
     /**
-     * Returns the complete list of tokens representing this path in correct
+     * Returns the list of path elements representing this path in correct
      * order.
      *
-     * @return a list of strings representing this path
+     * @return a list of elements that make up this path
      */
-    public List<String> path() {
-        return ImmutableList.copyOf(tokens);
+    public List<String> pathElements() {
+        return ImmutableList.copyOf(pathElements);
     }
 
     @Override
     public int hashCode() {
-        return Objects.hash(tokens);
+        return Objects.hash(pathElements);
     }
 
     @Override
     public boolean equals(Object obj) {
         if (obj instanceof DocumentPath) {
             DocumentPath that = (DocumentPath) obj;
-            return this.tokens.equals(that.tokens);
+            return this.pathElements.equals(that.pathElements);
         }
         return false;
     }
@@ -115,7 +109,7 @@ public class DocumentPath implements Comparable {
     @Override
     public String toString() {
         StringBuilder stringBuilder = new StringBuilder();
-        Iterator<String> iter = tokens.iterator();
+        Iterator<String> iter = pathElements.iterator();
         while (iter.hasNext()) {
             stringBuilder.append(iter.next());
             if (iter.hasNext()) {
@@ -126,26 +120,21 @@ public class DocumentPath implements Comparable {
     }
 
     @Override
-    public int compareTo(Object o) {
-        if (o instanceof DocumentPath) {
-            DocumentPath that = (DocumentPath) o;
-            int shorterLength = this.tokens.size() > that.tokens.size() ?
-                    that.tokens.size() : this.tokens.size();
-            for (int i = 0; i < shorterLength; i++) {
-                if (this.tokens.get(i).compareTo(that.tokens.get(i)) != 0) {
-                    return this.tokens.get(i).compareTo(that.tokens.get(i));
-                }
+    public int compareTo(DocumentPath that) {
+        int shorterLength = this.pathElements.size() > that.pathElements.size()
+                ? that.pathElements.size() : this.pathElements.size();
+        for (int i = 0; i < shorterLength; i++) {
+            if (this.pathElements.get(i).compareTo(that.pathElements.get(i)) != 0) {
+                return this.pathElements.get(i).compareTo(that.pathElements.get(i));
             }
+        }
 
-            if (this.tokens.size() > that.tokens.size()) {
-                return 1;
-            } else if (that.tokens.size() > this.tokens.size()) {
-                return -1;
-            } else {
-                return 0;
-            }
+        if (this.pathElements.size() > that.pathElements.size()) {
+            return 1;
+        } else if (that.pathElements.size() > this.pathElements.size()) {
+            return -1;
+        } else {
+            return 0;
         }
-        throw new IllegalArgumentException("Compare can only compare objects" +
-                                                   "of the same type.");
     }
 }

@@ -16,82 +16,68 @@
 
 package org.onosproject.store.service;
 
-import org.onosproject.store.primitives.DocumentTreeNode;
-
 import java.util.Iterator;
 
+import org.onosproject.store.primitives.DocumentTreeNode;
+
 /**
- * Interface for a tree with structure wherein keys hold information
- * about the hierarchical structure of the tree (name of parent,
- * grandparent etc.).
+ * A hierarchical <a href="https://en.wikipedia.org/wiki/Document_Object_Model">document tree</a> data structure.
+ *
+ * @param V document tree value type
  */
 public interface DocumentTree<V> {
 
     /**
-     * Returns the root of the tree. This will be the first part of any fully
-     * qualified path and will enable discovery of the entire tree.
+     * Returns the {@link DocumentPath path} to root of the tree.
      *
-     * @return a string that is the name of the root of the tree.
+     * @return path to root of the tree
      */
     DocumentPath root();
 
     /**
-     * Returns a sorted list containing all key value pairs that are direct
-     * descendants of the supplied parent. The returned list will be immutable.
-     * If the specified parent does not exist this method will fail with an
-     * exception.
+     * Returns an iterator for all the first order descendants of a node.
      *
-     * @throws NoSuchDocumentPathException if the parent does not exist
-     * @param parentPath the path to the parent of the desired nodes
-     * @return an iterator of the children of the specified parent
+     * @param path path to the node
+     * @return an iterator for the child nodes of the specified node path
+     * @throws NoSuchDocumentPathException if the path does not point to a valid node
      */
-    Iterator<DocumentTreeNode<V>> getChildren(DocumentPath parentPath);
+    Iterator<DocumentTreeNode<V>> getChildren(DocumentPath path);
 
     /**
-     * Returns the value associated with the supplied key or null if no such
-     * node exists.
+     * Returns a document tree node.
      *
-     * @param key the key to query
-     * @return a value or null
+     * @param path path to node
+     * @return node value or {@code null} if path does not point to a valid node
      */
-    DocumentTreeNode<V> getNode(DocumentPath key);
+    DocumentTreeNode<V> getNode(DocumentPath path);
 
     /**
-     * Takes a string that specifies the complete path to the mapping to be
-     * added or updated and creates the key value mapping or updates the value.
-     * If the specified parent cannot be found the operation fails with an
-     * error.
+     * Creates or updates a document tree node.
      *
-     * @throws NoSuchDocumentPathException if the specified parent does not
-     * exist.
-     * @param key the fully qualified key of the entry to be added or updated
+     * @param path path for the node to create or update
      * @param value the non-null value to be associated with the key
-     * @return the previous mapping or null if there was no previous mapping
+     * @return the previous mapping or {@code null} if there was no previous mapping
+     * @throws NoSuchDocumentPathException if the parent node (for the node to create/update) does not exist
      */
-    V putNode(DocumentPath key, V value);
+    V putNode(DocumentPath path, V value);
 
     /**
-     * Takes the fully qualified  name of the node to be added along with
-     * the value to be added. If the specified key already exists it doesnot
-     * update anything & returns false. If the parent does not exist the
-     * operation fails with an exception.
+     * Creates a document tree node if one does not exist already.
      *
-     * @throws NoSuchDocumentPathException if the specified parent does not
-     * exist.
-     * @param key the fully qualified key of the entry to be added or updated
+     * @param path path for the node to create
      * @param value the non-null value to be associated with the key
-     * @return returns true if the mapping could be added successfully
+     * @return returns {@code true} if the mapping could be added successfully, {@code false} otherwise
+     * @throws NoSuchDocumentPathException if the parent node (for the node to create) does not exist
      */
-    boolean createNode(DocumentPath key, V value);
+    boolean createNode(DocumentPath path, V value);
 
     /**
-     * Removes the node with the specified fully qualified key. Returns null if
-     * the node did not exist. This method will throw an exception if called on
-     * a non-leaf node.
+     * Removes the node with the specified path.
      *
-     * @throws IllegalDocumentModificationException if the node had children.
-     * @param key the fully qualified key of the node to be removed
-     * @return the previous value of the node or null if it did not exist
+     * is not a leaf node i.e has one or more children
+     * @param path path for the node to remove
+     * @return the previous value of the node or {@code null} if it did not exist
+     * @throws IllegalDocumentModificationException if the remove to be removed
      */
     V removeNode(DocumentPath key);
 }