yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/stmt/SchemaNodeIdentifier.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.yangtools.yang.model.api.stmt;
   9
  10 import static com.google.common.base.Preconditions.checkArgument;
  11 import static java.util.Objects.requireNonNull;
  12
  13 import com.google.common.base.MoreObjects;
  14 import com.google.common.base.MoreObjects.ToStringHelper;
  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.NoSuchElementException;
  20 import java.util.Objects;
  21 import java.util.concurrent.atomic.AtomicReferenceFieldUpdater;
  22 import org.opendaylight.yangtools.concepts.Immutable;
  23 import org.opendaylight.yangtools.yang.common.QName;
  24 import org.opendaylight.yangtools.yang.model.api.SchemaPath;
  25
  26 /**
  27  * Represents unique path to the every schema node inside the schema node identifier namespace. This concept is defined
  28  * in <a href="https://tools.ietf.org/html/rfc7950#section-6.5">RFC7950</a>.
  29  */
  30 public abstract class SchemaNodeIdentifier implements Immutable {
  31     /**
  32      * An absolute schema node identifier.
  33      */
  34     public static final class Absolute extends SchemaNodeIdentifier {
  35         private Absolute(final SchemaNodeIdentifier parent, final QName qname) {
  36             super(parent, qname);
  37         }
  38
  39         @Override
  40         public boolean isAbsolute() {
  41             return true;
  42         }
  43
  44         @Override
  45         public Absolute createChild(final QName element) {
  46             return new Absolute(this, requireNonNull(element));
  47         }
  48     }
  49
  50     /**
  51      * A descendant schema node identifier.
  52      */
  53     public static final class Descendant extends SchemaNodeIdentifier {
  54         private Descendant(final SchemaNodeIdentifier parent, final QName qname) {
  55             super(parent, qname);
  56         }
  57
  58         @Override
  59         public boolean isAbsolute() {
  60             return false;
  61         }
  62
  63         @Override
  64         public Descendant createChild(final QName element) {
  65             return new Descendant(this, requireNonNull(element));
  66         }
  67     }
  68
  69     @SuppressWarnings("rawtypes")
  70     private static final AtomicReferenceFieldUpdater<SchemaNodeIdentifier, ImmutableList> LEGACYPATH_UPDATER =
  71             AtomicReferenceFieldUpdater.newUpdater(SchemaNodeIdentifier.class, ImmutableList.class, "legacyPath");
  72     private static final AtomicReferenceFieldUpdater<SchemaNodeIdentifier, SchemaPath> SCHEMAPATH_UPDATER =
  73             AtomicReferenceFieldUpdater.newUpdater(SchemaNodeIdentifier.class, SchemaPath.class, "schemaPath");
  74     /**
  75      * Shared instance of the conceptual root schema node.
  76      */
  77     public static final Absolute ROOT = new Absolute(null, null);
  78
  79     /**
  80      * Shared instance of the "same" relative schema node.
  81      */
  82     public static final Descendant SAME = new Descendant(null, null);
  83
  84     /**
  85      * Parent path.
  86      */
  87     private final SchemaNodeIdentifier parent;
  88
  89     /**
  90      * This component.
  91      */
  92     private final QName qname;
  93
  94     /**
  95      * Cached hash code. We can use this since we are immutable.
  96      */
  97     private final int hash;
  98
  99     /**
 100      * Cached legacy path, filled-in when {@link #getPath()} or {@link #getPathTowardsRoot()}
 101      * is invoked.
 102      */
 103     private volatile ImmutableList<QName> legacyPath;
 104
 105     /**
 106      * Cached SchemaPath.
 107      */
 108     private volatile SchemaPath schemaPath;
 109
 110     SchemaNodeIdentifier(final SchemaNodeIdentifier 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     private ImmutableList<QName> getLegacyPath() {
 123         ImmutableList<QName> ret = legacyPath;
 124         if (ret == null) {
 125             ret = ImmutableList.copyOf(getPathTowardsRoot()).reverse();
 126             LEGACYPATH_UPDATER.lazySet(this, ret);
 127         }
 128
 129         return ret;
 130     }
 131
 132     /**
 133      * Constructs new instance of this class with the concrete path.
 134      *
 135      * @param path
 136      *            list of QName instances which specifies exact path to the
 137      *            module node
 138      * @param absolute
 139      *            boolean value which specifies if the path is absolute or
 140      *            relative
 141      *
 142      * @return A SchemaNodeIdentifier instance.
 143      */
 144     public static SchemaNodeIdentifier create(final Iterable<QName> path, final boolean absolute) {
 145         final SchemaNodeIdentifier parent = absolute ? ROOT : SAME;
 146         return parent.createChild(path);
 147     }
 148
 149     /**
 150      * Constructs new instance of this class with the concrete path.
 151      *
 152      * @param absolute
 153      *            boolean value which specifies if the path is absolute or
 154      *            relative
 155      * @param path
 156      *            one or more QName instances which specifies exact path to the
 157      *            module node
 158      *
 159      * @return A SchemaPath instance.
 160      */
 161     public static SchemaNodeIdentifier create(final boolean absolute, final QName... path) {
 162         return create(Arrays.asList(path), absolute);
 163     }
 164
 165     /**
 166      * Create a child path based on concatenation of this path and a relative path.
 167      *
 168      * @param relative Relative path
 169      * @return A new child path
 170      */
 171     public SchemaNodeIdentifier createChild(final Iterable<QName> relative) {
 172         if (Iterables.isEmpty(relative)) {
 173             return this;
 174         }
 175
 176         SchemaNodeIdentifier parentNode = this;
 177         for (QName item : relative) {
 178             parentNode = parentNode.createChild(item);
 179         }
 180
 181         return parentNode;
 182     }
 183
 184     /**
 185      * Create a child path based on concatenation of this path and a relative path.
 186      *
 187      * @param relative Relative SchemaPath
 188      * @return A new child path
 189      */
 190     public SchemaNodeIdentifier createChild(final SchemaNodeIdentifier relative) {
 191         checkArgument(!relative.isAbsolute(), "Child creation requires relative path");
 192         return createChild(relative.getPathFromRoot());
 193     }
 194
 195     /**
 196      * Create a child path based on concatenation of this path and an additional path element.
 197      *
 198      * @param element Next SchemaPath element
 199      * @return A new child path
 200      */
 201     public abstract SchemaNodeIdentifier createChild(QName element);
 202
 203     /**
 204      * Create a child path based on concatenation of this path and additional
 205      * path elements.
 206      *
 207      * @param elements Relative SchemaPath elements
 208      * @return A new child path
 209      */
 210     public SchemaNodeIdentifier createChild(final QName... elements) {
 211         return createChild(Arrays.asList(elements));
 212     }
 213
 214     /**
 215      * Returns the list of nodes which need to be traversed to get from the
 216      * starting point (root for absolute SchemaPaths) to the node represented
 217      * by this object.
 218      *
 219      * @return list of <code>qname</code> instances which represents
 220      *         path from the root to the schema node.
 221      */
 222     public Iterable<QName> getPathFromRoot() {
 223         return getLegacyPath();
 224     }
 225
 226     /**
 227      * Returns the list of nodes which need to be traversed to get from this
 228      * node to the starting point (root for absolute SchemaPaths).
 229      *
 230      * @return list of <code>qname</code> instances which represents
 231      *         path from the schema node towards the root.
 232      */
 233     public Iterable<QName> getPathTowardsRoot() {
 234         return () -> new UnmodifiableIterator<>() {
 235             private SchemaNodeIdentifier current = SchemaNodeIdentifier.this;
 236
 237             @Override
 238             public boolean hasNext() {
 239                 return current.parent != null;
 240             }
 241
 242             @Override
 243             public QName next() {
 244                 if (current.parent != null) {
 245                     final QName ret = current.qname;
 246                     current = current.parent;
 247                     return ret;
 248                 } else {
 249                     throw new NoSuchElementException("No more elements available");
 250                 }
 251             }
 252         };
 253     }
 254
 255     /**
 256      * Returns the immediate parent SchemaPath.
 257      *
 258      * @return Parent path, null if this SchemaPath is already toplevel.
 259      */
 260     public SchemaNodeIdentifier getParent() {
 261         return parent;
 262     }
 263
 264     /**
 265      * Get the last component of this path.
 266      *
 267      * @return The last component of this path.
 268      */
 269     public final QName getLastComponent() {
 270         return qname;
 271     }
 272
 273     private SchemaPath createSchemaPath() {
 274         final SchemaPath newPath;
 275         if (parent == null) {
 276             final SchemaPath parentPath = isAbsolute() ? SchemaPath.ROOT : SchemaPath.SAME;
 277             newPath = qname == null ? parentPath : parentPath.createChild(qname);
 278         } else {
 279             newPath = parent.asSchemaPath().createChild(qname);
 280         }
 281
 282         return SCHEMAPATH_UPDATER.compareAndSet(this, null, newPath) ? newPath : schemaPath;
 283     }
 284
 285     /**
 286      * Create the {@link SchemaPath} equivalent of this identifier.
 287      *
 288      * @return SchemaPath equivalent.
 289      */
 290     public final SchemaPath asSchemaPath() {
 291         final SchemaPath ret = schemaPath;
 292         return ret != null ? ret : createSchemaPath();
 293     }
 294
 295     /**
 296      * Describes whether schema node identifier is|isn't absolute.
 297      *
 298      * @return boolean value which is <code>true</code> if schema path is
 299      *         absolute.
 300      */
 301     public abstract boolean isAbsolute();
 302
 303     @Override
 304     public final int hashCode() {
 305         return hash;
 306     }
 307
 308     @Override
 309     public final boolean equals(final Object obj) {
 310         if (this == obj) {
 311             return true;
 312         }
 313         if (obj == null) {
 314             return false;
 315         }
 316         if (getClass() != obj.getClass()) {
 317             return false;
 318         }
 319         final SchemaNodeIdentifier other = (SchemaNodeIdentifier) obj;
 320         return Objects.equals(qname, other.qname) && Objects.equals(parent, other.parent);
 321     }
 322
 323     @Override
 324     public final String toString() {
 325         return addToStringAttributes(MoreObjects.toStringHelper(this)).toString();
 326     }
 327
 328     protected ToStringHelper addToStringAttributes(final ToStringHelper toStringHelper) {
 329         return toStringHelper.add("path", getPathFromRoot());
 330     }
 331 }