lib/classpath/external/jsr166/java/util/concurrent/ConcurrentNavigableMap.java

   1 /*
   2  * Written by Doug Lea with assistance from members of JCP JSR-166
   3  * Expert Group and released to the public domain, as explained at
   4  * http://creativecommons.org/licenses/publicdomain
   5  */
   6
   7 package java.util.concurrent;
   8 import java.util.*;
   9
  10 /**
  11  * A {@link ConcurrentMap} supporting {@link NavigableMap} operations,
  12  * and recursively so for its navigable sub-maps.
  13  *
  14  * <p>This interface is a member of the
  15  * <a href="{@docRoot}/../technotes/guides/collections/index.html">
  16  * Java Collections Framework</a>.
  17  *
  18  * @author Doug Lea
  19  * @param <K> the type of keys maintained by this map
  20  * @param <V> the type of mapped values
  21  * @since 1.6
  22  */
  23 public interface ConcurrentNavigableMap<K,V>
  24     extends ConcurrentMap<K,V>, NavigableMap<K,V>
  25 {
  26     /**
  27      * @throws ClassCastException       {@inheritDoc}
  28      * @throws NullPointerException     {@inheritDoc}
  29      * @throws IllegalArgumentException {@inheritDoc}
  30      */
  31     ConcurrentNavigableMap<K,V> subMap(K fromKey, boolean fromInclusive,
  32                                        K toKey,   boolean toInclusive);
  33
  34     /**
  35      * @throws ClassCastException       {@inheritDoc}
  36      * @throws NullPointerException     {@inheritDoc}
  37      * @throws IllegalArgumentException {@inheritDoc}
  38      */
  39     ConcurrentNavigableMap<K,V> headMap(K toKey, boolean inclusive);
  40
  41
  42     /**
  43      * @throws ClassCastException       {@inheritDoc}
  44      * @throws NullPointerException     {@inheritDoc}
  45      * @throws IllegalArgumentException {@inheritDoc}
  46      */
  47     ConcurrentNavigableMap<K,V> tailMap(K fromKey, boolean inclusive);
  48
  49     /**
  50      * @throws ClassCastException       {@inheritDoc}
  51      * @throws NullPointerException     {@inheritDoc}
  52      * @throws IllegalArgumentException {@inheritDoc}
  53      */
  54     ConcurrentNavigableMap<K,V> subMap(K fromKey, K toKey);
  55
  56     /**
  57      * @throws ClassCastException       {@inheritDoc}
  58      * @throws NullPointerException     {@inheritDoc}
  59      * @throws IllegalArgumentException {@inheritDoc}
  60      */
  61     ConcurrentNavigableMap<K,V> headMap(K toKey);
  62
  63     /**
  64      * @throws ClassCastException       {@inheritDoc}
  65      * @throws NullPointerException     {@inheritDoc}
  66      * @throws IllegalArgumentException {@inheritDoc}
  67      */
  68     ConcurrentNavigableMap<K,V> tailMap(K fromKey);
  69
  70     /**
  71      * Returns a reverse order view of the mappings contained in this map.
  72      * The descending map is backed by this map, so changes to the map are
  73      * reflected in the descending map, and vice-versa.
  74      *
  75      * <p>The returned map has an ordering equivalent to
  76      * <tt>{@link Collections#reverseOrder(Comparator) Collections.reverseOrder}(comparator())</tt>.
  77      * The expression {@code m.descendingMap().descendingMap()} returns a
  78      * view of {@code m} essentially equivalent to {@code m}.
  79      *
  80      * @return a reverse order view of this map
  81      */
  82     ConcurrentNavigableMap<K,V> descendingMap();
  83
  84     /**
  85      * Returns a {@link NavigableSet} view of the keys contained in this map.
  86      * The set's iterator returns the keys in ascending order.
  87      * The set is backed by the map, so changes to the map are
  88      * reflected in the set, and vice-versa.  The set supports element
  89      * removal, which removes the corresponding mapping from the map,
  90      * via the {@code Iterator.remove}, {@code Set.remove},
  91      * {@code removeAll}, {@code retainAll}, and {@code clear}
  92      * operations.  It does not support the {@code add} or {@code addAll}
  93      * operations.
  94      *
  95      * <p>The view's {@code iterator} is a "weakly consistent" iterator
  96      * that will never throw {@link ConcurrentModificationException},
  97      * and guarantees to traverse elements as they existed upon
  98      * construction of the iterator, and may (but is not guaranteed to)
  99      * reflect any modifications subsequent to construction.
 100      *
 101      * @return a navigable set view of the keys in this map
 102      */
 103     public NavigableSet<K> navigableKeySet();
 104
 105     /**
 106      * Returns a {@link NavigableSet} view of the keys contained in this map.
 107      * The set's iterator returns the keys in ascending order.
 108      * The set is backed by the map, so changes to the map are
 109      * reflected in the set, and vice-versa.  The set supports element
 110      * removal, which removes the corresponding mapping from the map,
 111      * via the {@code Iterator.remove}, {@code Set.remove},
 112      * {@code removeAll}, {@code retainAll}, and {@code clear}
 113      * operations.  It does not support the {@code add} or {@code addAll}
 114      * operations.
 115      *
 116      * <p>The view's {@code iterator} is a "weakly consistent" iterator
 117      * that will never throw {@link ConcurrentModificationException},
 118      * and guarantees to traverse elements as they existed upon
 119      * construction of the iterator, and may (but is not guaranteed to)
 120      * reflect any modifications subsequent to construction.
 121      *
 122      * <p>This method is equivalent to method {@code navigableKeySet}.
 123      *
 124      * @return a navigable set view of the keys in this map
 125      */
 126     NavigableSet<K> keySet();
 127
 128     /**
 129      * Returns a reverse order {@link NavigableSet} view of the keys contained in this map.
 130      * The set's iterator returns the keys in descending order.
 131      * The set is backed by the map, so changes to the map are
 132      * reflected in the set, and vice-versa.  The set supports element
 133      * removal, which removes the corresponding mapping from the map,
 134      * via the {@code Iterator.remove}, {@code Set.remove},
 135      * {@code removeAll}, {@code retainAll}, and {@code clear}
 136      * operations.  It does not support the {@code add} or {@code addAll}
 137      * operations.
 138      *
 139      * <p>The view's {@code iterator} is a "weakly consistent" iterator
 140      * that will never throw {@link ConcurrentModificationException},
 141      * and guarantees to traverse elements as they existed upon
 142      * construction of the iterator, and may (but is not guaranteed to)
 143      * reflect any modifications subsequent to construction.
 144      *
 145      * @return a reverse order navigable set view of the keys in this map
 146      */
 147     public NavigableSet<K> descendingKeySet();
 148 }