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