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.Objects;
  11 import com.google.common.base.Objects.ToStringHelper;
  12 import com.google.common.base.Preconditions;
  13 import com.google.common.collect.ImmutableList;
  14 import com.google.common.collect.Iterables;
  15
  16 import java.util.Arrays;
  17 import java.util.Iterator;
  18 import java.util.List;
  19 import java.util.NoSuchElementException;
  20
  21 import org.opendaylight.yangtools.concepts.Immutable;
  22 import org.opendaylight.yangtools.yang.common.QName;
  23
  24 /**
  25  * Represents unique path to the every node inside the module.
  26  */
  27 public abstract class SchemaPath implements Immutable {
  28     /**
  29      * An absolute SchemaPath.
  30      */
  31     private static final class AbsoluteSchemaPath extends SchemaPath {
  32         private AbsoluteSchemaPath(final SchemaPath parent, final QName qname) {
  33             super(parent, qname);
  34         }
  35
  36         @Override
  37         public boolean isAbsolute() {
  38             return true;
  39         }
  40
  41         @Override
  42         protected SchemaPath createInstance(final SchemaPath parent, final QName qname) {
  43             return new AbsoluteSchemaPath(parent, qname);
  44         }
  45     }
  46
  47     /**
  48      * A relative SchemaPath.
  49      */
  50     private static final class RelativeSchemaPath extends SchemaPath {
  51         private RelativeSchemaPath(final SchemaPath parent, final QName qname) {
  52             super(parent, qname);
  53         }
  54
  55         @Override
  56         public boolean isAbsolute() {
  57             return false;
  58         }
  59
  60         @Override
  61         protected SchemaPath createInstance(final SchemaPath parent, final QName qname) {
  62             return new RelativeSchemaPath(parent, qname);
  63         }
  64     }
  65
  66     /**
  67      * Shared instance of the conceptual root schema node.
  68      */
  69     public static final SchemaPath ROOT = new AbsoluteSchemaPath(null, null);
  70
  71     /**
  72      * Shared instance of the "same" relative schema node.
  73      */
  74     public static final SchemaPath SAME = new RelativeSchemaPath(null, null);
  75
  76     /**
  77      * Parent path.
  78      */
  79     private final SchemaPath parent;
  80
  81     /**
  82      * This component.
  83      */
  84     private final QName qname;
  85
  86     /**
  87      * Cached hash code. We can use this since we are immutable.
  88      */
  89     private final int hash;
  90
  91     /**
  92      * Cached legacy path, filled-in when {@link #getPath()} or {@link #getPathTowardsRoot()}
  93      * is invoked.
  94      */
  95     private ImmutableList<QName> legacyPath;
  96
  97     private ImmutableList<QName> getLegacyPath() {
  98         if (legacyPath == null) {
  99             legacyPath = ImmutableList.copyOf(getPathTowardsRoot()).reverse();
 100         }
 101
 102         return legacyPath;
 103     }
 104
 105     /**
 106      * Returns the complete path to schema node.
 107      *
 108      * @return list of <code>QName</code> instances which represents complete
 109      *         path to schema node
 110      *
 111      * @deprecated Use {@link #getPathFromRoot()} instead.
 112      */
 113     @Deprecated
 114     public List<QName> getPath() {
 115         return getLegacyPath();
 116     }
 117
 118     protected SchemaPath(final SchemaPath parent, final QName qname) {
 119         this.parent = parent;
 120         this.qname = qname;
 121
 122         int h = parent == null ? 0 : parent.hashCode();
 123         if (qname != null) {
 124             h = h * 31 + qname.hashCode();
 125         }
 126
 127         hash = h;
 128     }
 129
 130     /**
 131      * Constructs new instance of this class with the concrete path.
 132      *
 133      * @param path
 134      *            list of QName instances which specifies exact path to the
 135      *            module node
 136      * @param absolute
 137      *            boolean value which specifies if the path is absolute or
 138      *            relative
 139      *
 140      * @return A SchemaPath instance.
 141      */
 142     public static SchemaPath create(final Iterable<QName> path, final boolean absolute) {
 143         final SchemaPath parent = absolute ? ROOT : SAME;
 144         return parent.createChild(path);
 145     }
 146
 147     /**
 148      * Constructs new instance of this class with the concrete path.
 149      *
 150      * @param absolute
 151      *            boolean value which specifies if the path is absolute or
 152      *            relative
 153      * @param path
 154      *            one or more QName instances which specifies exact path to the
 155      *            module node
 156      *
 157      * @return A SchemaPath instance.
 158      */
 159     public static SchemaPath create(final boolean absolute, final QName... path) {
 160         return create(Arrays.asList(path), absolute);
 161     }
 162
 163     /**
 164      * Create a new instance.
 165      *
 166      * @param path path from root
 167      * @param hash intended hash code
 168      * @return A new SchemaPath instance
 169      */
 170     protected abstract SchemaPath createInstance(SchemaPath parent, QName qname);
 171
 172     /**
 173      * Create a child path based on concatenation of this path and a relative path.
 174      *
 175      * @param relative Relative path
 176      * @return A new child path
 177      */
 178     public SchemaPath createChild(final Iterable<QName> relative) {
 179         if (Iterables.isEmpty(relative)) {
 180             return this;
 181         }
 182
 183         SchemaPath parent = this;
 184         for (QName qname : relative) {
 185             parent = parent.createInstance(parent, qname);
 186         }
 187
 188         return parent;
 189     }
 190
 191     /**
 192      * Create a child path based on concatenation of this path and a relative path.
 193      *
 194      * @param relative Relative SchemaPath
 195      * @return A new child path
 196      */
 197     public SchemaPath createChild(final SchemaPath relative) {
 198         Preconditions.checkArgument(!relative.isAbsolute(), "Child creation requires relative path");
 199
 200         SchemaPath parent = this;
 201         for (QName qname : relative.getPathFromRoot()) {
 202             parent = parent.createInstance(parent, qname);
 203         }
 204
 205         return parent;
 206     }
 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 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 Iterable<QName> getPathFromRoot() {
 228         return getLegacyPath();
 229     }
 230
 231     /**
 232      * Returns the list of nodes which need to be traversed to get from this
 233      * node to the starting point (root for absolute SchemaPaths).
 234      *
 235      * @return list of <code>qname</code> instances which represents
 236      *         path from the schema node towards the root.
 237      */
 238     public Iterable<QName> getPathTowardsRoot() {
 239         return new Iterable<QName>() {
 240             @Override
 241             public Iterator<QName> iterator() {
 242                 return new Iterator<QName>() {
 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                         } else {
 257                             throw new NoSuchElementException("No more elements available");
 258                         }
 259                     }
 260
 261                     @Override
 262                     public void remove() {
 263                         throw new UnsupportedOperationException("Component removal not supported");
 264                     }
 265                 };
 266             }
 267         };
 268     }
 269
 270     /**
 271      * Returns the immediate parent SchemaPath.
 272      *
 273      * @return Parent path, null if this SchemaPath is already toplevel.
 274      */
 275     public SchemaPath getParent() {
 276         return parent;
 277     }
 278
 279     /**
 280      * Describes whether schema path is|isn't absolute.
 281      *
 282      * @return boolean value which is <code>true</code> if schema path is
 283      *         absolute.
 284      */
 285     public abstract boolean isAbsolute();
 286
 287     @Override
 288     public final int hashCode() {
 289         return hash;
 290     }
 291
 292     @Override
 293     public boolean equals(final Object obj) {
 294         if (this == obj) {
 295             return true;
 296         }
 297         if (obj == null) {
 298             return false;
 299         }
 300         if (getClass() != obj.getClass()) {
 301             return false;
 302         }
 303         final SchemaPath other = (SchemaPath) obj;
 304
 305         if (qname != null) {
 306             if (!qname.equals(other.qname)) {
 307                 return false;
 308             }
 309         } else {
 310             if (other.qname != null) {
 311                 return false;
 312             }
 313         }
 314
 315         if (parent == null) {
 316             return other.parent == null;
 317         }
 318         return parent.equals(other.parent);
 319     }
 320
 321     @Override
 322     public final String toString() {
 323         return addToStringAttributes(Objects.toStringHelper(this)).toString();
 324     }
 325
 326     protected ToStringHelper addToStringAttributes(final ToStringHelper toStringHelper) {
 327         return toStringHelper.add("path", getPathFromRoot());
 328     }
 329 }