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