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