jaroslav@1890: /*
jaroslav@1890:  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
jaroslav@1890:  *
jaroslav@1890:  * This code is free software; you can redistribute it and/or modify it
jaroslav@1890:  * under the terms of the GNU General Public License version 2 only, as
jaroslav@1890:  * published by the Free Software Foundation.  Oracle designates this
jaroslav@1890:  * particular file as subject to the "Classpath" exception as provided
jaroslav@1890:  * by Oracle in the LICENSE file that accompanied this code.
jaroslav@1890:  *
jaroslav@1890:  * This code is distributed in the hope that it will be useful, but WITHOUT
jaroslav@1890:  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
jaroslav@1890:  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
jaroslav@1890:  * version 2 for more details (a copy is included in the LICENSE file that
jaroslav@1890:  * accompanied this code).
jaroslav@1890:  *
jaroslav@1890:  * You should have received a copy of the GNU General Public License version
jaroslav@1890:  * 2 along with this work; if not, write to the Free Software Foundation,
jaroslav@1890:  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
jaroslav@1890:  *
jaroslav@1890:  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
jaroslav@1890:  * or visit www.oracle.com if you need additional information or have any
jaroslav@1890:  * questions.
jaroslav@1890:  */
jaroslav@1890: 
jaroslav@1890: /*
jaroslav@1890:  * This file is available under and governed by the GNU General Public
jaroslav@1890:  * License version 2 only, as published by the Free Software Foundation.
jaroslav@1890:  * However, the following notice accompanied the original version of this
jaroslav@1890:  * file:
jaroslav@1890:  *
jaroslav@1890:  * Written by Doug Lea with assistance from members of JCP JSR-166
jaroslav@1890:  * Expert Group and released to the public domain, as explained at
jaroslav@1890:  * http://creativecommons.org/publicdomain/zero/1.0/
jaroslav@1890:  */
jaroslav@1890: 
jaroslav@1890: package java.util.concurrent;
jaroslav@1890: import java.util.*;
jaroslav@1890: 
jaroslav@1890: /**
jaroslav@1890:  * A {@link ConcurrentMap} supporting {@link NavigableMap} operations,
jaroslav@1890:  * and recursively so for its navigable sub-maps.
jaroslav@1890:  *
jaroslav@1890:  * <p>This interface is a member of the
jaroslav@1890:  * <a href="{@docRoot}/../technotes/guides/collections/index.html">
jaroslav@1890:  * Java Collections Framework</a>.
jaroslav@1890:  *
jaroslav@1890:  * @author Doug Lea
jaroslav@1890:  * @param <K> the type of keys maintained by this map
jaroslav@1890:  * @param <V> the type of mapped values
jaroslav@1890:  * @since 1.6
jaroslav@1890:  */
jaroslav@1890: public interface ConcurrentNavigableMap<K,V>
jaroslav@1890:     extends ConcurrentMap<K,V>, NavigableMap<K,V>
jaroslav@1890: {
jaroslav@1890:     /**
jaroslav@1890:      * @throws ClassCastException       {@inheritDoc}
jaroslav@1890:      * @throws NullPointerException     {@inheritDoc}
jaroslav@1890:      * @throws IllegalArgumentException {@inheritDoc}
jaroslav@1890:      */
jaroslav@1890:     ConcurrentNavigableMap<K,V> subMap(K fromKey, boolean fromInclusive,
jaroslav@1890:                                        K toKey,   boolean toInclusive);
jaroslav@1890: 
jaroslav@1890:     /**
jaroslav@1890:      * @throws ClassCastException       {@inheritDoc}
jaroslav@1890:      * @throws NullPointerException     {@inheritDoc}
jaroslav@1890:      * @throws IllegalArgumentException {@inheritDoc}
jaroslav@1890:      */
jaroslav@1890:     ConcurrentNavigableMap<K,V> headMap(K toKey, boolean inclusive);
jaroslav@1890: 
jaroslav@1890: 
jaroslav@1890:     /**
jaroslav@1890:      * @throws ClassCastException       {@inheritDoc}
jaroslav@1890:      * @throws NullPointerException     {@inheritDoc}
jaroslav@1890:      * @throws IllegalArgumentException {@inheritDoc}
jaroslav@1890:      */
jaroslav@1890:     ConcurrentNavigableMap<K,V> tailMap(K fromKey, boolean inclusive);
jaroslav@1890: 
jaroslav@1890:     /**
jaroslav@1890:      * @throws ClassCastException       {@inheritDoc}
jaroslav@1890:      * @throws NullPointerException     {@inheritDoc}
jaroslav@1890:      * @throws IllegalArgumentException {@inheritDoc}
jaroslav@1890:      */
jaroslav@1890:     ConcurrentNavigableMap<K,V> subMap(K fromKey, K toKey);
jaroslav@1890: 
jaroslav@1890:     /**
jaroslav@1890:      * @throws ClassCastException       {@inheritDoc}
jaroslav@1890:      * @throws NullPointerException     {@inheritDoc}
jaroslav@1890:      * @throws IllegalArgumentException {@inheritDoc}
jaroslav@1890:      */
jaroslav@1890:     ConcurrentNavigableMap<K,V> headMap(K toKey);
jaroslav@1890: 
jaroslav@1890:     /**
jaroslav@1890:      * @throws ClassCastException       {@inheritDoc}
jaroslav@1890:      * @throws NullPointerException     {@inheritDoc}
jaroslav@1890:      * @throws IllegalArgumentException {@inheritDoc}
jaroslav@1890:      */
jaroslav@1890:     ConcurrentNavigableMap<K,V> tailMap(K fromKey);
jaroslav@1890: 
jaroslav@1890:     /**
jaroslav@1890:      * Returns a reverse order view of the mappings contained in this map.
jaroslav@1890:      * The descending map is backed by this map, so changes to the map are
jaroslav@1890:      * reflected in the descending map, and vice-versa.
jaroslav@1890:      *
jaroslav@1890:      * <p>The returned map has an ordering equivalent to
jaroslav@1890:      * <tt>{@link Collections#reverseOrder(Comparator) Collections.reverseOrder}(comparator())</tt>.
jaroslav@1890:      * The expression {@code m.descendingMap().descendingMap()} returns a
jaroslav@1890:      * view of {@code m} essentially equivalent to {@code m}.
jaroslav@1890:      *
jaroslav@1890:      * @return a reverse order view of this map
jaroslav@1890:      */
jaroslav@1890:     ConcurrentNavigableMap<K,V> descendingMap();
jaroslav@1890: 
jaroslav@1890:     /**
jaroslav@1890:      * Returns a {@link NavigableSet} view of the keys contained in this map.
jaroslav@1890:      * The set's iterator returns the keys in ascending order.
jaroslav@1890:      * The set is backed by the map, so changes to the map are
jaroslav@1890:      * reflected in the set, and vice-versa.  The set supports element
jaroslav@1890:      * removal, which removes the corresponding mapping from the map,
jaroslav@1890:      * via the {@code Iterator.remove}, {@code Set.remove},
jaroslav@1890:      * {@code removeAll}, {@code retainAll}, and {@code clear}
jaroslav@1890:      * operations.  It does not support the {@code add} or {@code addAll}
jaroslav@1890:      * operations.
jaroslav@1890:      *
jaroslav@1890:      * <p>The view's {@code iterator} is a "weakly consistent" iterator
jaroslav@1890:      * that will never throw {@link ConcurrentModificationException},
jaroslav@1890:      * and guarantees to traverse elements as they existed upon
jaroslav@1890:      * construction of the iterator, and may (but is not guaranteed to)
jaroslav@1890:      * reflect any modifications subsequent to construction.
jaroslav@1890:      *
jaroslav@1890:      * @return a navigable set view of the keys in this map
jaroslav@1890:      */
jaroslav@1890:     public NavigableSet<K> navigableKeySet();
jaroslav@1890: 
jaroslav@1890:     /**
jaroslav@1890:      * Returns a {@link NavigableSet} view of the keys contained in this map.
jaroslav@1890:      * The set's iterator returns the keys in ascending order.
jaroslav@1890:      * The set is backed by the map, so changes to the map are
jaroslav@1890:      * reflected in the set, and vice-versa.  The set supports element
jaroslav@1890:      * removal, which removes the corresponding mapping from the map,
jaroslav@1890:      * via the {@code Iterator.remove}, {@code Set.remove},
jaroslav@1890:      * {@code removeAll}, {@code retainAll}, and {@code clear}
jaroslav@1890:      * operations.  It does not support the {@code add} or {@code addAll}
jaroslav@1890:      * operations.
jaroslav@1890:      *
jaroslav@1890:      * <p>The view's {@code iterator} is a "weakly consistent" iterator
jaroslav@1890:      * that will never throw {@link ConcurrentModificationException},
jaroslav@1890:      * and guarantees to traverse elements as they existed upon
jaroslav@1890:      * construction of the iterator, and may (but is not guaranteed to)
jaroslav@1890:      * reflect any modifications subsequent to construction.
jaroslav@1890:      *
jaroslav@1890:      * <p>This method is equivalent to method {@code navigableKeySet}.
jaroslav@1890:      *
jaroslav@1890:      * @return a navigable set view of the keys in this map
jaroslav@1890:      */
jaroslav@1890:     NavigableSet<K> keySet();
jaroslav@1890: 
jaroslav@1890:     /**
jaroslav@1890:      * Returns a reverse order {@link NavigableSet} view of the keys contained in this map.
jaroslav@1890:      * The set's iterator returns the keys in descending order.
jaroslav@1890:      * The set is backed by the map, so changes to the map are
jaroslav@1890:      * reflected in the set, and vice-versa.  The set supports element
jaroslav@1890:      * removal, which removes the corresponding mapping from the map,
jaroslav@1890:      * via the {@code Iterator.remove}, {@code Set.remove},
jaroslav@1890:      * {@code removeAll}, {@code retainAll}, and {@code clear}
jaroslav@1890:      * operations.  It does not support the {@code add} or {@code addAll}
jaroslav@1890:      * operations.
jaroslav@1890:      *
jaroslav@1890:      * <p>The view's {@code iterator} is a "weakly consistent" iterator
jaroslav@1890:      * that will never throw {@link ConcurrentModificationException},
jaroslav@1890:      * and guarantees to traverse elements as they existed upon
jaroslav@1890:      * construction of the iterator, and may (but is not guaranteed to)
jaroslav@1890:      * reflect any modifications subsequent to construction.
jaroslav@1890:      *
jaroslav@1890:      * @return a reverse order navigable set view of the keys in this map
jaroslav@1890:      */
jaroslav@1890:     public NavigableSet<K> descendingKeySet();
jaroslav@1890: }