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  * @deprecated This interface is scheduled for removal in the next major release.
  24  */
  25 @Beta
  26 @Deprecated(forRemoval = true)
  27 public interface DOMDataTreeCursor extends AutoCloseable {
  28     /**
  29      * Move the cursor to the specified child of the current position.
  30      *
  31      * @param child Child identifier
  32      * @throws IllegalArgumentException when specified identifier does not identify a valid child,
  33      *         or if that child is not an instance of {@link NormalizedNodeContainer}.
  34      */
  35     void enter(@NonNull PathArgument child);
  36
  37     /**
  38      * Move the cursor to the specified child of the current position. This is the equivalent of
  39      * multiple invocations of {@link #enter(PathArgument)}, except the operation is performed all
  40      * at once.
  41      *
  42      * @param path Nested child identifier
  43      * @throws IllegalArgumentException when specified path does not identify a valid child, or if
  44      *         that child is not an instance of {@link NormalizedNodeContainer}.
  45      */
  46     default void enter(final @NonNull PathArgument... path) {
  47         enter(Arrays.asList(path));
  48     }
  49
  50     /**
  51      * Move the cursor to the specified child of the current position. This is equivalent to
  52      * {@link #enter(PathArgument...)}, except it takes an {@link Iterable} argument.
  53      *
  54      * @param path Nested child identifier
  55      * @throws IllegalArgumentException when specified path does not identify a valid child, or if
  56      *         that child is not an instance of {@link NormalizedNodeContainer}.
  57      */
  58     void enter(@NonNull Iterable<PathArgument> path);
  59
  60     /**
  61      * Move the cursor up to the parent of current position. This is equivalent of invoking
  62      * <code>exit(1)</code>.
  63      *
  64      * @throws IllegalStateException when exiting would violate containment, typically by attempting
  65      *         to exit more levels than previously entered.
  66      */
  67     void exit();
  68
  69     /**
  70      * Move the cursor up by specified amounts of steps from the current position. This is
  71      * equivalent of invoking {@link #exit()} multiple times, except the operation is performed
  72      * atomically.
  73      *
  74      * @param depth number of steps to exit
  75      * @throws IllegalArgumentException when depth is negative.
  76      * @throws IllegalStateException when exiting would violate containment, typically by attempting
  77      *         to exit more levels than previously entered.
  78      */
  79     void exit(int depth);
  80
  81     /**
  82      * Close this cursor. Attempting any further operations on the cursor will lead to undefined
  83      * behavior.
  84      */
  85     @Override
  86     void close();
  87 }