2 * Copyright (c) 2015 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
8 package org.opendaylight.yangtools.yang.data.api.schema.tree;
10 import com.google.common.annotations.Beta;
11 import java.util.Optional;
12 import javax.annotation.Nonnull;
13 import javax.annotation.concurrent.NotThreadSafe;
14 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.PathArgument;
15 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
16 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNodeContainer;
19 * A cursor holding a logical position within a {@link DataTreeSnapshot}. It allows
20 * operations relative to that position, as well as moving the position up or down
25 public interface DataTreeSnapshotCursor extends AutoCloseable {
27 * Move the cursor to the specified child of the current position.
29 * @param child Child identifier
30 * @throws BackendFailedException when an implementation-specific error occurs
31 * while servicing the request.
32 * @throws IllegalArgumentException when specified identifier does not identify
33 * a valid child, or if that child is not an
34 * instance of {@link NormalizedNodeContainer}.
36 void enter(@Nonnull PathArgument child);
39 * Move the cursor to the specified child of the current position. This is
40 * the equivalent of multiple invocations of {@link #enter(PathArgument)},
41 * except the operation is performed all at once.
43 * @param path Nested child identifier
44 * @throws BackendFailedException when an implementation-specific error occurs
45 * while servicing the request.
46 * @throws IllegalArgumentException when specified path does not identify
47 * a valid child, or if that child is not an
48 * instance of {@link NormalizedNodeContainer}.
50 void enter(@Nonnull PathArgument... path);
53 * Move the cursor to the specified child of the current position. This is
54 * equivalent to {@link #enter(PathArgument...)}, except it takes an {@link Iterable}
57 * @param path Nested child identifier
58 * @throws BackendFailedException when an implementation-specific error occurs
59 * while servicing the request.
60 * @throws IllegalArgumentException when specified path does not identify
61 * a valid child, or if that child is not an
62 * instance of {@link NormalizedNodeContainer}.
64 void enter(@Nonnull Iterable<PathArgument> path);
67 * Move the cursor up to the parent of current position. This is equivalent of
68 * invoking <code>exit(1)</code>.
70 * @throws IllegalStateException when exiting would violate containment, typically
71 * by attempting to exit more levels than previously
77 * Move the cursor up by specified amounts of steps from the current position.
78 * This is equivalent of invoking {@link #exit()} multiple times, except the
79 * operation is performed atomically.
81 * @param depth number of steps to exit
82 * @throws IllegalArgumentException when depth is negative.
83 * @throws IllegalStateException when exiting would violate containment, typically
84 * by attempting to exit more levels than previously
90 * Read a particular node from the snapshot.
92 * @param child Child identifier
93 * @return Optional result encapsulating the presence and value of the node
94 * @throws BackendFailedException when implementation-specific error occurs while
95 * servicing the request.
96 * @throws IllegalArgumentException when specified path does not identify a valid child.
98 Optional<NormalizedNode<?, ?>> readNode(@Nonnull PathArgument child);
101 * Close this cursor. Attempting any further operations on the cursor will lead
102 * to undefined behavior.