model/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/SchemaPath.java

   1 /*
   2  * Copyright (c) 2013 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.yangtools.yang.model.api;
   9
  10 import static com.google.common.base.Preconditions.checkArgument;
  11 import static com.google.common.base.Preconditions.checkState;
  12 import static java.util.Objects.requireNonNull;
  13
  14 import com.google.common.base.MoreObjects;
  15 import com.google.common.collect.ImmutableList;
  16 import com.google.common.collect.Iterables;
  17 import com.google.common.collect.UnmodifiableIterator;
  18 import java.util.Arrays;
  19 import java.util.List;
  20 import java.util.NoSuchElementException;
  21 import java.util.Objects;
  22 import org.eclipse.jdt.annotation.NonNull;
  23 import org.opendaylight.yangtools.concepts.Immutable;
  24 import org.opendaylight.yangtools.yang.common.QName;
  25 import org.opendaylight.yangtools.yang.model.api.stmt.SchemaNodeIdentifier;
  26 import org.opendaylight.yangtools.yang.model.api.stmt.SchemaNodeIdentifier.Absolute;
  27 import org.opendaylight.yangtools.yang.model.api.stmt.SchemaNodeIdentifier.Descendant;
  28
  29 /**
  30  * Represents unique path to the every node inside the module.
  31  *
  32  * @deprecated This path is not really unique, as it does not handle YANG namespace overlap correctly. There are two
  33  *             different replacements for this class:
  34  *             <ul>
  35  *               <li>{@link SchemaNodeIdentifier} for use in
  36  *                   <a href="https://datatracker.ietf.org/doc/html/rfc7950#section-6.5">YANG schema addressing</a>
  37  *                   contexts</li>
  38  *               <li>{@link EffectiveStatementInference} for use in contexts where the intent is to exchange pointer
  39  *                   to a specific statement. Unlike SchemaPath, though, it does not require additional lookup in most
  40  *                   cases</li>
  41  *             </ul>
  42  *             This class is scheduled for removal in the next major release.
  43  */
  44 @Deprecated(since = "7.0.8", forRemoval = true)
  45 public abstract class SchemaPath implements Immutable {
  46
  47     /**
  48      * An absolute SchemaPath.
  49      */
  50     private static final class AbsoluteSchemaPath extends SchemaPath {
  51         private AbsoluteSchemaPath(final SchemaPath parent, final QName qname) {
  52             super(parent, qname);
  53         }
  54
  55         @Override
  56         public boolean isAbsolute() {
  57             return true;
  58         }
  59
  60         @Override
  61         public AbsoluteSchemaPath createChild(final QName element) {
  62             return new AbsoluteSchemaPath(this, requireNonNull(element));
  63         }
  64     }
  65
  66     /**
  67      * A relative SchemaPath.
  68      */
  69     private static final class RelativeSchemaPath extends SchemaPath {
  70         private RelativeSchemaPath(final SchemaPath parent, final QName qname) {
  71             super(parent, qname);
  72         }
  73
  74         @Override
  75         public boolean isAbsolute() {
  76             return false;
  77         }
  78
  79         @Override
  80         public RelativeSchemaPath createChild(final QName element) {
  81             return new RelativeSchemaPath(this, requireNonNull(element));
  82         }
  83     }
  84
  85     /**
  86      * Shared instance of the conceptual root schema node.
  87      */
  88     public static final @NonNull SchemaPath ROOT = new AbsoluteSchemaPath(null, null);
  89
  90     /**
  91      * Shared instance of the "same" relative schema node.
  92      */
  93     public static final @NonNull SchemaPath SAME = new RelativeSchemaPath(null, null);
  94
  95     /**
  96      * Parent path.
  97      */
  98     private final SchemaPath parent;
  99
 100     /**
 101      * This component.
 102      */
 103     private final QName qname;
 104
 105     /**
 106      * Cached hash code. We can use this since we are immutable.
 107      */
 108     private final int hash;
 109
 110     SchemaPath(final SchemaPath parent, final QName qname) {
 111         this.parent = parent;
 112         this.qname = qname;
 113
 114         int tmp = Objects.hashCode(parent);
 115         if (qname != null) {
 116             tmp = tmp * 31 + qname.hashCode();
 117         }
 118
 119         hash = tmp;
 120     }
 121
 122     public static @NonNull SchemaPath of(final SchemaNodeIdentifier path) {
 123         if (path instanceof Absolute) {
 124             return of((Absolute) path);
 125         } else if (path instanceof Descendant) {
 126             return of((Descendant) path);
 127         } else {
 128             throw new IllegalStateException("Unexpected path " + requireNonNull(path));
 129         }
 130     }
 131
 132     public static @NonNull SchemaPath of(final Absolute path) {
 133         return SchemaPath.ROOT.createChild(path.getNodeIdentifiers());
 134     }
 135
 136     public static @NonNull SchemaPath of(final Descendant path) {
 137         return SchemaPath.SAME.createChild(path.getNodeIdentifiers());
 138     }
 139
 140     /**
 141      * Constructs new instance of this class with the concrete path.
 142      *
 143      * @param path
 144      *            list of QName instances which specifies exact path to the
 145      *            module node
 146      * @param absolute
 147      *            boolean value which specifies if the path is absolute or
 148      *            relative
 149      *
 150      * @return A SchemaPath instance.
 151      */
 152     public static @NonNull SchemaPath create(final Iterable<QName> path, final boolean absolute) {
 153         return (absolute ? ROOT : SAME).createChild(path);
 154     }
 155
 156     /**
 157      * Constructs new instance of this class with the concrete path.
 158      *
 159      * @param absolute
 160      *            boolean value which specifies if the path is absolute or
 161      *            relative
 162      * @param element
 163      *            a single QName which specifies exact path to the
 164      *            module node
 165      *
 166      * @return A SchemaPath instance.
 167      */
 168     public static @NonNull SchemaPath create(final boolean absolute, final QName element) {
 169         return (absolute ? ROOT : SAME).createChild(element);
 170     }
 171
 172     /**
 173      * Constructs new instance of this class with the concrete path.
 174      *
 175      * @param absolute
 176      *            boolean value which specifies if the path is absolute or
 177      *            relative
 178      * @param path
 179      *            one or more QName instances which specifies exact path to the
 180      *            module node
 181      *
 182      * @return A SchemaPath instance.
 183      */
 184     public static @NonNull SchemaPath create(final boolean absolute, final QName... path) {
 185         return create(Arrays.asList(path), absolute);
 186     }
 187
 188     /**
 189      * Create a child path based on concatenation of this path and a relative path.
 190      *
 191      * @param relative Relative path
 192      * @return A new child path
 193      */
 194     public @NonNull SchemaPath createChild(final Iterable<QName> relative) {
 195         if (Iterables.isEmpty(relative)) {
 196             return this;
 197         }
 198
 199         SchemaPath parentPath = this;
 200         for (QName item : relative) {
 201             parentPath = parentPath.createChild(item);
 202         }
 203
 204         return parentPath;
 205     }
 206
 207     /**
 208      * Create a child path based on concatenation of this path and a relative path.
 209      *
 210      * @param relative Relative SchemaPath
 211      * @return A new child path
 212      */
 213     public @NonNull SchemaPath createChild(final SchemaPath relative) {
 214         checkArgument(!relative.isAbsolute(), "Child creation requires relative path");
 215         return createChild(relative.getPathFromRoot());
 216     }
 217
 218     /**
 219      * Create a child path based on concatenation of this path and an additional path element.
 220      *
 221      * @param element Relative SchemaPath elements
 222      * @return A new child path
 223      */
 224     public abstract @NonNull SchemaPath createChild(QName element);
 225
 226     /**
 227      * Create a child path based on concatenation of this path and additional
 228      * path elements.
 229      *
 230      * @param elements Relative SchemaPath elements
 231      * @return A new child path
 232      */
 233     public @NonNull SchemaPath createChild(final QName... elements) {
 234         return createChild(Arrays.asList(elements));
 235     }
 236
 237     /**
 238      * Returns the list of nodes which need to be traversed to get from the
 239      * starting point (root for absolute SchemaPaths) to the node represented
 240      * by this object.
 241      *
 242      * @return list of <code>qname</code> instances which represents
 243      *         path from the root to the schema node.
 244      */
 245     public List<QName> getPathFromRoot() {
 246         if (qname == null) {
 247             return ImmutableList.of();
 248         }
 249         return parent == null ? ImmutableList.of(qname) : new PathFromRoot(this);
 250     }
 251
 252     /**
 253      * Returns the list of nodes which need to be traversed to get from this
 254      * node to the starting point (root for absolute SchemaPaths).
 255      *
 256      * @return list of <code>qname</code> instances which represents
 257      *         path from the schema node towards the root.
 258      */
 259     public Iterable<QName> getPathTowardsRoot() {
 260         return () -> new UnmodifiableIterator<>() {
 261             private SchemaPath current = SchemaPath.this;
 262
 263             @Override
 264             public boolean hasNext() {
 265                 return current.parent != null;
 266             }
 267
 268             @Override
 269             public QName next() {
 270                 if (current.parent != null) {
 271                     final QName ret = current.qname;
 272                     current = current.parent;
 273                     return ret;
 274                 }
 275
 276                 throw new NoSuchElementException("No more elements available");
 277             }
 278         };
 279     }
 280
 281     /**
 282      * Returns the immediate parent SchemaPath.
 283      *
 284      * @return Parent path, null if this SchemaPath is already toplevel.
 285      */
 286     public SchemaPath getParent() {
 287         return parent;
 288     }
 289
 290     /**
 291      * Get the last component of this path.
 292      *
 293      * @return The last component of this path.
 294      */
 295     public final QName getLastComponent() {
 296         return qname;
 297     }
 298
 299     /**
 300      * Describes whether schema path is|isn't absolute.
 301      *
 302      * @return boolean value which is <code>true</code> if schema path is
 303      *         absolute.
 304      */
 305     public abstract boolean isAbsolute();
 306
 307     /**
 308      * Return this path as a {@link SchemaNodeIdentifier}.
 309      *
 310      * @return A SchemaNodeIdentifier.
 311      * @throws IllegalStateException if this path is empty
 312      */
 313     public final SchemaNodeIdentifier asSchemaNodeIdentifier() {
 314         checkState(qname != null, "Cannot convert empty %s", this);
 315         final List<QName> path = getPathFromRoot();
 316         return isAbsolute() ? Absolute.of(path) : Descendant.of(path);
 317     }
 318
 319     /**
 320      * Return this path as an {@link Absolute} SchemaNodeIdentifier.
 321      *
 322      * @return An SchemaNodeIdentifier.
 323      * @throws IllegalStateException if this path is empty or is not absolute.
 324      */
 325     public final Absolute asAbsolute() {
 326         final SchemaNodeIdentifier ret = asSchemaNodeIdentifier();
 327         if (ret instanceof Absolute) {
 328             return (Absolute) ret;
 329         }
 330         throw new IllegalStateException("Path " + this + " is relative");
 331     }
 332
 333     /**
 334      * Return this path as an {@link Descendant} SchemaNodeIdentifier.
 335      *
 336      * @return An SchemaNodeIdentifier.
 337      * @throws IllegalStateException if this path is empty or is not relative.
 338      */
 339     public final Descendant asDescendant() {
 340         final SchemaNodeIdentifier ret = asSchemaNodeIdentifier();
 341         if (ret instanceof Descendant) {
 342             return (Descendant) ret;
 343         }
 344         throw new IllegalStateException("Path " + this + " is absolute");
 345     }
 346
 347     @Override
 348     public final int hashCode() {
 349         return hash;
 350     }
 351
 352     @Override
 353     public boolean equals(final Object obj) {
 354         if (this == obj) {
 355             return true;
 356         }
 357         if (obj == null) {
 358             return false;
 359         }
 360         if (getClass() != obj.getClass()) {
 361             return false;
 362         }
 363         final SchemaPath other = (SchemaPath) obj;
 364         return Objects.equals(qname, other.qname) && Objects.equals(parent, other.parent);
 365     }
 366
 367     @Override
 368     public final String toString() {
 369         return MoreObjects.toStringHelper(this).add("path", getPathFromRoot()).toString();
 370     }
 371 }