Javadoc updates to DocumentTree classes
Change-Id: Id55d317de95fc6b50849de58a1d813a7cc1216e7
diff --git a/core/api/src/main/java/org/onosproject/store/service/DocumentPath.java b/core/api/src/main/java/org/onosproject/store/service/DocumentPath.java
index 1147c22..d73fa53 100644
--- a/core/api/src/main/java/org/onosproject/store/service/DocumentPath.java
+++ b/core/api/src/main/java/org/onosproject/store/service/DocumentPath.java
@@ -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;
-/**
- * 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.
- */
-public class DocumentPath implements Comparable {
+import com.google.common.base.Preconditions;
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.Lists;
- private final ArrayList<String> tokens = Lists.newArrayList();
+/**
+ * Unique key for nodes in the {@link DocumentTree}.
+ */
+public class DocumentPath implements Comparable<DocumentPath> {
+
+ 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 @@
"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 @@
}
/**
- * 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 @@
@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 @@
}
@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));
- }
- }
-
- if (this.tokens.size() > that.tokens.size()) {
- return 1;
- } else if (that.tokens.size() > this.tokens.size()) {
- return -1;
- } else {
- return 0;
+ 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));
}
}
- throw new IllegalArgumentException("Compare can only compare objects" +
- "of the same type.");
+
+ if (this.pathElements.size() > that.pathElements.size()) {
+ return 1;
+ } else if (that.pathElements.size() > this.pathElements.size()) {
+ return -1;
+ } else {
+ return 0;
+ }
}
}
diff --git a/core/api/src/main/java/org/onosproject/store/service/DocumentTree.java b/core/api/src/main/java/org/onosproject/store/service/DocumentTree.java
index 5156c06..5a86009 100644
--- a/core/api/src/main/java/org/onosproject/store/service/DocumentTree.java
+++ b/core/api/src/main/java/org/onosproject/store/service/DocumentTree.java
@@ -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);
}