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.Collections;
  18 import java.util.List;
  19
  20 import org.opendaylight.yangtools.concepts.Immutable;
  21 import org.opendaylight.yangtools.util.HashCodeBuilder;
  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 Iterable<QName> path, final int hash) {
  33             super(path, hash);
  34         }
  35
  36         @Override
  37         public boolean isAbsolute() {
  38             return true;
  39         }
  40
  41         @Override
  42         protected SchemaPath createInstance(final Iterable<QName> path, final int hash) {
  43             return new AbsoluteSchemaPath(path, hash);
  44         }
  45     }
  46
  47     /**
  48      * A relative SchemaPath.
  49      */
  50     private static final class RelativeSchemaPath extends SchemaPath {
  51         private RelativeSchemaPath(final Iterable<QName> path, final int hash) {
  52             super(path, hash);
  53         }
  54
  55         @Override
  56         public boolean isAbsolute() {
  57             return false;
  58         }
  59
  60         @Override
  61         protected SchemaPath createInstance(final Iterable<QName> path, final int hash) {
  62             return new RelativeSchemaPath(path, hash);
  63         }
  64     }
  65
  66     /**
  67      * Shared instance of the conceptual root schema node.
  68      */
  69     public static final SchemaPath ROOT = new AbsoluteSchemaPath(Collections.<QName>emptyList(), Boolean.TRUE.hashCode());
  70
  71     /**
  72      * Shared instance of the "same" relative schema node.
  73      */
  74     public static final SchemaPath SAME = new RelativeSchemaPath(Collections.<QName>emptyList(), Boolean.FALSE.hashCode());
  75
  76     /**
  77      * List of QName instances which represents complete path to the node.
  78      */
  79     private final Iterable<QName> path;
  80
  81     /**
  82      * Cached hash code. We can use this since we are immutable.
  83      */
  84     private final int hash;
  85
  86     /**
  87      * Cached legacy path, filled-in when {@link #getPath()} or {@link #getPathTowardsRoot()}
  88      * is invoked.
  89      */
  90     private ImmutableList<QName> legacyPath;
  91
  92     private ImmutableList<QName> getLegacyPath() {
  93         if (legacyPath == null) {
  94             legacyPath = ImmutableList.copyOf(path);
  95         }
  96
  97         return legacyPath;
  98     }
  99
 100     /**
 101      * Returns the complete path to schema node.
 102      *
 103      * @return list of <code>QName</code> instances which represents complete
 104      *         path to schema node
 105      *
 106      * @deprecated Use {@link #getPathFromRoot()} instead.
 107      */
 108     @Deprecated
 109     public List<QName> getPath() {
 110         return getLegacyPath();
 111     }
 112
 113     protected SchemaPath(final Iterable<QName> path, final int hash) {
 114         this.path = Preconditions.checkNotNull(path);
 115         this.hash = hash;
 116     }
 117
 118     /**
 119      * Constructs new instance of this class with the concrete path.
 120      *
 121      * @param path
 122      *            list of QName instances which specifies exact path to the
 123      *            module node
 124      * @param absolute
 125      *            boolean value which specifies if the path is absolute or
 126      *            relative
 127      *
 128      * @return A SchemaPath instance.
 129      */
 130     public static SchemaPath create(final Iterable<QName> path, final boolean absolute) {
 131         final SchemaPath parent = absolute ? ROOT : SAME;
 132         return parent.createChild(path);
 133     }
 134
 135     /**
 136      * Constructs new instance of this class with the concrete path.
 137      *
 138      * @param absolute
 139      *            boolean value which specifies if the path is absolute or
 140      *            relative
 141      * @param path
 142      *            one or more QName instances which specifies exact path to the
 143      *            module node
 144      *
 145      * @return A SchemaPath instance.
 146      */
 147     public static SchemaPath create(final boolean absolute, final QName... path) {
 148         return create(Arrays.asList(path), absolute);
 149     }
 150
 151     /**
 152      * Create a new instance.
 153      *
 154      * @param path path from root
 155      * @param hash intended hash code
 156      * @return A new SchemaPath instance
 157      */
 158     protected abstract SchemaPath createInstance(Iterable<QName> path, int hash);
 159
 160     private SchemaPath trustedCreateChild(final Iterable<QName> relative) {
 161         if (Iterables.isEmpty(relative)) {
 162             return this;
 163         }
 164
 165         final HashCodeBuilder<QName> b = new HashCodeBuilder<>(hash);
 166         for (QName p : relative) {
 167             b.addArgument(p);
 168         }
 169
 170         return createInstance(Iterables.concat(path, relative), b.toInstance());
 171     }
 172
 173     /**
 174      * Create a child path based on concatenation of this path and a relative path.
 175      *
 176      * @param relative Relative path
 177      * @return A new child path
 178      */
 179     public SchemaPath createChild(final Iterable<QName> relative) {
 180         if (Iterables.isEmpty(relative)) {
 181             return this;
 182         }
 183
 184         return trustedCreateChild(ImmutableList.copyOf(relative));
 185     }
 186
 187     /**
 188      * Create a child path based on concatenation of this path and a relative path.
 189      *
 190      * @param relative Relative SchemaPath
 191      * @return A new child path
 192      */
 193     public SchemaPath createChild(final SchemaPath relative) {
 194         Preconditions.checkArgument(!relative.isAbsolute(), "Child creation requires relative path");
 195         return trustedCreateChild(relative.path);
 196     }
 197
 198     /**
 199      * Create a child path based on concatenation of this path and additional
 200      * path elements.
 201      *
 202      * @param elements Relative SchemaPath elements
 203      * @return A new child path
 204      */
 205     public SchemaPath createChild(final QName... elements) {
 206         return createChild(Arrays.asList(elements));
 207     }
 208
 209     /**
 210      * Returns the list of nodes which need to be traversed to get from the
 211      * starting point (root for absolute SchemaPaths) to the node represented
 212      * by this object.
 213      *
 214      * @return list of <code>qname</code> instances which represents
 215      *         path from the root to the schema node.
 216      */
 217     public Iterable<QName> getPathFromRoot() {
 218         return path;
 219     }
 220
 221     /**
 222      * Returns the list of nodes which need to be traversed to get from this
 223      * node to the starting point (root for absolute SchemaPaths).
 224      *
 225      * @return list of <code>qname</code> instances which represents
 226      *         path from the schema node towards the root.
 227      */
 228     public Iterable<QName> getPathTowardsRoot() {
 229         return getLegacyPath().reverse();
 230     }
 231
 232     /**
 233      * Returns the immediate parent SchemaPath.
 234      *
 235      * @return Parent path, null if this SchemaPath is already toplevel.
 236      */
 237     public SchemaPath getParent() {
 238         final int size = Iterables.size(path);
 239         if (size != 0) {
 240             final SchemaPath parent = isAbsolute() ? ROOT : SAME;
 241             return parent.trustedCreateChild(Iterables.limit(path, size - 1));
 242         } else {
 243             return null;
 244         }
 245     }
 246
 247     /**
 248      * Describes whether schema path is|isn't absolute.
 249      *
 250      * @return boolean value which is <code>true</code> if schema path is
 251      *         absolute.
 252      */
 253     public abstract boolean isAbsolute();
 254
 255     @Override
 256     public final int hashCode() {
 257         return hash;
 258     }
 259
 260     @Override
 261     public boolean equals(final Object obj) {
 262         if (this == obj) {
 263             return true;
 264         }
 265         if (obj == null) {
 266             return false;
 267         }
 268         if (getClass() != obj.getClass()) {
 269             return false;
 270         }
 271         SchemaPath other = (SchemaPath) obj;
 272         return Iterables.elementsEqual(path, other.path);
 273     }
 274
 275     @Override
 276     public final String toString() {
 277         return addToStringAttributes(Objects.toStringHelper(this)).toString();
 278     }
 279
 280     protected ToStringHelper addToStringAttributes(final ToStringHelper toStringHelper) {
 281         return toStringHelper.add("path", path);
 282     }
 283 }