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