1/*
2 *  Licensed to the Apache Software Foundation (ASF) under one or more
3 *  contributor license agreements.  See the NOTICE file distributed with
4 *  this work for additional information regarding copyright ownership.
5 *  The ASF licenses this file to You under the Apache License, Version 2.0
6 *  (the "License"); you may not use this file except in compliance with
7 *  the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17
18package java.util;
19
20
21/**
22 * A map that has its keys ordered. The sorting is according to either the
23 * natural ordering of its keys or the ordering given by a specified comparator.
24 */
25public interface SortedMap<K,V> extends Map<K,V> {
26
27    /**
28     * Returns the comparator used to compare keys in this sorted map.
29     *
30     * @return the comparator or {@code null} if the natural order is used.
31     */
32    public Comparator<? super K> comparator();
33
34    /**
35     * Returns the first key in this sorted map.
36     *
37     * @return the first key in this sorted map.
38     * @throws NoSuchElementException
39     *                if this sorted map is empty.
40     */
41    public K firstKey();
42
43    /**
44     * Returns a sorted map over a range of this sorted map with all keys that
45     * are less than the specified {@code endKey}. Changes to the returned
46     * sorted map are reflected in this sorted map and vice versa.
47     * <p>
48     * Note: The returned map will not allow an insertion of a key outside the
49     * specified range.
50     *
51     * @param endKey
52     *            the high boundary of the range specified.
53     * @return a sorted map where the keys are less than {@code endKey}.
54     * @throws ClassCastException
55     *             if the class of the end key is inappropriate for this sorted
56     *             map.
57     * @throws NullPointerException
58     *             if the end key is {@code null} and this sorted map does not
59     *             support {@code null} keys.
60     * @throws IllegalArgumentException
61     *             if this map is itself a sorted map over a range of another
62     *             map and the specified key is outside of its range.
63     */
64    public SortedMap<K,V> headMap(K endKey);
65
66    /**
67     * Returns the last key in this sorted map.
68     *
69     * @return the last key in this sorted map.
70     * @throws NoSuchElementException
71     *                if this sorted map is empty.
72     */
73    public K lastKey();
74
75    /**
76     * Returns a sorted map over a range of this sorted map with all keys
77     * greater than or equal to the specified {@code startKey} and less than the
78     * specified {@code endKey}. Changes to the returned sorted map are
79     * reflected in this sorted map and vice versa.
80     * <p>
81     * Note: The returned map will not allow an insertion of a key outside the
82     * specified range.
83     *
84     * @param startKey
85     *            the low boundary of the range (inclusive).
86     * @param endKey
87     *            the high boundary of the range (exclusive),
88     * @return a sorted map with the key from the specified range.
89     * @throws ClassCastException
90     *             if the class of the start or end key is inappropriate for
91     *             this sorted map.
92     * @throws NullPointerException
93     *             if the start or end key is {@code null} and this sorted map
94     *             does not support {@code null} keys.
95     * @throws IllegalArgumentException
96     *             if the start key is greater than the end key, or if this map
97     *             is itself a sorted map over a range of another sorted map and
98     *             the specified range is outside of its range.
99     */
100    public SortedMap<K,V> subMap(K startKey, K endKey);
101
102    /**
103     * Returns a sorted map over a range of this sorted map with all keys that
104     * are greater than or equal to the specified {@code startKey}. Changes to
105     * the returned sorted map are reflected in this sorted map and vice versa.
106     * <p>
107     * Note: The returned map will not allow an insertion of a key outside the
108     * specified range.
109     *
110     * @param startKey
111     *            the low boundary of the range specified.
112     * @return a sorted map where the keys are greater or equal to
113     *         {@code startKey}.
114     * @throws ClassCastException
115     *             if the class of the start key is inappropriate for this
116     *             sorted map.
117     * @throws NullPointerException
118     *             if the start key is {@code null} and this sorted map does not
119     *             support {@code null} keys.
120     * @throws IllegalArgumentException
121     *             if this map itself a sorted map over a range of another map
122     *             and the specified key is outside of its range.
123     */
124    public SortedMap<K,V> tailMap(K startKey);
125}
126