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     /**
 123      * Constructs new instance of this class with the concrete path.
 124      *
 125      * @param path
 126      *            list of QName instances which specifies exact path to the
 127      *            module node
 128      * @param absolute
 129      *            boolean value which specifies if the path is absolute or
 130      *            relative
 131      *
 132      * @return A SchemaPath instance.
 133      */
 134     public static @NonNull SchemaPath create(final Iterable<QName> path, final boolean absolute) {
 135         return (absolute ? ROOT : SAME).createChild(path);
 136     }
 137
 138     /**
 139      * Constructs new instance of this class with the concrete path.
 140      *
 141      * @param absolute
 142      *            boolean value which specifies if the path is absolute or
 143      *            relative
 144      * @param element
 145      *            a single QName which specifies exact path to the
 146      *            module node
 147      *
 148      * @return A SchemaPath instance.
 149      */
 150     public static @NonNull SchemaPath create(final boolean absolute, final QName element) {
 151         return (absolute ? ROOT : SAME).createChild(element);
 152     }
 153
 154     /**
 155      * Constructs new instance of this class with the concrete path.
 156      *
 157      * @param absolute
 158      *            boolean value which specifies if the path is absolute or
 159      *            relative
 160      * @param path
 161      *            one or more QName instances which specifies exact path to the
 162      *            module node
 163      *
 164      * @return A SchemaPath instance.
 165      */
 166     public static @NonNull SchemaPath create(final boolean absolute, final QName... path) {
 167         return create(Arrays.asList(path), absolute);
 168     }
 169
 170     /**
 171      * Create a child path based on concatenation of this path and a relative path.
 172      *
 173      * @param relative Relative path
 174      * @return A new child path
 175      */
 176     public @NonNull SchemaPath createChild(final Iterable<QName> relative) {
 177         if (Iterables.isEmpty(relative)) {
 178             return this;
 179         }
 180
 181         SchemaPath parentPath = this;
 182         for (QName item : relative) {
 183             parentPath = parentPath.createChild(item);
 184         }
 185
 186         return parentPath;
 187     }
 188
 189     /**
 190      * Create a child path based on concatenation of this path and a relative path.
 191      *
 192      * @param relative Relative SchemaPath
 193      * @return A new child path
 194      */
 195     public @NonNull SchemaPath createChild(final SchemaPath relative) {
 196         checkArgument(!relative.isAbsolute(), "Child creation requires relative path");
 197         return createChild(relative.getPathFromRoot());
 198     }
 199
 200     /**
 201      * Create a child path based on concatenation of this path and an additional path element.
 202      *
 203      * @param element Relative SchemaPath elements
 204      * @return A new child path
 205      */
 206     public abstract @NonNull SchemaPath createChild(QName element);
 207
 208     /**
 209      * Create a child path based on concatenation of this path and additional
 210      * path elements.
 211      *
 212      * @param elements Relative SchemaPath elements
 213      * @return A new child path
 214      */
 215     public @NonNull SchemaPath createChild(final QName... elements) {
 216         return createChild(Arrays.asList(elements));
 217     }
 218
 219     /**
 220      * Returns the list of nodes which need to be traversed to get from the
 221      * starting point (root for absolute SchemaPaths) to the node represented
 222      * by this object.
 223      *
 224      * @return list of <code>qname</code> instances which represents
 225      *         path from the root to the schema node.
 226      */
 227     public List<QName> getPathFromRoot() {
 228         if (qname == null) {
 229             return ImmutableList.of();
 230         }
 231         return parent == null ? ImmutableList.of(qname) : new PathFromRoot(this);
 232     }
 233
 234     /**
 235      * Returns the list of nodes which need to be traversed to get from this
 236      * node to the starting point (root for absolute SchemaPaths).
 237      *
 238      * @return list of <code>qname</code> instances which represents
 239      *         path from the schema node towards the root.
 240      */
 241     public Iterable<QName> getPathTowardsRoot() {
 242         return () -> new UnmodifiableIterator<>() {
 243             private SchemaPath current = SchemaPath.this;
 244
 245             @Override
 246             public boolean hasNext() {
 247                 return current.parent != null;
 248             }
 249
 250             @Override
 251             public QName next() {
 252                 if (current.parent != null) {
 253                     final QName ret = current.qname;
 254                     current = current.parent;
 255                     return ret;
 256                 }
 257
 258                 throw new NoSuchElementException("No more elements available");
 259             }
 260         };
 261     }
 262
 263     /**
 264      * Returns the immediate parent SchemaPath.
 265      *
 266      * @return Parent path, null if this SchemaPath is already toplevel.
 267      */
 268     public SchemaPath getParent() {
 269         return parent;
 270     }
 271
 272     /**
 273      * Get the last component of this path.
 274      *
 275      * @return The last component of this path.
 276      */
 277     public final QName getLastComponent() {
 278         return qname;
 279     }
 280
 281     /**
 282      * Describes whether schema path is|isn't absolute.
 283      *
 284      * @return boolean value which is <code>true</code> if schema path is
 285      *         absolute.
 286      */
 287     public abstract boolean isAbsolute();
 288
 289     /**
 290      * Return this path as a {@link SchemaNodeIdentifier}.
 291      *
 292      * @return A SchemaNodeIdentifier.
 293      * @throws IllegalStateException if this path is empty
 294      */
 295     public final SchemaNodeIdentifier asSchemaNodeIdentifier() {
 296         checkState(qname != null, "Cannot convert empty %s", this);
 297         final List<QName> path = getPathFromRoot();
 298         return isAbsolute() ? Absolute.of(path) : Descendant.of(path);
 299     }
 300
 301     /**
 302      * Return this path as an {@link Absolute} SchemaNodeIdentifier.
 303      *
 304      * @return An SchemaNodeIdentifier.
 305      * @throws IllegalStateException if this path is empty or is not absolute.
 306      */
 307     public final Absolute asAbsolute() {
 308         final SchemaNodeIdentifier ret = asSchemaNodeIdentifier();
 309         if (ret instanceof Absolute) {
 310             return (Absolute) ret;
 311         }
 312         throw new IllegalStateException("Path " + this + " is relative");
 313     }
 314
 315     /**
 316      * Return this path as an {@link Descendant} SchemaNodeIdentifier.
 317      *
 318      * @return An SchemaNodeIdentifier.
 319      * @throws IllegalStateException if this path is empty or is not relative.
 320      */
 321     public final Descendant asDescendant() {
 322         final SchemaNodeIdentifier ret = asSchemaNodeIdentifier();
 323         if (ret instanceof Descendant) {
 324             return (Descendant) ret;
 325         }
 326         throw new IllegalStateException("Path " + this + " is absolute");
 327     }
 328
 329     @Override
 330     public final int hashCode() {
 331         return hash;
 332     }
 333
 334     @Override
 335     public boolean equals(final Object obj) {
 336         if (this == obj) {
 337             return true;
 338         }
 339         if (obj == null) {
 340             return false;
 341         }
 342         if (getClass() != obj.getClass()) {
 343             return false;
 344         }
 345         final SchemaPath other = (SchemaPath) obj;
 346         return Objects.equals(qname, other.qname) && Objects.equals(parent, other.parent);
 347     }
 348
 349     @Override
 350     public final String toString() {
 351         return MoreObjects.toStringHelper(this).add("path", getPathFromRoot()).toString();
 352     }
 353 }