--- /dev/null
+/*
+ * Copyright (c) 2015 Cisco Systems, Inc. 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.dom.api;
+
+import com.google.common.annotations.Beta;
+import javax.annotation.Nonnull;
+import javax.annotation.concurrent.NotThreadSafe;
+import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.PathArgument;
+import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNodeContainer;
+
+/**
+ * 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 DOMDataTreeCursor 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 NormalizedNodeContainer}.
+ */
+ void enter(@Nonnull PathArgument child);
+
+ /**
+ * Move the cursor to the specified child of the current position. This is the equivalent of
+ * multiple invocations of {@link #enter(PathArgument)}, 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 NormalizedNodeContainer}.
+ */
+ void enter(@Nonnull PathArgument... path);
+
+ /**
+ * Move the cursor to the specified child of the current position. This is equivalent to
+ * {@link #enter(PathArgument...)}, 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 NormalizedNodeContainer}.
+ */
+ void enter(@Nonnull Iterable<PathArgument> 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();
+}
--- /dev/null
+/*
+ * Copyright (c) 2015 Cisco Systems, Inc. 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.dom.api;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import org.opendaylight.yangtools.yang.data.api.schema.tree.DataTreeModificationCursor;
+
+public interface DOMDataTreeCursorProvider {
+
+ /**
+ * Create a new {@link DataTreeModificationCursor} at specified path. May fail if specified path
+ * does not exist.
+ *
+ * @param path Path at which the cursor is to be anchored
+ * @return A new cursor, or null if the path does not exist.
+ * @throws IllegalStateException if there is another cursor currently open, or the transaction
+ * is already closed (closed or submitted).
+ */
+ @Nullable
+ DOMDataTreeCursor createCursor(@Nonnull DOMDataTreeIdentifier path);
+
+}
--- /dev/null
+/*
+ * Copyright (c) 2015 Cisco Systems, Inc. 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.dom.api;
+
+import com.google.common.base.Optional;
+import com.google.common.util.concurrent.CheckedFuture;
+import javax.annotation.Nonnull;
+import org.opendaylight.mdsal.common.api.ReadFailedException;
+import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.PathArgument;
+import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
+
+public interface DOMDataTreeReadCursor extends DOMDataTreeCursor {
+
+ /**
+ * Read a particular node from the snapshot.
+ *
+ * @param child Child identifier
+ * @return Optional result encapsulating the presence and value of the node
+ * @throws IllegalArgumentException when specified path does not identify a valid child.
+ */
+ CheckedFuture<Optional<NormalizedNode<?, ?>>, ReadFailedException> readNode(@Nonnull PathArgument child);
+
+ /**
+ * Checks if data is available in the logical data store located at provided path.
+ * <p>
+ *
+ * Note: a successful result from this method makes no guarantee that a subsequent call to
+ * {@link #readNode(PathArgument)} will succeed. It is possible that the data resides in a data store on a remote
+ * node and, if that node goes down or a network failure occurs, a subsequent read would fail.
+ * Another scenario is if the data is deleted in between the calls to <code>exists</code> and
+ * <code>readNode</code>
+ *
+ * @param child Child identifier
+ * @return a CheckFuture containing the result of the check.
+ * <ul>
+ * <li>If the data at the supplied path exists, the Future returns a Boolean whose value
+ * is true, false otherwise</li> <li>If checking for the data fails, the Future will
+ * fail with a {@link ReadFailedException} or an exception derived from
+ * ReadFailedException.</li>
+ * </ul>
+ */
+ CheckedFuture<Boolean, ReadFailedException> exists(@Nonnull PathArgument child);
+}
*/
package org.opendaylight.mdsal.dom.api;
+import com.google.common.base.Optional;
+import com.google.common.util.concurrent.CheckedFuture;
import org.opendaylight.mdsal.common.api.AsyncReadTransaction;
import org.opendaylight.mdsal.common.api.LogicalDatastoreType;
import org.opendaylight.mdsal.common.api.ReadFailedException;
-
import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
-import com.google.common.base.Optional;
-import com.google.common.util.concurrent.CheckedFuture;
/**
* A transaction that provides read access to a logical data store.
LogicalDatastoreType store, YangInstanceIdentifier path);
/**
- /**
* Checks if data is available in the logical data store located at provided path.
* <p>
*
--- /dev/null
+/*
+ * Copyright (c) 2015 Cisco Systems, Inc. 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.dom.api;
+
+import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.PathArgument;
+import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
+import org.opendaylight.yangtools.yang.data.api.schema.tree.BackendFailedException;
+
+public interface DOMDataTreeWriteCursor extends DOMDataTreeCursor {
+
+ /**
+ * Delete the specified child.
+ *
+ * @param child Child identifier
+ * @throws BackendFailedException when implementation-specific errors occurs while servicing the
+ * request.
+ */
+ void delete(PathArgument 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.
+ */
+ void merge(PathArgument child, NormalizedNode<?, ?> 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.
+ */
+ void write(PathArgument child, NormalizedNode<?, ?> data);
+}
Code Review / mdsal.git / commitdiff