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