Updates to DocumentTreeNode + Simple implementation of DocumentTree interface
Change-Id: Icc162201a50de8ae48abdb8e769fb6ed86138a03
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 4e97cd4..1c43f4d 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,6 +16,7 @@
package org.onosproject.store.service;
+import java.util.Arrays;
import java.util.Iterator;
import java.util.List;
import java.util.Objects;
@@ -71,6 +72,16 @@
}
/**
+ * Creates a new {@code DocumentPath} from a period delimited path string.
+ *
+ * @param path path string
+ * @return {@code DocumentPath} instance
+ */
+ public static DocumentPath from(String path) {
+ return new DocumentPath(Arrays.asList(path.split("\\.")));
+ }
+
+ /**
* Returns a path for the parent of this node.
*
* @return parent node path. If this path is for the root, returns {@code null}.
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 35c6deb..4255b65 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,15 +16,16 @@
package org.onosproject.store.service;
-import java.util.Iterator;
+import java.util.Map;
-import org.onosproject.store.primitives.DocumentTreeNode;
+import javax.annotation.concurrent.NotThreadSafe;
/**
* A hierarchical <a href="https://en.wikipedia.org/wiki/Document_Object_Model">document tree</a> data structure.
*
* @param <V> document tree value type
*/
+@NotThreadSafe
public interface DocumentTree<V> {
/**
@@ -35,13 +36,13 @@
DocumentPath root();
/**
- * Returns an iterator for all the first order descendants of a node.
+ * Returns the child values for this node.
*
* @param path path to the node
- * @return an iterator for the child nodes of the specified node path
+ * @return mapping from a child name to its value
* @throws NoSuchDocumentPathException if the path does not point to a valid node
*/
- Iterator<DocumentTreeNode<V>> getChildren(DocumentPath path);
+ Map<String, Versioned<V>> getChildren(DocumentPath path);
/**
* Returns a document tree node.
@@ -49,7 +50,7 @@
* @param path path to node
* @return node value or {@code null} if path does not point to a valid node
*/
- DocumentTreeNode<V> getNode(DocumentPath path);
+ Versioned<V> get(DocumentPath path);
/**
* Creates or updates a document tree node.
@@ -59,7 +60,7 @@
* @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 path, V value);
+ Versioned<V> set(DocumentPath path, V value);
/**
* Creates a document tree node if one does not exist already.
@@ -69,7 +70,7 @@
* @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 path, V value);
+ boolean create(DocumentPath path, V value);
/**
* Conditionally updates a tree node if the current version matches a specified version.
@@ -77,7 +78,7 @@
* @param path path for the node to create
* @param newValue the non-null value to be associated with the key
* @param version current version of the value for update to occur
- * @return returns {@code true} if the update was made, {@code false} otherwise
+ * @return returns {@code true} if the update was made and the tree was modified, {@code false} otherwise
* @throws NoSuchDocumentPathException if the parent node (for the node to create) does not exist
*/
boolean replace(DocumentPath path, V newValue, long version);
@@ -88,7 +89,8 @@
* @param path path for the node to create
* @param newValue the non-null value to be associated with the key
* @param currentValue current value for update to occur
- * @return returns {@code true} if the update was made, {@code false} otherwise
+ * @return returns {@code true} if the update was made and the tree was modified, {@code false} otherwise.
+ * This method returns {@code false} if the newValue and currentValue are same.
* @throws NoSuchDocumentPathException if the parent node (for the node to create) does not exist
*/
boolean replace(DocumentPath path, V newValue, V currentValue);
@@ -96,12 +98,11 @@
/**
* Removes the node with the specified path.
*
- * is not a leaf node i.e has one or more children
- * @param key path for the node to remove
+ * @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);
+ Versioned<V> removeNode(DocumentPath path);
/**
* Registers a listener to be notified when a subtree rooted at the specified path
diff --git a/core/api/src/main/java/org/onosproject/store/service/DocumentTreeNode.java b/core/api/src/main/java/org/onosproject/store/service/DocumentTreeNode.java
new file mode 100644
index 0000000..9de9780
--- /dev/null
+++ b/core/api/src/main/java/org/onosproject/store/service/DocumentTreeNode.java
@@ -0,0 +1,67 @@
+/*
+ * Copyright 2016-present Open Networking Laboratory
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.onosproject.store.service;
+
+import java.util.Iterator;
+
+import javax.annotation.concurrent.NotThreadSafe;
+
+/**
+ * A {@code DocumentTree} node.
+ *
+ * @param <V> value type
+ */
+@NotThreadSafe
+public interface DocumentTreeNode<V> {
+
+ /**
+ * Returns the path to this node in a {@code DocumentTree}.
+ *
+ * @return absolute path
+ */
+ DocumentPath path();
+
+ /**
+ * Returns the value of this node.
+ *
+ * @return node value (and version)
+ */
+ Versioned<V> value();
+
+ /**
+ * Returns the children of this node.
+ *
+ * @return iterator for this node's children
+ */
+ Iterator<DocumentTreeNode<V>> children();
+
+ /**
+ * Returns the child node of this node with the specified relative path name.
+ *
+ * @param relativePath relative path name for the child node.
+ * @return child node; this method returns {@code null} if no such child exists
+ */
+ DocumentTreeNode<V> child(String relativePath);
+
+ /**
+ * Returns if this node has one or more children.
+ * @return {@code true} if yes, {@code false} otherwise
+ */
+ default boolean hasChildren() {
+ return children().hasNext();
+ }
+}