Committed by
Gerrit Code Review
Javadoc updates to DocumentTree classes
Change-Id: Id55d317de95fc6b50849de58a1d813a7cc1216e7
Showing
2 changed files
with
76 additions
and
101 deletions
... | @@ -16,45 +16,41 @@ | ... | @@ -16,45 +16,41 @@ |
16 | 16 | ||
17 | package org.onosproject.store.service; | 17 | package org.onosproject.store.service; |
18 | 18 | ||
19 | -import com.google.common.base.Preconditions; | ||
20 | -import com.google.common.collect.ImmutableList; | ||
21 | -import com.google.common.collect.Lists; | ||
22 | - | ||
23 | -import java.util.ArrayList; | ||
24 | import java.util.Iterator; | 19 | import java.util.Iterator; |
25 | import java.util.List; | 20 | import java.util.List; |
26 | import java.util.Objects; | 21 | import java.util.Objects; |
27 | 22 | ||
23 | +import com.google.common.base.Preconditions; | ||
24 | +import com.google.common.collect.ImmutableList; | ||
25 | +import com.google.common.collect.Lists; | ||
26 | + | ||
28 | /** | 27 | /** |
29 | - * A path class for identifying nodes within the {@code DocumentTree}. | 28 | + * Unique key for nodes in the {@link DocumentTree}. |
30 | - * | ||
31 | - * Note: indexing is ONE based so the root is the 1st level, to retrieve the | ||
32 | - * root one should query level 1. | ||
33 | */ | 29 | */ |
34 | -public class DocumentPath implements Comparable { | 30 | +public class DocumentPath implements Comparable<DocumentPath> { |
35 | 31 | ||
36 | - private final ArrayList<String> tokens = Lists.newArrayList(); | 32 | + private final List<String> pathElements = Lists.newArrayList(); |
37 | 33 | ||
38 | /** | 34 | /** |
39 | * Private utility constructor for internal generation of partial paths only. | 35 | * Private utility constructor for internal generation of partial paths only. |
40 | * | 36 | * |
41 | - * @param path | 37 | + * @param pathElements list of path elements |
42 | */ | 38 | */ |
43 | - private DocumentPath(List<String> path) { | 39 | + private DocumentPath(List<String> pathElements) { |
44 | - Preconditions.checkNotNull(path); | 40 | + Preconditions.checkNotNull(pathElements); |
45 | - this.tokens.addAll(path); | 41 | + this.pathElements.addAll(pathElements); |
46 | } | 42 | } |
47 | 43 | ||
48 | /** | 44 | /** |
49 | - * Constructor to generate new {@DocumentPath}, new paths must contain at | 45 | + * Constructs a {@DocumentPath}. |
50 | - * least one name and string names may NOT contain any '.'s. If one field | 46 | + * <p> |
51 | - * is null that field will be ignored. | 47 | + * New paths must contain at least one name and string names may NOT contain any period characters. |
48 | + * If one field is {@code null} that field will be ignored. | ||
52 | * | 49 | * |
53 | - * @throws IllegalDocumentNameException if both parameters are null or the string | ||
54 | - * name contains an illegal character ('.') | ||
55 | * @param nodeName the name of the last level of this path | 50 | * @param nodeName the name of the last level of this path |
56 | - * @param parentPath the path representing the parents leading up to this | 51 | + * @param parentPath the path representing the parent leading up to this |
57 | - * node, in the case of the root this should be null | 52 | + * node, in the case of the root this should be {@code null} |
53 | + * @throws IllegalDocumentNameException if both parameters are null or name contains an illegal character ('.') | ||
58 | */ | 54 | */ |
59 | public DocumentPath(String nodeName, DocumentPath parentPath) { | 55 | public DocumentPath(String nodeName, DocumentPath parentPath) { |
60 | if (nodeName.contains(".")) { | 56 | if (nodeName.contains(".")) { |
... | @@ -62,12 +58,12 @@ public class DocumentPath implements Comparable { | ... | @@ -62,12 +58,12 @@ public class DocumentPath implements Comparable { |
62 | "Periods are not allowed in names."); | 58 | "Periods are not allowed in names."); |
63 | } | 59 | } |
64 | if (parentPath != null) { | 60 | if (parentPath != null) { |
65 | - tokens.addAll(parentPath.path()); | 61 | + pathElements.addAll(parentPath.pathElements()); |
66 | } | 62 | } |
67 | if (nodeName != null) { | 63 | if (nodeName != null) { |
68 | - tokens.add(nodeName); | 64 | + pathElements.add(nodeName); |
69 | } | 65 | } |
70 | - if (tokens.isEmpty()) { | 66 | + if (pathElements.isEmpty()) { |
71 | throw new IllegalDocumentNameException("A document path must contain at" + | 67 | throw new IllegalDocumentNameException("A document path must contain at" + |
72 | "least one non-null" + | 68 | "least one non-null" + |
73 | "element."); | 69 | "element."); |
... | @@ -75,39 +71,37 @@ public class DocumentPath implements Comparable { | ... | @@ -75,39 +71,37 @@ public class DocumentPath implements Comparable { |
75 | } | 71 | } |
76 | 72 | ||
77 | /** | 73 | /** |
78 | - * Returns a path from the root to the parent of this node, if this node is | 74 | + * Returns a path for the parent of this node. |
79 | - * the root this call returns null. | ||
80 | * | 75 | * |
81 | - * @return a {@code DocumentPath} representing a path to this paths parent, | 76 | + * @return parent node path. If this path is for the root, returns {@code null}. |
82 | - * null if this a root path | ||
83 | */ | 77 | */ |
84 | public DocumentPath parent() { | 78 | public DocumentPath parent() { |
85 | - if (tokens.size() <= 1) { | 79 | + if (pathElements.size() <= 1) { |
86 | return null; | 80 | return null; |
87 | } | 81 | } |
88 | - return new DocumentPath(this.tokens.subList(0, tokens.size() - 1)); | 82 | + return new DocumentPath(this.pathElements.subList(0, pathElements.size() - 1)); |
89 | } | 83 | } |
90 | 84 | ||
91 | /** | 85 | /** |
92 | - * Returns the complete list of tokens representing this path in correct | 86 | + * Returns the list of path elements representing this path in correct |
93 | * order. | 87 | * order. |
94 | * | 88 | * |
95 | - * @return a list of strings representing this path | 89 | + * @return a list of elements that make up this path |
96 | */ | 90 | */ |
97 | - public List<String> path() { | 91 | + public List<String> pathElements() { |
98 | - return ImmutableList.copyOf(tokens); | 92 | + return ImmutableList.copyOf(pathElements); |
99 | } | 93 | } |
100 | 94 | ||
101 | @Override | 95 | @Override |
102 | public int hashCode() { | 96 | public int hashCode() { |
103 | - return Objects.hash(tokens); | 97 | + return Objects.hash(pathElements); |
104 | } | 98 | } |
105 | 99 | ||
106 | @Override | 100 | @Override |
107 | public boolean equals(Object obj) { | 101 | public boolean equals(Object obj) { |
108 | if (obj instanceof DocumentPath) { | 102 | if (obj instanceof DocumentPath) { |
109 | DocumentPath that = (DocumentPath) obj; | 103 | DocumentPath that = (DocumentPath) obj; |
110 | - return this.tokens.equals(that.tokens); | 104 | + return this.pathElements.equals(that.pathElements); |
111 | } | 105 | } |
112 | return false; | 106 | return false; |
113 | } | 107 | } |
... | @@ -115,7 +109,7 @@ public class DocumentPath implements Comparable { | ... | @@ -115,7 +109,7 @@ public class DocumentPath implements Comparable { |
115 | @Override | 109 | @Override |
116 | public String toString() { | 110 | public String toString() { |
117 | StringBuilder stringBuilder = new StringBuilder(); | 111 | StringBuilder stringBuilder = new StringBuilder(); |
118 | - Iterator<String> iter = tokens.iterator(); | 112 | + Iterator<String> iter = pathElements.iterator(); |
119 | while (iter.hasNext()) { | 113 | while (iter.hasNext()) { |
120 | stringBuilder.append(iter.next()); | 114 | stringBuilder.append(iter.next()); |
121 | if (iter.hasNext()) { | 115 | if (iter.hasNext()) { |
... | @@ -126,26 +120,21 @@ public class DocumentPath implements Comparable { | ... | @@ -126,26 +120,21 @@ public class DocumentPath implements Comparable { |
126 | } | 120 | } |
127 | 121 | ||
128 | @Override | 122 | @Override |
129 | - public int compareTo(Object o) { | 123 | + public int compareTo(DocumentPath that) { |
130 | - if (o instanceof DocumentPath) { | 124 | + int shorterLength = this.pathElements.size() > that.pathElements.size() |
131 | - DocumentPath that = (DocumentPath) o; | 125 | + ? that.pathElements.size() : this.pathElements.size(); |
132 | - int shorterLength = this.tokens.size() > that.tokens.size() ? | 126 | + for (int i = 0; i < shorterLength; i++) { |
133 | - that.tokens.size() : this.tokens.size(); | 127 | + if (this.pathElements.get(i).compareTo(that.pathElements.get(i)) != 0) { |
134 | - for (int i = 0; i < shorterLength; i++) { | 128 | + return this.pathElements.get(i).compareTo(that.pathElements.get(i)); |
135 | - if (this.tokens.get(i).compareTo(that.tokens.get(i)) != 0) { | ||
136 | - return this.tokens.get(i).compareTo(that.tokens.get(i)); | ||
137 | - } | ||
138 | } | 129 | } |
130 | + } | ||
139 | 131 | ||
140 | - if (this.tokens.size() > that.tokens.size()) { | 132 | + if (this.pathElements.size() > that.pathElements.size()) { |
141 | - return 1; | 133 | + return 1; |
142 | - } else if (that.tokens.size() > this.tokens.size()) { | 134 | + } else if (that.pathElements.size() > this.pathElements.size()) { |
143 | - return -1; | 135 | + return -1; |
144 | - } else { | 136 | + } else { |
145 | - return 0; | 137 | + return 0; |
146 | - } | ||
147 | } | 138 | } |
148 | - throw new IllegalArgumentException("Compare can only compare objects" + | ||
149 | - "of the same type."); | ||
150 | } | 139 | } |
151 | } | 140 | } | ... | ... |
... | @@ -16,82 +16,68 @@ | ... | @@ -16,82 +16,68 @@ |
16 | 16 | ||
17 | package org.onosproject.store.service; | 17 | package org.onosproject.store.service; |
18 | 18 | ||
19 | -import org.onosproject.store.primitives.DocumentTreeNode; | ||
20 | - | ||
21 | import java.util.Iterator; | 19 | import java.util.Iterator; |
22 | 20 | ||
21 | +import org.onosproject.store.primitives.DocumentTreeNode; | ||
22 | + | ||
23 | /** | 23 | /** |
24 | - * Interface for a tree with structure wherein keys hold information | 24 | + * A hierarchical <a href="https://en.wikipedia.org/wiki/Document_Object_Model">document tree</a> data structure. |
25 | - * about the hierarchical structure of the tree (name of parent, | 25 | + * |
26 | - * grandparent etc.). | 26 | + * @param V document tree value type |
27 | */ | 27 | */ |
28 | public interface DocumentTree<V> { | 28 | public interface DocumentTree<V> { |
29 | 29 | ||
30 | /** | 30 | /** |
31 | - * Returns the root of the tree. This will be the first part of any fully | 31 | + * Returns the {@link DocumentPath path} to root of the tree. |
32 | - * qualified path and will enable discovery of the entire tree. | ||
33 | * | 32 | * |
34 | - * @return a string that is the name of the root of the tree. | 33 | + * @return path to root of the tree |
35 | */ | 34 | */ |
36 | DocumentPath root(); | 35 | DocumentPath root(); |
37 | 36 | ||
38 | /** | 37 | /** |
39 | - * Returns a sorted list containing all key value pairs that are direct | 38 | + * Returns an iterator for all the first order descendants of a node. |
40 | - * descendants of the supplied parent. The returned list will be immutable. | ||
41 | - * If the specified parent does not exist this method will fail with an | ||
42 | - * exception. | ||
43 | * | 39 | * |
44 | - * @throws NoSuchDocumentPathException if the parent does not exist | 40 | + * @param path path to the node |
45 | - * @param parentPath the path to the parent of the desired nodes | 41 | + * @return an iterator for the child nodes of the specified node path |
46 | - * @return an iterator of the children of the specified parent | 42 | + * @throws NoSuchDocumentPathException if the path does not point to a valid node |
47 | */ | 43 | */ |
48 | - Iterator<DocumentTreeNode<V>> getChildren(DocumentPath parentPath); | 44 | + Iterator<DocumentTreeNode<V>> getChildren(DocumentPath path); |
49 | 45 | ||
50 | /** | 46 | /** |
51 | - * Returns the value associated with the supplied key or null if no such | 47 | + * Returns a document tree node. |
52 | - * node exists. | ||
53 | * | 48 | * |
54 | - * @param key the key to query | 49 | + * @param path path to node |
55 | - * @return a value or null | 50 | + * @return node value or {@code null} if path does not point to a valid node |
56 | */ | 51 | */ |
57 | - DocumentTreeNode<V> getNode(DocumentPath key); | 52 | + DocumentTreeNode<V> getNode(DocumentPath path); |
58 | 53 | ||
59 | /** | 54 | /** |
60 | - * Takes a string that specifies the complete path to the mapping to be | 55 | + * Creates or updates a document tree node. |
61 | - * added or updated and creates the key value mapping or updates the value. | ||
62 | - * If the specified parent cannot be found the operation fails with an | ||
63 | - * error. | ||
64 | * | 56 | * |
65 | - * @throws NoSuchDocumentPathException if the specified parent does not | 57 | + * @param path path for the node to create or update |
66 | - * exist. | ||
67 | - * @param key the fully qualified key of the entry to be added or updated | ||
68 | * @param value the non-null value to be associated with the key | 58 | * @param value the non-null value to be associated with the key |
69 | - * @return the previous mapping or null if there was no previous mapping | 59 | + * @return the previous mapping or {@code null} if there was no previous mapping |
60 | + * @throws NoSuchDocumentPathException if the parent node (for the node to create/update) does not exist | ||
70 | */ | 61 | */ |
71 | - V putNode(DocumentPath key, V value); | 62 | + V putNode(DocumentPath path, V value); |
72 | 63 | ||
73 | /** | 64 | /** |
74 | - * Takes the fully qualified name of the node to be added along with | 65 | + * Creates a document tree node if one does not exist already. |
75 | - * the value to be added. If the specified key already exists it doesnot | ||
76 | - * update anything & returns false. If the parent does not exist the | ||
77 | - * operation fails with an exception. | ||
78 | * | 66 | * |
79 | - * @throws NoSuchDocumentPathException if the specified parent does not | 67 | + * @param path path for the node to create |
80 | - * exist. | ||
81 | - * @param key the fully qualified key of the entry to be added or updated | ||
82 | * @param value the non-null value to be associated with the key | 68 | * @param value the non-null value to be associated with the key |
83 | - * @return returns true if the mapping could be added successfully | 69 | + * @return returns {@code true} if the mapping could be added successfully, {@code false} otherwise |
70 | + * @throws NoSuchDocumentPathException if the parent node (for the node to create) does not exist | ||
84 | */ | 71 | */ |
85 | - boolean createNode(DocumentPath key, V value); | 72 | + boolean createNode(DocumentPath path, V value); |
86 | 73 | ||
87 | /** | 74 | /** |
88 | - * Removes the node with the specified fully qualified key. Returns null if | 75 | + * Removes the node with the specified path. |
89 | - * the node did not exist. This method will throw an exception if called on | ||
90 | - * a non-leaf node. | ||
91 | * | 76 | * |
92 | - * @throws IllegalDocumentModificationException if the node had children. | 77 | + * is not a leaf node i.e has one or more children |
93 | - * @param key the fully qualified key of the node to be removed | 78 | + * @param path path for the node to remove |
94 | - * @return the previous value of the node or null if it did not exist | 79 | + * @return the previous value of the node or {@code null} if it did not exist |
80 | + * @throws IllegalDocumentModificationException if the remove to be removed | ||
95 | */ | 81 | */ |
96 | V removeNode(DocumentPath key); | 82 | V removeNode(DocumentPath key); |
97 | } | 83 | } | ... | ... |
-
Please register or login to post a comment