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