2 * Copyright (c) 2016 Cisco Systems, Inc. and others. All rights reserved.
4 * This program and the accompanying materials are made available under the
5 * terms of the Eclipse Public License v1.0 which accompanies this distribution,
6 * and is available at http://www.eclipse.org/legal/epl-v10.html
9 package org.opendaylight.mdsal.binding.api;
11 import com.google.common.annotations.Beta;
12 import javax.annotation.Nonnull;
13 import javax.annotation.concurrent.NotThreadSafe;
14 import org.opendaylight.yangtools.yang.binding.DataContainer;
15 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier.PathArgument;
19 * A cursor holding a logical position within a conceptual data tree. It allows operations relative
20 * to that position, as well as moving the position up or down the tree.
24 public interface DataTreeCursor extends AutoCloseable {
26 * Move the cursor to the specified child of the current position.
28 * @param child Child identifier
29 * @throws IllegalArgumentException when specified identifier does not identify a valid child,
30 * or if that child is not an instance of {@link DataContainer}.
32 void enter(@Nonnull PathArgument child);
35 * Move the cursor to the specified child of the current position. This is the equivalent of
36 * multiple invocations of {@link #enter(PathArgument)}, except the operation is performed all
39 * @param path Nested child identifier
40 * @throws IllegalArgumentException when specified path does not identify a valid child, or if
41 * that child is not an instance of {@link DataContainer}.
43 void enter(@Nonnull PathArgument... path);
46 * Move the cursor to the specified child of the current position. This is equivalent to
47 * {@link #enter(PathArgument...)}, except it takes an {@link Iterable} argument.
49 * @param path Nested child identifier
50 * @throws IllegalArgumentException when specified path does not identify a valid child, or if
51 * that child is not an instance of {@link DataContainer}.
53 void enter(@Nonnull Iterable<PathArgument> path);
56 * Move the cursor up to the parent of current position. This is equivalent of invoking
57 * <code>exit(1)</code>.
59 * @throws IllegalStateException when exiting would violate containment, typically by attempting
60 * to exit more levels than previously entered.
65 * Move the cursor up by specified amounts of steps from the current position. This is
66 * equivalent of invoking {@link #exit()} multiple times, except the operation is performed
69 * @param depth number of steps to exit
70 * @throws IllegalArgumentException when depth is negative.
71 * @throws IllegalStateException when exiting would violate containment, typically by attempting
72 * to exit more levels than previously entered.
77 * Close this cursor. Attempting any further operations on the cursor will lead to undefined