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 java.util.Optional;
  12 import org.eclipse.jdt.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 operations relative to that
  19  * position, as well as moving the position up or down the tree. Implementations are expected to be NOT thread-safe.
  20  */
  21 @Beta
  22 public interface DataTreeSnapshotCursor extends AutoCloseable {
  23     /**
  24      * Move the cursor to the specified child of the current position.
  25      *
  26      * @param child Child identifier
  27      * @throws BackendFailedException when an implementation-specific error occurs
  28      *                                while servicing the request.
  29      * @throws IllegalArgumentException when specified identifier does not identify
  30      *                                  a valid child, or if that child is not an
  31      *                                  instance of {@link NormalizedNodeContainer}.
  32      */
  33     void enter(@NonNull PathArgument child);
  34
  35     /**
  36      * Move the cursor to the specified child of the current position. This is
  37      * the equivalent of multiple invocations of {@link #enter(PathArgument)},
  38      * except the operation is performed all at once.
  39      *
  40      * @param path Nested child identifier
  41      * @throws BackendFailedException when an implementation-specific error occurs
  42      *                                while servicing the request.
  43      * @throws IllegalArgumentException when specified path does not identify
  44      *                                  a valid child, or if that child is not an
  45      *                                  instance of {@link NormalizedNodeContainer}.
  46      */
  47     void enter(@NonNull PathArgument... path);
  48
  49     /**
  50      * Move the cursor to the specified child of the current position. This is
  51      * equivalent to {@link #enter(PathArgument...)}, except it takes an {@link Iterable}
  52      * argument.
  53      *
  54      * @param path Nested child identifier
  55      * @throws BackendFailedException when an implementation-specific error occurs
  56      *                                while servicing the request.
  57      * @throws IllegalArgumentException when specified path does not identify
  58      *                                  a valid child, or if that child is not an
  59      *                                  instance of {@link NormalizedNodeContainer}.
  60      */
  61     void enter(@NonNull Iterable<PathArgument> path);
  62
  63     /**
  64      * Move the cursor up to the parent of current position. This is equivalent of
  65      * invoking <code>exit(1)</code>.
  66      *
  67      * @throws IllegalStateException when exiting would violate containment, typically
  68      *                               by attempting to exit more levels than previously
  69      *                               entered.
  70      */
  71     void exit();
  72
  73     /**
  74      * Move the cursor up by specified amounts of steps from the current position.
  75      * This is equivalent of invoking {@link #exit()} multiple times, except the
  76      * operation is performed atomically.
  77      *
  78      * @param depth number of steps to exit
  79      * @throws IllegalArgumentException when depth is negative.
  80      * @throws IllegalStateException when exiting would violate containment, typically
  81      *                               by attempting to exit more levels than previously
  82      *                               entered.
  83      */
  84     void exit(int depth);
  85
  86     /**
  87      * Read a particular node from the snapshot.
  88      *
  89      * @param child Child identifier
  90      * @return Optional result encapsulating the presence and value of the node
  91      * @throws BackendFailedException when implementation-specific error occurs while
  92      *                                servicing the request.
  93      * @throws IllegalArgumentException when specified path does not identify a valid child.
  94      */
  95     Optional<NormalizedNode<?, ?>> readNode(@NonNull PathArgument child);
  96
  97     /**
  98      * Close this cursor. Attempting any further operations on the cursor will lead
  99      * to undefined behavior.
 100      */
 101     @Override
 102     void close();
 103 }