/*
* 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.yangtools.yang.data.api.schema.tree;
import com.google.common.annotations.Beta;
import com.google.common.base.Optional;
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.NormalizedNode;
import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNodeContainer;
/**
* A cursor holding a logical position within a {@link DataTreeSnapshot}. It allows
* operations relative to that position, as well as moving the position up or down
* the tree.
*/
@Beta
@NotThreadSafe
public interface DataTreeSnapshotCursor extends AutoCloseable {
/**
* Move the cursor to the specified child of the current position.
*
* @param child Child identifier
* @throws BackendFailedException when an implementation-specific error occurs
* while servicing the request.
* @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 BackendFailedException when an implementation-specific error occurs
* while servicing the request.
* @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 BackendFailedException when an implementation-specific error occurs
* while servicing the request.
* @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);
/**
* Read a particular node from the snapshot.
*
* @param child Child identifier
* @return Optional result encapsulating the presence and value of the node
* @throws BackendFailedException when implementation-specific error occurs while
* servicing the request.
* @throws IllegalArgumentException when specified path does not identify a valid child.
*/
Optional<NormalizedNode<?, ?>> readNode(@Nonnull PathArgument child);
/**
* Close this cursor. Attempting any further operations on the cursor will lead
* to undefined behavior.
*/
@Override
void close();
}