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 18 package 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 */ 25 public interface SortedMap<K,V> extends Map<K,V> { 26 27 /** 28 * Returns the comparator used to compare keys in this sorted map, or null if the natural 29 * ordering is in use. 30 */ comparator()31 public Comparator<? super K> comparator(); 32 33 /** 34 * Returns the least key in this sorted map. 35 * 36 * @throws NoSuchElementException 37 * if this sorted map is empty. 38 */ firstKey()39 public K firstKey(); 40 41 /** 42 * Returns a sorted map over a range of this sorted map with all keys that 43 * are less than the specified {@code endKey}. Changes to the returned 44 * sorted map are reflected in this sorted map and vice versa. 45 * <p> 46 * Note: The returned map will not allow an insertion of a key outside the 47 * specified range. 48 * 49 * @param endKey 50 * the high boundary of the range specified. 51 * @return a sorted map where the keys are less than {@code endKey}. 52 * @throws ClassCastException 53 * if the class of the end key is inappropriate for this sorted 54 * map. 55 * @throws NullPointerException 56 * if the end key is {@code null} and this sorted map does not 57 * support {@code null} keys. 58 * @throws IllegalArgumentException 59 * if this map is itself a sorted map over a range of another 60 * map and the specified key is outside of its range. 61 */ headMap(K endKey)62 public SortedMap<K,V> headMap(K endKey); 63 64 /** 65 * Returns the greatest key in this sorted map. 66 * 67 * @throws NoSuchElementException 68 * if this sorted map is empty. 69 */ lastKey()70 public K lastKey(); 71 72 /** 73 * Returns a sorted map over a range of this sorted map with all keys 74 * greater than or equal to the specified {@code startKey} and less than the 75 * specified {@code endKey}. Changes to the returned sorted map are 76 * reflected in this sorted map and vice versa. 77 * <p> 78 * Note: The returned map will not allow an insertion of a key outside the 79 * specified range. 80 * 81 * @param startKey 82 * the low boundary of the range (inclusive). 83 * @param endKey 84 * the high boundary of the range (exclusive), 85 * @return a sorted map with the key from the specified range. 86 * @throws ClassCastException 87 * if the class of the start or end key is inappropriate for 88 * this sorted map. 89 * @throws NullPointerException 90 * if the start or end key is {@code null} and this sorted map 91 * does not support {@code null} keys. 92 * @throws IllegalArgumentException 93 * if the start key is greater than the end key, or if this map 94 * is itself a sorted map over a range of another sorted map and 95 * the specified range is outside of its range. 96 */ subMap(K startKey, K endKey)97 public SortedMap<K,V> subMap(K startKey, K endKey); 98 99 /** 100 * Returns a sorted map over a range of this sorted map with all keys that 101 * are greater than or equal to the specified {@code startKey}. Changes to 102 * the returned sorted map are reflected in this sorted map and vice versa. 103 * <p> 104 * Note: The returned map will not allow an insertion of a key outside the 105 * specified range. 106 * 107 * @param startKey 108 * the low boundary of the range specified. 109 * @return a sorted map where the keys are greater or equal to 110 * {@code startKey}. 111 * @throws ClassCastException 112 * if the class of the start key is inappropriate for this 113 * sorted map. 114 * @throws NullPointerException 115 * if the start key is {@code null} and this sorted map does not 116 * support {@code null} keys. 117 * @throws IllegalArgumentException 118 * if this map itself a sorted map over a range of another map 119 * and the specified key is outside of its range. 120 */ tailMap(K startKey)121 public SortedMap<K,V> tailMap(K startKey); 122 } 123