common/concepts/src/main/java/org/opendaylight/yangtools/concepts/ItemOrder.java

   1 /*
   2  * Copyright (c) 2020 PANTHEON.tech, s.r.o. 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.concepts;
   9
  10 import com.google.common.annotations.Beta;
  11 import java.util.Collection;
  12 import java.util.List;
  13 import java.util.Set;
  14 import org.eclipse.jdt.annotation.NonNullByDefault;
  15 import org.eclipse.jdt.annotation.Nullable;
  16
  17 /**
  18  * Marker interface for specifying ordering of items. There are two orderings, {@link Ordered} and {@link Unordered},
  19  * and they are mutually exclusive. Item ordering is considered semantically important, such as it impacts
  20  * {@link Object#equals(Object)} contract. This can be thought of as the missing interface distinction between
  21  * {@link Collection}, {@link List} and {@link Set}.
  22  *
  23  * @param <T> Item order type
  24  */
  25 @Beta
  26 @NonNullByDefault
  27 public interface ItemOrder<T extends ItemOrder<T>> {
  28     /**
  29      * Items are ordered and their order is significant. A {@link List} is an example of a collection which conforms to
  30      * this contract.
  31      */
  32     interface Ordered extends ItemOrder<Ordered> {
  33         @Override
  34         default Class<Ordered> itemOrder() {
  35             return Ordered.class;
  36         }
  37
  38         /**
  39          * {@inheritDoc}
  40          *
  41          * <p>
  42          * Hash code contract of {@link Ordered} objects <b>should</b> be sensitive to item order. In general similar to
  43          * {@link List#hashCode()} (in the {@code must} reading of sensitivity. {@code need not} reading of sensitivity
  44          * could also be implemented as {@code Map.hashCode()} in case of a map-like container.
  45          */
  46         // FIXME: 7.0.0: tighten 'should' to 'must'?
  47         @Override
  48         int hashCode();
  49
  50         /**
  51          * {@inheritDoc}
  52          *
  53          * <p>
  54          * Equality contract of {@link Ordered} objects <b>must</b> be sensitive to item order, similar to
  55          * {@link List#equals(Object)}.
  56          */
  57         @Override
  58         boolean equals(@Nullable Object obj);
  59     }
  60
  61     /**
  62      * Items are unordered and their order is insignificant. A {@link Set} is an example of a collection which conforms
  63      * to this contract.
  64      */
  65     interface Unordered extends ItemOrder<Unordered> {
  66         @Override
  67         default Class<Unordered> itemOrder() {
  68             return Unordered.class;
  69         }
  70
  71         /**
  72          * {@inheritDoc}
  73          *
  74          * <p>
  75          * Hash code contract of {@link Unordered} objects <b>must</b> be insensitive to item order, similar to
  76          * {@link Set#hashCode()}.
  77          *
  78          * <p>
  79          * This contract is also exposed through {@link #itemOrder()}.
  80          */
  81         @Override
  82         int hashCode();
  83
  84         /**
  85          * {@inheritDoc}
  86          *
  87          * <p>
  88          * Equality contract of {@link Unordered} objects <b>must</b> be insensitive to item order, similar to
  89          * {@link Set#equals(Object)}.
  90          *
  91          * <p>
  92          * This contract is also exposed through {@link #itemOrder()}.
  93          */
  94         @Override
  95         boolean equals(@Nullable Object obj);
  96     }
  97
  98     /**
  99      * Return the item order class of this object. The class' equality contracts apply to this object's equality
 100      * contract.
 101      *
 102      * @return Item order class.
 103      */
 104     Class<T> itemOrder();
 105
 106     /**
 107      * {@link ItemOrder} has impact on {@link #hashCode()}.
 108      */
 109     @Override
 110     int hashCode();
 111
 112     /**
 113      * {@link ItemOrder} has impact on {@link #equals(Object)}.
 114      */
 115     @Override
 116     boolean equals(@Nullable Object obj);
 117 }