홍길동 / onos

Go to a project
Toggle navigation Toggle navigation pinning
Madan Jampani
Committed by Gerrit Code Review
5bdebd5c 1 parent 2ca9a35d

Javadoc updates to DocumentTree classes 

Change-Id: Id55d317de95fc6b50849de58a1d813a7cc1216e7
Inline Side-by-side
Showing 2 changed files with 70 additions and 95 deletions
......@@ -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();
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.tokens.get(i).compareTo(that.tokens.get(i)) != 0) {
return this.tokens.get(i).compareTo(that.tokens.get(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()) {
if (this.pathElements.size() > that.pathElements.size()) {
return 1;
} else if (that.tokens.size() > this.tokens.size()) {
} 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);
}
......