yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/DataTreeSnapshotCursor.java

   1 /*
   2  * Copyright (c) 2015 Cisco Systems, Inc. and others.  All rights reserved.
   3  *
   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
   7  */
   8 package org.opendaylight.yangtools.yang.data.api.schema.tree;
   9
  10 import com.google.common.annotations.Beta;
  11 import com.google.common.base.Optional;
  12 import javax.annotation.Nonnull;
  13 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.PathArgument;
  14 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
  15 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNodeContainer;
  16
  17 /**
  18  * A cursor holding a logical position within a {@link DataTreeSnapshot}. It allows
  19  * operations relative to that position, as well as moving the position up or down
  20  * the tree.
  21  */
  22 @Beta
  23 public interface DataTreeSnapshotCursor extends AutoCloseable {
  24     /**
  25      * Move the cursor to the specified child of the current position.
  26      *
  27      * @param child Child identifier
  28      * @throws BackendFailedException when implementation-specific errors occurs
  29      *                                while servicing the request.
  30      * @throws IllegalArgumentException when specified identifier does not identify
  31      *                                  a valid child, or if that child is not an
  32      *                                  instance of {@link NormalizedNodeContainer}.
  33      */
  34     void enter(@Nonnull PathArgument child);
  35
  36     /**
  37      * Move the cursor to the specified child of the current position. This is
  38      * the equivalent of multiple invocations of {@link #enter(PathArgument)},
  39      * except the operation is performed atomically.
  40      *
  41      * @param path Nested child identifier
  42      * @throws BackendFailedException when implementation-specific errors occurs
  43      *                                while servicing the request.
  44      * @throws IllegalArgumentException when specified path does not identify
  45      *                                  a valid child, or if that child is not an
  46      *                                  instance of {@link NormalizedNodeContainer}.
  47      */
  48     void enter(@Nonnull PathArgument... path);
  49
  50     /**
  51      * Move the cursor to the specified child of the current position. This is
  52      * equivalent to {@link #enter(PathArgument...)}, except it takes an {@link Iterable}
  53      * argument.
  54      *
  55      * @param path Nested child identifier
  56      * @throws BackendFailedException when implementation-specific errors occurs
  57      *                                while servicing the request.
  58      * @throws IllegalArgumentException when specified path does not identify
  59      *                                  a valid child, or if that child is not an
  60      *                                  instance of {@link NormalizedNodeContainer}.
  61      */
  62     void enter(@Nonnull Iterable<PathArgument> path);
  63
  64     /**
  65      * Move the cursor up to the parent of current position. This is equivalent of
  66      * invoking <code>exit(1)</code>.
  67      *
  68      * @throws IllegalStateException when exiting would violate containment, typically
  69      *                               by attempting to exit more levels than previously
  70      *                               entered.
  71      */
  72     void exit();
  73
  74     /**
  75      * Move the cursor up by specified amounts of steps from the current position.
  76      * This is equivalent of invoking {@link #exit()} multiple times, except the
  77      * operation is performed atomically.
  78      *
  79      * @param depth number of steps to exit
  80      * @throws IllegalArgumentException when depth is negative.
  81      * @throws IllegalStateException when exiting would violate containment, typically
  82      *                               by attempting to exit more levels than previously
  83      *                               entered.
  84      */
  85     void exit(int depth);
  86
  87     /**
  88      * Read a particular node from the snapshot.
  89      *
  90      * @param child Child identifier
  91      * @return Optional result encapsulating the presence and value of the node
  92      * @throws BackendFailedException when implementation-specific error occurs while
  93      *                                servicing the request.
  94      * @throws IllegalArgumentException when specified path does not identify a valid child.
  95      */
  96     Optional<NormalizedNode<?, ?>> readNode(@Nonnull PathArgument child);
  97
  98     /**
  99      * Close this cursor. Attempting any further operations on the cursor will lead
 100      * to undefined behavior.
 101      */
 102     @Override
 103     void close();
 104 }