binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeCursor.java

   1 /*
   2  * Copyright (c) 2016 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
   9 package org.opendaylight.mdsal.binding.api;
  10
  11 import com.google.common.annotations.Beta;
  12 import javax.annotation.Nonnull;
  13 import javax.annotation.concurrent.NotThreadSafe;
  14 import org.opendaylight.yangtools.yang.binding.DataContainer;
  15 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier.PathArgument;
  16
  17
  18 /**
  19  * A cursor holding a logical position within a conceptual data tree. It allows operations relative
  20  * to that position, as well as moving the position up or down the tree.
  21  */
  22 @Beta
  23 @NotThreadSafe
  24 public interface DataTreeCursor extends AutoCloseable {
  25     /**
  26      * Move the cursor to the specified child of the current position.
  27      *
  28      * @param child Child identifier
  29      * @throws IllegalArgumentException when specified identifier does not identify a valid child,
  30      *         or if that child is not an instance of {@link DataContainer}.
  31      */
  32     void enter(@Nonnull PathArgument child);
  33
  34     /**
  35      * Move the cursor to the specified child of the current position. This is the equivalent of
  36      * multiple invocations of {@link #enter(PathArgument)}, except the operation is performed all
  37      * at once.
  38      *
  39      * @param path Nested child identifier
  40      * @throws IllegalArgumentException when specified path does not identify a valid child, or if
  41      *         that child is not an instance of {@link DataContainer}.
  42      */
  43     void enter(@Nonnull PathArgument... path);
  44
  45     /**
  46      * Move the cursor to the specified child of the current position. This is equivalent to
  47      * {@link #enter(PathArgument...)}, except it takes an {@link Iterable} argument.
  48      *
  49      * @param path Nested child identifier
  50      * @throws IllegalArgumentException when specified path does not identify a valid child, or if
  51      *         that child is not an instance of {@link DataContainer}.
  52      */
  53     void enter(@Nonnull Iterable<PathArgument> path);
  54
  55     /**
  56      * Move the cursor up to the parent of current position. This is equivalent of invoking
  57      * <code>exit(1)</code>.
  58      *
  59      * @throws IllegalStateException when exiting would violate containment, typically by attempting
  60      *         to exit more levels than previously entered.
  61      */
  62     void exit();
  63
  64     /**
  65      * Move the cursor up by specified amounts of steps from the current position. This is
  66      * equivalent of invoking {@link #exit()} multiple times, except the operation is performed
  67      * atomically.
  68      *
  69      * @param depth number of steps to exit
  70      * @throws IllegalArgumentException when depth is negative.
  71      * @throws IllegalStateException when exiting would violate containment, typically by attempting
  72      *         to exit more levels than previously entered.
  73      */
  74     void exit(int depth);
  75
  76     /**
  77      * Close this cursor. Attempting any further operations on the cursor will lead to undefined
  78      * behavior.
  79      */
  80     @Override
  81     void close();
  82 }