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