yang/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 com.google.common.base.MoreObjects;
  11 import com.google.common.base.MoreObjects.ToStringHelper;
  12 import com.google.common.base.Preconditions;
  13 import com.google.common.collect.ImmutableList;
  14 import com.google.common.collect.Iterables;
  15 import com.google.common.collect.Lists;
  16 import com.google.common.collect.UnmodifiableIterator;
  17 import java.util.ArrayList;
  18 import java.util.Arrays;
  19 import java.util.Iterator;
  20 import java.util.List;
  21 import java.util.NoSuchElementException;
  22 import java.util.Objects;
  23 import java.util.concurrent.atomic.AtomicReferenceFieldUpdater;
  24 import org.opendaylight.yangtools.concepts.Immutable;
  25 import org.opendaylight.yangtools.yang.common.QName;
  26
  27 /**
  28  * Represents unique path to the every node inside the module.
  29  */
  30 public abstract class SchemaPath implements Immutable {
  31
  32     /**
  33      * An absolute SchemaPath.
  34      */
  35     private static final class AbsoluteSchemaPath extends SchemaPath {
  36         private AbsoluteSchemaPath(final SchemaPath parent, final QName qname) {
  37             super(parent, qname);
  38         }
  39
  40         @Override
  41         public boolean isAbsolute() {
  42             return true;
  43         }
  44
  45         @Override
  46         protected SchemaPath createInstance(final SchemaPath parent, final QName qname) {
  47             return new AbsoluteSchemaPath(parent, Preconditions.checkNotNull(qname));
  48         }
  49     }
  50
  51     /**
  52      * A relative SchemaPath.
  53      */
  54     private static final class RelativeSchemaPath extends SchemaPath {
  55         private RelativeSchemaPath(final SchemaPath parent, final QName qname) {
  56             super(parent, qname);
  57         }
  58
  59         @Override
  60         public boolean isAbsolute() {
  61             return false;
  62         }
  63
  64         @Override
  65         protected SchemaPath createInstance(final SchemaPath parent, final QName qname) {
  66             return new RelativeSchemaPath(parent, Preconditions.checkNotNull(qname));
  67         }
  68     }
  69
  70     @SuppressWarnings("rawtypes")
  71     private static final AtomicReferenceFieldUpdater<SchemaPath, ImmutableList> LEGACYPATH_UPDATER =
  72             AtomicReferenceFieldUpdater.newUpdater(SchemaPath.class, ImmutableList.class, "legacyPath");
  73
  74     /**
  75      * Shared instance of the conceptual root schema node.
  76      */
  77     public static final SchemaPath ROOT = new AbsoluteSchemaPath(null, null);
  78
  79     /**
  80      * Shared instance of the "same" relative schema node.
  81      */
  82     public static final SchemaPath SAME = new RelativeSchemaPath(null, null);
  83
  84     /**
  85      * Parent path.
  86      */
  87     private final SchemaPath 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      * @deprecated This constructor will be hidden in a future release.
 107      * @param parent
 108      * @param qname
 109      */
 110     @Deprecated
 111     protected SchemaPath(final SchemaPath parent, final QName qname) {
 112         this.parent = parent;
 113         this.qname = qname;
 114
 115         int h = Objects.hashCode(parent);
 116         if (qname != null) {
 117             h = h * 31 + qname.hashCode();
 118         }
 119
 120         hash = h;
 121     }
 122
 123     private ImmutableList<QName> getLegacyPath() {
 124         ImmutableList<QName> ret = legacyPath;
 125         if (ret == null) {
 126             final List<QName> tmp = new ArrayList<>();
 127             for (QName qname : getPathTowardsRoot()) {
 128                 tmp.add(qname);
 129             }
 130             ret = ImmutableList.copyOf(Lists.reverse(tmp));
 131             LEGACYPATH_UPDATER.lazySet(this, ret);
 132         }
 133
 134         return ret;
 135     }
 136
 137     /**
 138      * Returns the complete path to schema node.
 139      *
 140      * @return list of <code>QName</code> instances which represents complete
 141      *         path to schema node
 142      *
 143      * @deprecated Use {@link #getPathFromRoot()} instead.
 144      */
 145     @Deprecated
 146     public List<QName> getPath() {
 147         return getLegacyPath();
 148     }
 149
 150     /**
 151      * Constructs new instance of this class with the concrete path.
 152      *
 153      * @param path
 154      *            list of QName instances which specifies exact path to the
 155      *            module node
 156      * @param absolute
 157      *            boolean value which specifies if the path is absolute or
 158      *            relative
 159      *
 160      * @return A SchemaPath instance.
 161      */
 162     public static SchemaPath create(final Iterable<QName> path, final boolean absolute) {
 163         final SchemaPath parent = absolute ? ROOT : SAME;
 164         return parent.createChild(path);
 165     }
 166
 167     /**
 168      * Constructs new instance of this class with the concrete path.
 169      *
 170      * @param absolute
 171      *            boolean value which specifies if the path is absolute or
 172      *            relative
 173      * @param path
 174      *            one or more QName instances which specifies exact path to the
 175      *            module node
 176      *
 177      * @return A SchemaPath instance.
 178      */
 179     public static SchemaPath create(final boolean absolute, final QName... path) {
 180         return create(Arrays.asList(path), absolute);
 181     }
 182
 183     /**
 184      * Create a new instance.
 185      *
 186      * @param parent Parent SchemaPath
 187      * @param qname next path element
 188      * @return A new SchemaPath instance
 189      */
 190     protected abstract SchemaPath createInstance(SchemaPath parent, QName qname);
 191
 192     /**
 193      * Create a child path based on concatenation of this path and a relative path.
 194      *
 195      * @param relative Relative path
 196      * @return A new child path
 197      */
 198     public SchemaPath createChild(final Iterable<QName> relative) {
 199         if (Iterables.isEmpty(relative)) {
 200             return this;
 201         }
 202
 203         SchemaPath parentPath = this;
 204         for (QName qname : relative) {
 205             parentPath = parentPath.createInstance(parentPath, qname);
 206         }
 207
 208         return parentPath;
 209     }
 210
 211     /**
 212      * Create a child path based on concatenation of this path and a relative path.
 213      *
 214      * @param relative Relative SchemaPath
 215      * @return A new child path
 216      */
 217     public SchemaPath createChild(final SchemaPath relative) {
 218         Preconditions.checkArgument(!relative.isAbsolute(), "Child creation requires relative path");
 219
 220         SchemaPath parentPath = this;
 221         for (QName qname : relative.getPathFromRoot()) {
 222             parentPath = parentPath.createInstance(parentPath, qname);
 223         }
 224
 225         return parentPath;
 226     }
 227
 228     /**
 229      * Create a child path based on concatenation of this path and additional
 230      * path elements.
 231      *
 232      * @param elements Relative SchemaPath elements
 233      * @return A new child path
 234      */
 235     public SchemaPath createChild(final QName... elements) {
 236         return createChild(Arrays.asList(elements));
 237     }
 238
 239     /**
 240      * Returns the list of nodes which need to be traversed to get from the
 241      * starting point (root for absolute SchemaPaths) to the node represented
 242      * by this object.
 243      *
 244      * @return list of <code>qname</code> instances which represents
 245      *         path from the root to the schema node.
 246      */
 247     public Iterable<QName> getPathFromRoot() {
 248         return getLegacyPath();
 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 Iterable<QName>() {
 260             @Override
 261             public Iterator<QName> iterator() {
 262                 return new UnmodifiableIterator<QName>() {
 263                     private SchemaPath current = SchemaPath.this;
 264
 265                     @Override
 266                     public boolean hasNext() {
 267                         return current.parent != null;
 268                     }
 269
 270                     @Override
 271                     public QName next() {
 272                         if (current.parent != null) {
 273                             final QName ret = current.qname;
 274                             current = current.parent;
 275                             return ret;
 276                         } else {
 277                             throw new NoSuchElementException("No more elements available");
 278                         }
 279                     }
 280                 };
 281             }
 282         };
 283     }
 284
 285     /**
 286      * Returns the immediate parent SchemaPath.
 287      *
 288      * @return Parent path, null if this SchemaPath is already toplevel.
 289      */
 290     public SchemaPath getParent() {
 291         return parent;
 292     }
 293
 294     /**
 295      * Get the last component of this path.
 296      *
 297      * @return The last component of this path.
 298      */
 299     public final QName getLastComponent() {
 300         return qname;
 301     }
 302
 303     /**
 304      * Describes whether schema path is|isn't absolute.
 305      *
 306      * @return boolean value which is <code>true</code> if schema path is
 307      *         absolute.
 308      */
 309     public abstract boolean isAbsolute();
 310
 311     @Override
 312     public final int hashCode() {
 313         return hash;
 314     }
 315
 316     @Override
 317     public boolean equals(final Object obj) {
 318         if (this == obj) {
 319             return true;
 320         }
 321         if (obj == null) {
 322             return false;
 323         }
 324         if (getClass() != obj.getClass()) {
 325             return false;
 326         }
 327         final SchemaPath other = (SchemaPath) obj;
 328         return Objects.equals(qname, other.qname) && Objects.equals(parent, other.parent);
 329     }
 330
 331     @Override
 332     public final String toString() {
 333         return addToStringAttributes(MoreObjects.toStringHelper(this)).toString();
 334     }
 335
 336     protected ToStringHelper addToStringAttributes(final ToStringHelper toStringHelper) {
 337         return toStringHelper.add("path", getPathFromRoot());
 338     }
 339 }