Binding2 runtime - API #2

- DataTreeWriteCursor & its relatives
- Javadocs provided

Change-Id: I1e6d6e6f609d048f78821875a0ef37f7aa6f47b1
Signed-off-by: Martin Ciglan <martin.ciglan@pantheon.tech>
(cherry picked from commit b60e6c66d294945f916f8a78b5d383c9c49659ff)

diff --git a/binding2/mdsal-binding2-api/src/main/java/org/opendaylight/mdsal/binding/javav2/api/DataTreeCursor.java b/binding2/mdsal-binding2-api/src/main/java/org/opendaylight/mdsal/binding/javav2/api/DataTreeCursor.java
new file mode 100644 (file)
index 0000000..c3fceaf
--- /dev/null
+++ b/binding2/mdsal-binding2-api/src/main/java/org/opendaylight/mdsal/binding/javav2/api/DataTreeCursor.java
@@ -0,0 +1,82 @@
+/*
+ * Copyright (c) 2017 Pantheon Technologies s.r.o. and others.  All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this distribution,
+ * and is available at http://www.eclipse.org/legal/epl-v10.html
+ */
+
+package org.opendaylight.mdsal.binding.javav2.api;
+
+import com.google.common.annotations.Beta;
+import javax.annotation.Nonnull;
+import javax.annotation.concurrent.NotThreadSafe;
+import org.opendaylight.mdsal.binding.javav2.spec.base.TreeArgument;
+import org.opendaylight.mdsal.binding.javav2.spec.base.TreeNode;
+
+/**
+ * A cursor holding a logical position within a conceptual data tree. It allows operations relative
+ * to that position, as well as moving the position up or down the tree.
+ */
+@Beta
+@NotThreadSafe
+public interface DataTreeCursor extends AutoCloseable {
+
+    /**
+     * Move the cursor to the specified child of the current position.
+     *
+     * @param child Child identifier
+     * @throws IllegalArgumentException when specified identifier does not identify a valid child,
+     *         or if that child is not an instance of {@link TreeNode}.
+     */
+    void enter(@Nonnull TreeArgument<?> child);
+
+    /**
+     * Move the cursor to the specified child of the current position. This is the equivalent of
+     * multiple invocations of {@link #enter(TreeArgument)}, except the operation is performed all
+     * at once.
+     *
+     * @param path Nested child identifier
+     * @throws IllegalArgumentException when specified path does not identify a valid child, or if
+     *         that child is not an instance of {@link TreeNode}.
+     */
+    void enter(@Nonnull TreeArgument<?>... path);
+
+    /**
+     * Move the cursor to the specified child of the current position. This is equivalent to
+     * {@link #enter(TreeArgument...)}, except it takes an {@link Iterable} argument.
+     *
+     * @param path Nested child identifier
+     * @throws IllegalArgumentException when specified path does not identify a valid child, or if
+     *         that child is not an instance of {@link TreeNode}.
+     */
+    void enter(@Nonnull Iterable<TreeArgument<?>> path);
+
+    /**
+     * Move the cursor up to the parent of current position. This is equivalent of invoking
+     * <code>exit(1)</code>.
+     *
+     * @throws IllegalStateException when exiting would violate containment, typically by attempting
+     *         to exit more levels than previously entered.
+     */
+    void exit();
+
+    /**
+     * Move the cursor up by specified amounts of steps from the current position. This is
+     * equivalent of invoking {@link #exit()} multiple times, except the operation is performed
+     * atomically.
+     *
+     * @param depth number of steps to exit
+     * @throws IllegalArgumentException when depth is negative.
+     * @throws IllegalStateException when exiting would violate containment, typically by attempting
+     *         to exit more levels than previously entered.
+     */
+    void exit(int depth);
+
+    /**
+     * Close this cursor. Attempting any further operations on the cursor will lead to undefined
+     * behavior.
+     */
+    @Override
+    void close() throws Exception;
+}

diff --git a/binding2/mdsal-binding2-api/src/main/java/org/opendaylight/mdsal/binding/javav2/api/DataTreeWriteCursor.java b/binding2/mdsal-binding2-api/src/main/java/org/opendaylight/mdsal/binding/javav2/api/DataTreeWriteCursor.java
new file mode 100644 (file)
index 0000000..3ecd79d
--- /dev/null
+++ b/binding2/mdsal-binding2-api/src/main/java/org/opendaylight/mdsal/binding/javav2/api/DataTreeWriteCursor.java
@@ -0,0 +1,53 @@
+/*
+ * Copyright (c) 2017 Pantheon Technologies s.r.o. and others.  All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this distribution,
+ * and is available at http://www.eclipse.org/legal/epl-v10.html
+ */
+
+package org.opendaylight.mdsal.binding.javav2.api;
+
+import com.google.common.annotations.Beta;
+import org.opendaylight.mdsal.binding.javav2.spec.base.TreeArgument;
+import org.opendaylight.mdsal.binding.javav2.spec.base.TreeNode;
+import org.opendaylight.yangtools.yang.data.api.schema.tree.BackendFailedException;
+
+/**
+ * {@inheritDoc}
+ *
+ * <p>
+ * In addition this cursor also provides write operations(delete, merge, write).
+ */
+@Beta
+public interface DataTreeWriteCursor extends DataTreeCursor {
+
+    /**
+     * Delete the specified child.
+     *
+     * @param child Child identifier
+     * @throws BackendFailedException when implementation-specific errors occurs while servicing the
+     *         request.
+     */
+    void delete(TreeArgument<?> child);
+
+    /**
+     * Merge the specified data with the currently-present data at specified path.
+     *
+     * @param child Child identifier
+     * @param data Data to be merged
+     * @throws BackendFailedException when implementation-specific errors occurs while servicing the
+     *         request.
+     */
+    <T extends TreeNode> void merge(TreeArgument<T> child, T data);
+
+    /**
+     * Replace the data at specified path with supplied data.
+     *
+     * @param child Child identifier
+     * @param data New node data
+     * @throws BackendFailedException when implementation-specific errors occurs while servicing the
+     *         request.
+     */
+    <T extends TreeNode> void write(TreeArgument<T> child, T data);
+}