binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/InstanceIdentifier.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.binding;
   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.ImmutableCollection;
  16 import com.google.common.collect.ImmutableList;
  17 import com.google.common.collect.Iterables;
  18 import java.io.ObjectStreamException;
  19 import java.io.Serializable;
  20 import java.util.Collections;
  21 import java.util.Iterator;
  22 import java.util.Objects;
  23 import java.util.Optional;
  24 import org.eclipse.jdt.annotation.NonNull;
  25 import org.eclipse.jdt.annotation.Nullable;
  26 import org.opendaylight.yangtools.concepts.Builder;
  27 import org.opendaylight.yangtools.concepts.Immutable;
  28 import org.opendaylight.yangtools.concepts.Path;
  29 import org.opendaylight.yangtools.util.HashCodeBuilder;
  30
  31 /**
  32  * This instance identifier uniquely identifies a specific DataObject in the data tree modeled by YANG.
  33  *
  34  * <p>
  35  * For Example let's say you were trying to refer to a node in inventory which was modeled in YANG as follows,
  36  *
  37  * <p>
  38  * <pre>
  39  * module opendaylight-inventory {
  40  *      ....
  41  *
  42  *      container nodes {
  43  *        list node {
  44  *            key "id";
  45  *            ext:context-instance "node-context";
  46  *
  47  *            uses node;
  48  *        }
  49  *    }
  50  *
  51  * }
  52  * </pre>
  53  *
  54  * <p>
  55  * You can create an instance identifier as follows to get to a node with id "openflow:1": {@code
  56  * InstanceIdentifierBuilder.builder(Nodes.class).child(Node.class, new NodeKey(new NodeId("openflow:1")).build();
  57  * }
  58  *
  59  * <p>
  60  * This would be the same as using a path like so, "/nodes/node/openflow:1" to refer to the openflow:1 node
  61  */
  62 public class InstanceIdentifier<T extends DataObject> implements Path<InstanceIdentifier<? extends DataObject>>,
  63         Immutable, Serializable {
  64     private static final long serialVersionUID = 3L;
  65
  66     /*
  67      * Protected to differentiate internal and external access. Internal access is required never to modify
  68      * the contents. References passed to outside entities have to be wrapped in an unmodifiable view.
  69      */
  70     final Iterable<PathArgument> pathArguments;
  71
  72     private final @NonNull Class<T> targetType;
  73     private final boolean wildcarded;
  74     private final int hash;
  75
  76     InstanceIdentifier(final Class<T> type, final Iterable<PathArgument> pathArguments, final boolean wildcarded,
  77             final int hash) {
  78         this.pathArguments = requireNonNull(pathArguments);
  79         this.targetType = requireNonNull(type);
  80         this.wildcarded = wildcarded;
  81         this.hash = hash;
  82     }
  83
  84     /**
  85      * Return the type of data which this InstanceIdentifier identifies.
  86      *
  87      * @return Target type
  88      */
  89     public final @NonNull Class<T> getTargetType() {
  90         return targetType;
  91     }
  92
  93     /**
  94      * Return the path argument chain which makes up this instance identifier.
  95      *
  96      * @return Path argument chain. Immutable and does not contain nulls.
  97      */
  98     public final @NonNull Iterable<PathArgument> getPathArguments() {
  99         return Iterables.unmodifiableIterable(pathArguments);
 100     }
 101
 102     /**
 103      * Check whether an instance identifier contains any wildcards. A wildcard is an path argument which has a null key.
 104      *
 105      * @return true if any of the path arguments has a null key.
 106      */
 107     public final boolean isWildcarded() {
 108         return wildcarded;
 109     }
 110
 111     @Override
 112     public final int hashCode() {
 113         return hash;
 114     }
 115
 116     @Override
 117     public final boolean equals(final Object obj) {
 118         if (this == obj) {
 119             return true;
 120         }
 121         if (obj == null) {
 122             return false;
 123         }
 124         if (getClass() != obj.getClass()) {
 125             return false;
 126         }
 127
 128         final InstanceIdentifier<?> other = (InstanceIdentifier<?>) obj;
 129         if (pathArguments == other.pathArguments) {
 130             return true;
 131         }
 132
 133         /*
 134          * We could now just go and compare the pathArguments, but that
 135          * can be potentially expensive. Let's try to avoid that by
 136          * checking various things that we have cached from pathArguments
 137          * and trying to prove the identifiers are *not* equal.
 138          */
 139         if (hash != other.hash) {
 140             return false;
 141         }
 142         if (wildcarded != other.wildcarded) {
 143             return false;
 144         }
 145         if (targetType != other.targetType) {
 146             return false;
 147         }
 148         if (fastNonEqual(other)) {
 149             return false;
 150         }
 151
 152         // Everything checks out so far, so we have to do a full equals
 153         return Iterables.elementsEqual(pathArguments, other.pathArguments);
 154     }
 155
 156     /**
 157      * Perform class-specific fast checks for non-equality. This allows subclasses to avoid iterating over the
 158      * pathArguments by performing quick checks on their specific fields.
 159      *
 160      * @param other The other identifier, guaranteed to be the same class
 161      * @return true if the other identifier cannot be equal to this one.
 162      */
 163     protected boolean fastNonEqual(final InstanceIdentifier<?> other) {
 164         return false;
 165     }
 166
 167     @Override
 168     public final String toString() {
 169         return addToStringAttributes(MoreObjects.toStringHelper(this)).toString();
 170     }
 171
 172     /**
 173      * Add class-specific toString attributes.
 174      *
 175      * @param toStringHelper ToStringHelper instance
 176      * @return ToStringHelper instance which was passed in
 177      */
 178     protected ToStringHelper addToStringAttributes(final ToStringHelper toStringHelper) {
 179         return toStringHelper.add("targetType", targetType).add("path", Iterables.toString(pathArguments));
 180     }
 181
 182     /**
 183      * Return an instance identifier trimmed at the first occurrence of a specific component type.
 184      *
 185      * <p>
 186      * For example let's say an instance identifier was built like so,
 187      * <pre>
 188      *      identifier = InstanceIdentifierBuilder.builder(Nodes.class).child(Node.class,
 189      *                   new NodeKey(new NodeId("openflow:1")).build();
 190      * </pre>
 191      *
 192      * <p>
 193      * And you wanted to obtain the Instance identifier which represented Nodes you would do it like so,
 194      *
 195      * <p>
 196      * <pre>
 197      *      identifier.firstIdentifierOf(Nodes.class)
 198      * </pre>
 199      *
 200      * @param type component type
 201      * @return trimmed instance identifier, or null if the component type
 202      *         is not present.
 203      */
 204     public final <I extends DataObject> @Nullable InstanceIdentifier<I> firstIdentifierOf(final Class<I> type) {
 205         int count = 1;
 206         for (final PathArgument a : pathArguments) {
 207             if (type.equals(a.getType())) {
 208                 @SuppressWarnings("unchecked")
 209                 final InstanceIdentifier<I> ret = (InstanceIdentifier<I>) internalCreate(
 210                         Iterables.limit(pathArguments, count));
 211                 return ret;
 212             }
 213
 214             ++count;
 215         }
 216
 217         return null;
 218     }
 219
 220     /**
 221      * Return the key associated with the first component of specified type in
 222      * an identifier.
 223      *
 224      * @param listItem component type
 225      * @return key associated with the component, or null if the component type
 226      *         is not present.
 227      */
 228     public final <N extends Identifiable<K> & DataObject, K extends Identifier<N>> @Nullable K firstKeyOf(
 229             final Class<N> listItem) {
 230         for (final PathArgument i : pathArguments) {
 231             if (listItem.equals(i.getType())) {
 232                 @SuppressWarnings("unchecked")
 233                 final K ret = ((IdentifiableItem<N, K>)i).getKey();
 234                 return ret;
 235             }
 236         }
 237
 238         return null;
 239     }
 240
 241     /**
 242      * Check whether an identifier is contained in this identifier. This is a strict subtree check, which requires all
 243      * PathArguments to match exactly.
 244      *
 245      * <p>
 246      * The contains method checks if the other identifier is fully contained within the current identifier. It does this
 247      * by looking at only the types of the path arguments and not by comparing the path arguments themselves.
 248      *
 249      * <p>
 250      * To illustrate here is an example which explains the working of this API. Let's say you have two instance
 251      * identifiers as follows:
 252      * {@code
 253      * this = /nodes/node/openflow:1
 254      * other = /nodes/node/openflow:2
 255      * }
 256      * then this.contains(other) will return false.
 257      *
 258      * @param other Potentially-container instance identifier
 259      * @return True if the specified identifier is contained in this identifier.
 260      */
 261     @Override
 262     public final boolean contains(final InstanceIdentifier<? extends DataObject> other) {
 263         requireNonNull(other, "other should not be null");
 264
 265         final Iterator<?> lit = pathArguments.iterator();
 266         final Iterator<?> oit = other.pathArguments.iterator();
 267
 268         while (lit.hasNext()) {
 269             if (!oit.hasNext()) {
 270                 return false;
 271             }
 272
 273             if (!lit.next().equals(oit.next())) {
 274                 return false;
 275             }
 276         }
 277
 278         return true;
 279     }
 280
 281     /**
 282      * Check whether this instance identifier contains the other identifier after wildcard expansion. This is similar
 283      * to {@link #contains(InstanceIdentifier)}, with the exception that a wildcards are assumed to match the their
 284      * non-wildcarded PathArgument counterpart.
 285      *
 286      * @param other Identifier which should be checked for inclusion.
 287      * @return true if this identifier contains the other object
 288      */
 289     public final boolean containsWildcarded(final InstanceIdentifier<?> other) {
 290         requireNonNull(other, "other should not be null");
 291
 292         final Iterator<PathArgument> lit = pathArguments.iterator();
 293         final Iterator<PathArgument> oit = other.pathArguments.iterator();
 294
 295         while (lit.hasNext()) {
 296             if (!oit.hasNext()) {
 297                 return false;
 298             }
 299
 300             final PathArgument la = lit.next();
 301             final PathArgument oa = oit.next();
 302
 303             if (!la.getType().equals(oa.getType())) {
 304                 return false;
 305             }
 306             if (la instanceof IdentifiableItem<?, ?> && oa instanceof IdentifiableItem<?, ?> && !la.equals(oa)) {
 307                 return false;
 308             }
 309         }
 310
 311         return true;
 312     }
 313
 314     private <N extends DataObject> @NonNull InstanceIdentifier<N> childIdentifier(final AbstractPathArgument<N> arg) {
 315         return trustedCreate(arg, Iterables.concat(pathArguments, Collections.singleton(arg)),
 316             HashCodeBuilder.nextHashCode(hash, arg), isWildcarded());
 317     }
 318
 319     /**
 320      * Create an InstanceIdentifier for a child container. This method is a more efficient equivalent to
 321      * {@code builder().child(container).build()}.
 322      *
 323      * @param container Container to append
 324      * @param <N> Container type
 325      * @return An InstanceIdentifier.
 326      * @throws NullPointerException if {@code container} is null
 327      */
 328     public final <N extends ChildOf<? super T>> @NonNull InstanceIdentifier<N> child(final Class<N> container) {
 329         return childIdentifier(Item.of(container));
 330     }
 331
 332     /**
 333      * Create an InstanceIdentifier for a child list item. This method is a more efficient equivalent to
 334      * {@code builder().child(listItem, listKey).build()}.
 335      *
 336      * @param listItem List to append
 337      * @param listKey List key
 338      * @param <N> List type
 339      * @param <K> Key type
 340      * @return An InstanceIdentifier.
 341      * @throws NullPointerException if any argument is null
 342      */
 343     @SuppressWarnings("unchecked")
 344     public final <N extends Identifiable<K> & ChildOf<? super T>, K extends Identifier<N>>
 345             @NonNull KeyedInstanceIdentifier<N, K> child(final Class<N> listItem, final K listKey) {
 346         return (KeyedInstanceIdentifier<N, K>) childIdentifier(IdentifiableItem.of(listItem, listKey));
 347     }
 348
 349     /**
 350      * Create an InstanceIdentifier for a child container. This method is a more efficient equivalent to
 351      * {@code builder().child(caze, container).build()}.
 352      *
 353      * @param caze Choice case class
 354      * @param container Container to append
 355      * @param <C> Case type
 356      * @param <N> Container type
 357      * @return An InstanceIdentifier.
 358      * @throws NullPointerException if any argument is null
 359      */
 360     public final <C extends ChoiceIn<? super T> & DataObject, N extends ChildOf<? super C>>
 361             @NonNull InstanceIdentifier<N> child(final Class<C> caze, final Class<N> container) {
 362         return childIdentifier(Item.of(caze, container));
 363     }
 364
 365     /**
 366      * Create an InstanceIdentifier for a child list item. This method is a more efficient equivalent to
 367      * {@code builder().child(caze, listItem, listKey).build()}.
 368      *
 369      * @param caze Choice case class
 370      * @param listItem List to append
 371      * @param listKey List key
 372      * @param <C> Case type
 373      * @param <N> List type
 374      * @param <K> Key type
 375      * @return An InstanceIdentifier.
 376      * @throws NullPointerException if any argument is null
 377      */
 378     @SuppressWarnings("unchecked")
 379     public final <C extends ChoiceIn<? super T> & DataObject, K extends Identifier<N>,
 380         N extends Identifiable<K> & ChildOf<? super C>> @NonNull KeyedInstanceIdentifier<N, K> child(
 381                 final Class<C> caze, final Class<N> listItem, final K listKey) {
 382         return (KeyedInstanceIdentifier<N, K>) childIdentifier(IdentifiableItem.of(caze, listItem, listKey));
 383     }
 384
 385     /**
 386      * Create an InstanceIdentifier for a child augmentation. This method is a more efficient equivalent to
 387      * {@code builder().augmentation(container).build()}.
 388      *
 389      * @param container Container to append
 390      * @param <N> Container type
 391      * @return An InstanceIdentifier.
 392      * @throws NullPointerException if {@code container} is null
 393      */
 394     public final <N extends DataObject & Augmentation<? super T>> @NonNull InstanceIdentifier<N> augmentation(
 395             final Class<N> container) {
 396         return childIdentifier(Item.of(container));
 397     }
 398
 399     /**
 400      * Create a builder rooted at this key.
 401      *
 402      * @return A builder instance
 403      */
 404     public @NonNull InstanceIdentifierBuilder<T> builder() {
 405         return new InstanceIdentifierBuilderImpl<>(Item.of(targetType), pathArguments, hash, isWildcarded());
 406     }
 407
 408     /**
 409      * Create an InstanceIdentifierBuilder for a specific type of InstanceIdentifier as specified by container.
 410      *
 411      * @param container Base container
 412      * @param <T> Type of the container
 413      * @return A new {@link InstanceIdentifierBuilder}
 414      * @throws NullPointerException if {@code container} is null
 415      */
 416     public static <T extends ChildOf<? extends DataRoot>> @NonNull InstanceIdentifierBuilder<T> builder(
 417             final Class<T> container) {
 418         return new InstanceIdentifierBuilderImpl<T>().addWildNode(Item.of(container));
 419     }
 420
 421     /**
 422      * Create an InstanceIdentifierBuilder for a specific type of InstanceIdentifier as specified by container in
 423      * a {@code grouping} used in the {@code case} statement.
 424      *
 425      * @param caze Choice case class
 426      * @param container Base container
 427      * @param <C> Case type
 428      * @param <T> Type of the container
 429      * @return A new {@link InstanceIdentifierBuilder}
 430      * @throws NullPointerException if any argument is null
 431      */
 432     public static <C extends ChoiceIn<? extends DataRoot> & DataObject, T extends ChildOf<? super C>>
 433             @NonNull InstanceIdentifierBuilder<T> builder(final Class<C> caze, final Class<T> container) {
 434         return new InstanceIdentifierBuilderImpl<T>().addWildNode(Item.of(caze, container));
 435     }
 436
 437     /**
 438      * Create an InstanceIdentifierBuilder for a specific type of InstanceIdentifier which represents an
 439      * {@link IdentifiableItem}.
 440      *
 441      * @param listItem list item class
 442      * @param listKey key value
 443      * @param <N> List type
 444      * @param <K> List key
 445      * @return A new {@link InstanceIdentifierBuilder}
 446      * @throws NullPointerException if any argument is null
 447      */
 448     public static <N extends Identifiable<K> & ChildOf<? extends DataRoot>,
 449             K extends Identifier<N>> @NonNull InstanceIdentifierBuilder<N> builder(final Class<N> listItem,
 450                     final K listKey) {
 451         return new InstanceIdentifierBuilderImpl<N>().addNode(IdentifiableItem.of(listItem, listKey));
 452     }
 453
 454     /**
 455      * Create an InstanceIdentifierBuilder for a specific type of InstanceIdentifier which represents an
 456      * {@link IdentifiableItem} in a {@code grouping} used in the {@code case} statement.
 457      *
 458      * @param caze Choice case class
 459      * @param listItem list item class
 460      * @param listKey key value
 461      * @param <C> Case type
 462      * @param <N> List type
 463      * @param <K> List key
 464      * @return A new {@link InstanceIdentifierBuilder}
 465      * @throws NullPointerException if any argument is null
 466      */
 467     public static <C extends ChoiceIn<? extends DataRoot> & DataObject,
 468             N extends Identifiable<K> & ChildOf<? super C>, K extends Identifier<N>>
 469             @NonNull InstanceIdentifierBuilder<N> builder(final Class<C> caze, final Class<N> listItem,
 470                     final K listKey) {
 471         return new InstanceIdentifierBuilderImpl<N>().addNode(IdentifiableItem.of(caze, listItem, listKey));
 472     }
 473
 474     /**
 475      * Create an instance identifier for a very specific object type. This method implements {@link #create(Iterable)}
 476      * semantics, except it is used by internal callers, which have assured that the argument is an immutable Iterable.
 477      *
 478      * @param pathArguments The path to a specific node in the data tree
 479      * @return InstanceIdentifier instance
 480      * @throws IllegalArgumentException if pathArguments is empty or contains a null element.
 481      * @throws NullPointerException if {@code pathArguments} is null
 482      */
 483     private static @NonNull InstanceIdentifier<?> internalCreate(final Iterable<PathArgument> pathArguments) {
 484         final Iterator<? extends PathArgument> it = requireNonNull(pathArguments, "pathArguments may not be null")
 485                 .iterator();
 486         final HashCodeBuilder<PathArgument> hashBuilder = new HashCodeBuilder<>();
 487         boolean wildcard = false;
 488         PathArgument arg = null;
 489
 490         while (it.hasNext()) {
 491             arg = it.next();
 492             checkArgument(arg != null, "pathArguments may not contain null elements");
 493
 494             // TODO: sanity check ChildOf<>;
 495             hashBuilder.addArgument(arg);
 496
 497             if (Identifiable.class.isAssignableFrom(arg.getType()) && !(arg instanceof IdentifiableItem<?, ?>)) {
 498                 wildcard = true;
 499             }
 500         }
 501         checkArgument(arg != null, "pathArguments may not be empty");
 502
 503         return trustedCreate(arg, pathArguments, hashBuilder.build(), wildcard);
 504     }
 505
 506     /**
 507      * Create an instance identifier for a very specific object type.
 508      *
 509      * <p>
 510      * Example:
 511      * <pre>
 512      *  List&lt;PathArgument&gt; path = Arrays.asList(new Item(Nodes.class))
 513      *  new InstanceIdentifier(path);
 514      * </pre>
 515      *
 516      * @param pathArguments The path to a specific node in the data tree
 517      * @return InstanceIdentifier instance
 518      * @throws IllegalArgumentException if pathArguments is empty or
 519      *         contains a null element.
 520      */
 521     public static @NonNull InstanceIdentifier<?> create(final Iterable<? extends PathArgument> pathArguments) {
 522         if (pathArguments instanceof ImmutableCollection<?>) {
 523             @SuppressWarnings("unchecked")
 524             final Iterable<PathArgument> immutableArguments = (Iterable<PathArgument>) pathArguments;
 525             return internalCreate(immutableArguments);
 526         }
 527
 528         return internalCreate(ImmutableList.copyOf(pathArguments));
 529     }
 530
 531     /**
 532      * Create an instance identifier for a very specific object type.
 533      *
 534      * <p>
 535      * For example
 536      * <pre>
 537      *      new InstanceIdentifier(Nodes.class)
 538      * </pre>
 539      * would create an InstanceIdentifier for an object of type Nodes
 540      *
 541      * @param type The type of the object which this instance identifier represents
 542      * @return InstanceIdentifier instance
 543      */
 544     @SuppressWarnings("unchecked")
 545     public static <T extends DataObject> @NonNull InstanceIdentifier<T> create(final Class<T> type) {
 546         return (InstanceIdentifier<T>) create(ImmutableList.of(Item.of(type)));
 547     }
 548
 549     /**
 550      * Return the key associated with the last component of the specified identifier.
 551      *
 552      * @param id instance identifier
 553      * @return key associated with the last component
 554      * @throws IllegalArgumentException if the supplied identifier type cannot have a key.
 555      * @throws NullPointerException if id is null.
 556      */
 557     public static <N extends Identifiable<K> & DataObject, K extends Identifier<N>> K keyOf(
 558             final InstanceIdentifier<N> id) {
 559         requireNonNull(id);
 560         checkArgument(id instanceof KeyedInstanceIdentifier, "%s does not have a key", id);
 561
 562         @SuppressWarnings("unchecked")
 563         final K ret = ((KeyedInstanceIdentifier<N, K>)id).getKey();
 564         return ret;
 565     }
 566
 567     @SuppressWarnings({ "unchecked", "rawtypes" })
 568     static <N extends DataObject> @NonNull InstanceIdentifier<N> trustedCreate(final PathArgument arg,
 569             final Iterable<PathArgument> pathArguments, final int hash, boolean wildcarded) {
 570         if (Identifiable.class.isAssignableFrom(arg.getType()) && !wildcarded) {
 571             Identifier<?> key = null;
 572             if (arg instanceof IdentifiableItem) {
 573                 key = ((IdentifiableItem<?, ?>)arg).getKey();
 574             } else {
 575                 wildcarded = true;
 576             }
 577
 578             return new KeyedInstanceIdentifier(arg.getType(), pathArguments, wildcarded, hash, key);
 579         }
 580
 581         return new InstanceIdentifier(arg.getType(), pathArguments, wildcarded, hash);
 582     }
 583
 584     /**
 585      * Path argument of {@link InstanceIdentifier}. Interface which implementations are used as path components of the
 586      * path in overall data tree.
 587      */
 588     public interface PathArgument extends Comparable<PathArgument> {
 589         /**
 590          * Return the data object type backing this PathArgument.
 591          *
 592          * @return Data object type.
 593          */
 594         @NonNull Class<? extends DataObject> getType();
 595
 596         /**
 597          * Return an optional enclosing case type. This is used only when {@link #getType()} references a node defined
 598          * in a {@code grouping} which is reference inside a {@code case} statement in order to safely reference the
 599          * node.
 600          *
 601          * @return Optional case class.
 602          */
 603         default Optional<? extends Class<? extends DataObject>> getCaseType() {
 604             return Optional.empty();
 605         }
 606     }
 607
 608     private abstract static class AbstractPathArgument<T extends DataObject> implements PathArgument, Serializable {
 609         private static final long serialVersionUID = 1L;
 610
 611         private final @NonNull Class<T> type;
 612
 613         AbstractPathArgument(final Class<T> type) {
 614             this.type = requireNonNull(type, "Type may not be null.");
 615         }
 616
 617         @Override
 618         public final Class<T> getType() {
 619             return type;
 620         }
 621
 622         Object getKey() {
 623             return null;
 624         }
 625
 626         @Override
 627         public final int hashCode() {
 628             return Objects.hash(type, getCaseType(), getKey());
 629         }
 630
 631         @Override
 632         public final boolean equals(final Object obj) {
 633             if (this == obj) {
 634                 return true;
 635             }
 636             if (!(obj instanceof AbstractPathArgument)) {
 637                 return false;
 638             }
 639             final AbstractPathArgument<?> other = (AbstractPathArgument<?>) obj;
 640             return type.equals(other.type) && Objects.equals(getKey(), other.getKey())
 641                     && getCaseType().equals(other.getCaseType());
 642         }
 643
 644         @Override
 645         public final int compareTo(final PathArgument arg) {
 646             final int cmp = compareClasses(type, arg.getType());
 647             if (cmp != 0) {
 648                 return cmp;
 649             }
 650             final Optional<? extends Class<?>> caseType = getCaseType();
 651             if (!caseType.isPresent()) {
 652                 return arg.getCaseType().isPresent() ? -1 : 1;
 653             }
 654             final Optional<? extends Class<?>> argCaseType = getCaseType();
 655             return argCaseType.isPresent() ? compareClasses(caseType.get(), argCaseType.get()) : 1;
 656         }
 657
 658         private static int compareClasses(final Class<?> first, final Class<?> second) {
 659             return first.getCanonicalName().compareTo(second.getCanonicalName());
 660         }
 661     }
 662
 663     /**
 664      * An Item represents an object that probably is only one of it's kind. For example a Nodes object is only one of
 665      * a kind. In YANG terms this would probably represent a container.
 666      *
 667      * @param <T> Item type
 668      */
 669     public static class Item<T extends DataObject> extends AbstractPathArgument<T> {
 670         private static final long serialVersionUID = 1L;
 671
 672         Item(final Class<T> type) {
 673             super(type);
 674         }
 675
 676         /**
 677          * Return a PathArgument instance backed by the specified class.
 678          *
 679          * @param type Backing class
 680          * @param <T> Item type
 681          * @return A new PathArgument
 682          * @throws NullPointerException if {@code} is null.
 683          */
 684         public static <T extends DataObject> @NonNull Item<T> of(final Class<T> type) {
 685             return new Item<>(type);
 686         }
 687
 688         /**
 689          * Return a PathArgument instance backed by the specified class, which in turn is defined in a {@code grouping}
 690          * used in a corresponding {@code case} statement.
 691          *
 692          * @param caseType defining case class
 693          * @param type Backing class
 694          * @param <C> Case type
 695          * @param <T> Item type
 696          * @return A new PathArgument
 697          * @throws NullPointerException if any argument is null.
 698          */
 699         public static <C extends ChoiceIn<?> & DataObject, T extends ChildOf<? super C>> @NonNull Item<T> of(
 700                 final Class<C> caseType, final Class<T> type) {
 701             return new CaseItem<>(caseType, type);
 702         }
 703
 704         @Override
 705         public String toString() {
 706             return getType().getName();
 707         }
 708     }
 709
 710     /**
 711      * An IdentifiableItem represents a object that is usually present in a collection and can be identified uniquely
 712      * by a key. In YANG terms this would probably represent an item in a list.
 713      *
 714      * @param <I> An object that is identifiable by an identifier
 715      * @param <T> The identifier of the object
 716      */
 717     public static class IdentifiableItem<I extends Identifiable<T> & DataObject, T extends Identifier<I>>
 718             extends AbstractPathArgument<I> {
 719         private static final long serialVersionUID = 1L;
 720
 721         private final @NonNull T key;
 722
 723         IdentifiableItem(final Class<I> type, final T key) {
 724             super(type);
 725             this.key = requireNonNull(key, "Key may not be null.");
 726         }
 727
 728         /**
 729          * Return an IdentifiableItem instance backed by the specified class with specified key.
 730          *
 731          * @param type Backing class
 732          * @param key Key
 733          * @param <T> List type
 734          * @param <I> Key type
 735          * @return An IdentifiableItem
 736          * @throws NullPointerException if any argument is null.
 737          */
 738         public static <T extends Identifiable<I> & DataObject, I extends Identifier<T>>
 739                 @NonNull IdentifiableItem<T, I> of(final Class<T> type, final I key) {
 740             return new IdentifiableItem<>(type, key);
 741         }
 742
 743         /**
 744          * Return an IdentifiableItem instance backed by the specified class with specified key. The class is in turn
 745          * defined in a {@code grouping} used in a corresponding {@code case} statement.
 746          *
 747          * @param caseType defining case class
 748          * @param type Backing class
 749          * @param <C> Case type
 750          * @param <T> List type
 751          * @param <I> Key type
 752          * @return A new PathArgument
 753          * @throws NullPointerException if any argument is null.
 754          */
 755         public static <C extends ChoiceIn<?> & DataObject, T extends ChildOf<? super C> & Identifiable<I>,
 756                 I extends Identifier<T>> @NonNull IdentifiableItem<T, I> of(final Class<C> caseType,
 757                         final Class<T> type, final I key) {
 758             return new CaseIdentifiableItem<>(caseType, type, key);
 759         }
 760
 761         /**
 762          * Return the data object type backing this PathArgument.
 763          *
 764          * @return Data object type.
 765          */
 766         @Override
 767         public final @NonNull T getKey() {
 768             return key;
 769         }
 770
 771         @Override
 772         public String toString() {
 773             return getType().getName() + "[key=" + key + "]";
 774         }
 775     }
 776
 777     private static final class CaseItem<C extends ChoiceIn<?> & DataObject, T extends ChildOf<? super C>>
 778             extends Item<T> {
 779         private static final long serialVersionUID = 1L;
 780
 781         private final Class<C> caseType;
 782
 783         CaseItem(final Class<C> caseType, final Class<T> type) {
 784             super(type);
 785             this.caseType = requireNonNull(caseType);
 786         }
 787
 788         @Override
 789         public Optional<Class<C>> getCaseType() {
 790             return Optional.of(caseType);
 791         }
 792     }
 793
 794     private static final class CaseIdentifiableItem<C extends ChoiceIn<?> & DataObject,
 795             T extends ChildOf<? super C> & Identifiable<K>, K extends Identifier<T>> extends IdentifiableItem<T, K> {
 796         private static final long serialVersionUID = 1L;
 797
 798         private final Class<C> caseType;
 799
 800         CaseIdentifiableItem(final Class<C> caseType, final Class<T> type, final K key) {
 801             super(type, key);
 802             this.caseType = requireNonNull(caseType);
 803         }
 804
 805         @Override
 806         public Optional<Class<C>> getCaseType() {
 807             return Optional.of(caseType);
 808         }
 809     }
 810
 811     public interface InstanceIdentifierBuilder<T extends DataObject> extends Builder<InstanceIdentifier<T>> {
 812         /**
 813          * Append the specified container as a child of the current InstanceIdentifier referenced by the builder. This
 814          * method should be used when you want to build an instance identifier by appending top-level elements, for
 815          * example
 816          * <pre>
 817          *     InstanceIdentifier.builder().child(Nodes.class).build();
 818          * </pre>
 819          *
 820          * <p>
 821          * NOTE :- The above example is only for illustration purposes InstanceIdentifier.builder() has been deprecated
 822          * and should not be used. Use InstanceIdentifier.builder(Nodes.class) instead
 823          *
 824          * @param container Container to append
 825          * @param <N> Container type
 826          * @return this builder
 827          * @throws NullPointerException if {@code container} is null
 828          */
 829         <N extends ChildOf<? super T>> @NonNull InstanceIdentifierBuilder<N> child(Class<N> container);
 830
 831         /**
 832          * Append the specified container as a child of the current InstanceIdentifier referenced by the builder. This
 833          * method should be used when you want to build an instance identifier by appending a container node to the
 834          * identifier and the {@code container} is defined in a {@code grouping} used in a {@code case} statement.
 835          *
 836          * @param caze Choice case class
 837          * @param container Container to append
 838          * @param <C> Case type
 839          * @param <N> Container type
 840          * @return this builder
 841          * @throws NullPointerException if {@code container} is null
 842          */
 843         <C extends ChoiceIn<? super T> & DataObject, N extends ChildOf<? super C>>
 844                 @NonNull InstanceIdentifierBuilder<N> child(Class<C> caze, Class<N> container);
 845
 846         /**
 847          * Append the specified listItem as a child of the current InstanceIdentifier referenced by the builder. This
 848          * method should be used when you want to build an instance identifier by appending a specific list element to
 849          * the identifier.
 850          *
 851          * @param listItem List to append
 852          * @param listKey List key
 853          * @param <N> List type
 854          * @param <K> Key type
 855          * @return this builder
 856          * @throws NullPointerException if any argument is null
 857          */
 858         <N extends Identifiable<K> & ChildOf<? super T>, K extends Identifier<N>>
 859                 @NonNull InstanceIdentifierBuilder<N> child(Class<N> listItem, K listKey);
 860
 861         /**
 862          * Append the specified listItem as a child of the current InstanceIdentifier referenced by the builder. This
 863          * method should be used when you want to build an instance identifier by appending a specific list element to
 864          * the identifier and the {@code list} is defined in a {@code grouping} used in a {@code case} statement.
 865          *
 866          * @param caze Choice case class
 867          * @param listItem List to append
 868          * @param listKey List key
 869          * @param <C> Case type
 870          * @param <N> List type
 871          * @param <K> Key type
 872          * @return this builder
 873          * @throws NullPointerException if any argument is null
 874          */
 875         <C extends ChoiceIn<? super T> & DataObject, K extends Identifier<N>,
 876                 N extends Identifiable<K> & ChildOf<? super C>> @NonNull InstanceIdentifierBuilder<N> child(
 877                         Class<C> caze, Class<N> listItem, K listKey);
 878
 879         /**
 880          * Build an identifier which refers to a specific augmentation of the current InstanceIdentifier referenced by
 881          * the builder.
 882          *
 883          * @param container augmentation class
 884          * @param <N> augmentation type
 885          * @return this builder
 886          * @throws NullPointerException if {@code container} is null
 887          */
 888         <N extends DataObject & Augmentation<? super T>> @NonNull InstanceIdentifierBuilder<N> augmentation(
 889                 Class<N> container);
 890
 891         /**
 892          * Build the instance identifier.
 893          *
 894          * @return Resulting instance identifier.
 895          */
 896         @Override
 897         InstanceIdentifier<T> build();
 898     }
 899
 900     private Object writeReplace() throws ObjectStreamException {
 901         return new InstanceIdentifierV3<>(this);
 902     }
 903 }