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 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;
  17
  18 /**
  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
  21  * the tree.
  22  */
  23 @Beta
  24 @NotThreadSafe
  25 public interface DataTreeSnapshotCursor extends AutoCloseable {
  26     /**
  27      * Move the cursor to the specified child of the current position.
  28      *
  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}.
  35      */
  36     void enter(@Nonnull PathArgument child);
  37
  38     /**
  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.
  42      *
  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}.
  49      */
  50     void enter(@Nonnull PathArgument... path);
  51
  52     /**
  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}
  55      * argument.
  56      *
  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}.
  63      */
  64     void enter(@Nonnull Iterable<PathArgument> path);
  65
  66     /**
  67      * Move the cursor up to the parent of current position. This is equivalent of
  68      * invoking <code>exit(1)</code>.
  69      *
  70      * @throws IllegalStateException when exiting would violate containment, typically
  71      *                               by attempting to exit more levels than previously
  72      *                               entered.
  73      */
  74     void exit();
  75
  76     /**
  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.
  80      *
  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
  85      *                               entered.
  86      */
  87     void exit(int depth);
  88
  89     /**
  90      * Read a particular node from the snapshot.
  91      *
  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.
  97      */
  98     Optional<NormalizedNode<?, ?>> readNode(@Nonnull PathArgument child);
  99
 100     /**
 101      * Close this cursor. Attempting any further operations on the cursor will lead
 102      * to undefined behavior.
 103      */
 104     @Override
 105     void close();
 106 }