dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataTreeCursor.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.mdsal.dom.api;
   9
  10 import com.google.common.annotations.Beta;
  11 import java.util.Arrays;
  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.NormalizedNodeContainer;
  16
  17 /**
  18  * A cursor holding a logical position within a conceptual data tree. It allows operations relative
  19  * to that position, as well as moving the position up or down the tree.
  20  */
  21 @Beta
  22 @NotThreadSafe
  23 public interface DOMDataTreeCursor 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 NormalizedNodeContainer}.
  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 NormalizedNodeContainer}.
  41      */
  42     default void enter(@Nonnull final PathArgument... path) {
  43         enter(Arrays.asList(path));
  44     }
  45
  46     /**
  47      * Move the cursor to the specified child of the current position. This is equivalent to
  48      * {@link #enter(PathArgument...)}, except it takes an {@link Iterable} argument.
  49      *
  50      * @param path Nested child identifier
  51      * @throws IllegalArgumentException when specified path does not identify a valid child, or if
  52      *         that child is not an instance of {@link NormalizedNodeContainer}.
  53      */
  54     void enter(@Nonnull Iterable<PathArgument> path);
  55
  56     /**
  57      * Move the cursor up to the parent of current position. This is equivalent of invoking
  58      * <code>exit(1)</code>.
  59      *
  60      * @throws IllegalStateException when exiting would violate containment, typically by attempting
  61      *         to exit more levels than previously entered.
  62      */
  63     void exit();
  64
  65     /**
  66      * Move the cursor up by specified amounts of steps from the current position. This is
  67      * equivalent of invoking {@link #exit()} multiple times, except the operation is performed
  68      * atomically.
  69      *
  70      * @param depth number of steps to exit
  71      * @throws IllegalArgumentException when depth is negative.
  72      * @throws IllegalStateException when exiting would violate containment, typically by attempting
  73      *         to exit more levels than previously entered.
  74      */
  75     void exit(int depth);
  76
  77     /**
  78      * Close this cursor. Attempting any further operations on the cursor will lead to undefined
  79      * behavior.
  80      */
  81     @Override
  82     void close();
  83 }