001/* 002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 003 * 004 * This code is free software; you can redistribute it and/or modify it 005 * under the terms of the GNU General Public License version 2 only, as 006 * published by the Free Software Foundation. Oracle designates this 007 * particular file as subject to the "Classpath" exception as provided 008 * by Oracle in the LICENSE file that accompanied this code. 009 * 010 * This code is distributed in the hope that it will be useful, but WITHOUT 011 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 012 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 013 * version 2 for more details (a copy is included in the LICENSE file that 014 * accompanied this code). 015 * 016 * You should have received a copy of the GNU General Public License version 017 * 2 along with this work; if not, write to the Free Software Foundation, 018 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 019 * 020 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 021 * or visit www.oracle.com if you need additional information or have any 022 * questions. 023 */ 024 025/* 026 * This file is available under and governed by the GNU General Public 027 * License version 2 only, as published by the Free Software Foundation. 028 * However, the following notice accompanied the original version of this 029 * file: 030 * 031 * Written by Doug Lea and Josh Bloch with assistance from members of JCP 032 * JSR-166 Expert Group and released to the public domain, as explained at 033 * http://creativecommons.org/publicdomain/zero/1.0/ 034 */ 035package Torello.Java.ReadOnly; 036 037import java.util.Map; 038import java.util.NavigableMap; 039import java.util.Set; 040import java.util.Comparator; 041 042/** 043 * Immutable variant of Java Collectionds Framework interface 044 * <CODE>java.util.NavigableMap<K, V></CODE>. 045 * 046 * <EMBED CLASS='external-html' DATA-JDK=ReadOnlyNavigableMap DATA-FILE-ID=INTERFACES> 047 * 048 * @param <K> the type of keys maintained by this map 049 * @param <V> the type of mapped values 050 */ 051@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_INTERFACE") 052public interface ReadOnlyNavigableMap<K, V> extends ReadOnlySortedMap<K,V> 053{ 054 // ******************************************************************************************** 055 // ******************************************************************************************** 056 // Original JDK Interface Methods 057 // ******************************************************************************************** 058 // ******************************************************************************************** 059 060 061 /** 062 * Returns a key-value mapping associated with the greatest key strictly less than the given 063 * key, or {@code null} if there is no such key. 064 * 065 * @param key the key 066 * 067 * @return an entry with the greatest key less than {@code key}, or {@code null} if there is no 068 * such key 069 * 070 * @throws ClassCastException if the specified key cannot be compared with the keys currently 071 * in the map 072 * 073 * @throws NullPointerException if the specified key is null and this map does not permit null 074 * keys 075 */ 076 ReadOnlyMap.Entry<K,V> lowerEntry(K key); 077 078 /** 079 * Returns the greatest key strictly less than the given key, or {@code null} if there is no 080 * such key. 081 * 082 * @param key the key 083 * @return the greatest key less than {@code key}, or {@code null} if there is no such key 084 * 085 * @throws ClassCastException if the specified key cannot be compared with the keys currently 086 * in the map 087 * 088 * @throws NullPointerException if the specified key is null and this map does not permit null 089 * keys 090 */ 091 K lowerKey(K key); 092 093 /** 094 * Returns a key-value mapping associated with the greatest key less than or equal to the given 095 * key, or {@code null} if there is no such key. 096 * 097 * @param key the key 098 * 099 * @return an entry with the greatest key less than or equal to {@code key}, or {@code null} if 100 * there is no such key 101 * 102 * @throws ClassCastException if the specified key cannot be compared with the keys currently 103 * in the map 104 * 105 * @throws NullPointerException if the specified key is null and this map does not permit null 106 * keys 107 */ 108 ReadOnlyMap.Entry<K,V> floorEntry(K key); 109 110 /** 111 * Returns the greatest key less than or equal to the given key, or {@code null} if there is no 112 * such key. 113 * 114 * @param key the key 115 * 116 * @return the greatest key less than or equal to {@code key}, or {@code null} if there is no 117 * such key 118 * 119 * @throws ClassCastException if the specified key cannot be compared with the keys currently 120 * in the map 121 * 122 * @throws NullPointerException if the specified key is null and this map does not permit null 123 * keys 124 */ 125 K floorKey(K key); 126 127 /** 128 * Returns a key-value mapping associated with the least key greater than or equal to the given 129 * key, or {@code null} if there is no such key. 130 * 131 * @param key the key 132 * 133 * @return an entry with the least key greater than or equal to {@code key}, or {@code null} if 134 * there is no such key 135 * 136 * @throws ClassCastException if the specified key cannot be compared with the keys currently in 137 * the map 138 * 139 * @throws NullPointerException if the specified key is null and this map does not permit null 140 * keys 141 */ 142 ReadOnlyMap.Entry<K,V> ceilingEntry(K key); 143 144 /** 145 * Returns the least key greater than or equal to the given key, or {@code null} if there is no 146 * such key. 147 * 148 * @param key the key 149 * 150 * @return the least key greater than or equal to {@code key}, or {@code null} if there is no 151 * such key 152 * 153 * @throws ClassCastException if the specified key cannot be compared with the keys currently 154 * in the map 155 * 156 * @throws NullPointerException if the specified key is null and this map does not permit null 157 * keys 158 */ 159 K ceilingKey(K key); 160 161 /** 162 * Returns a key-value mapping associated with the least key strictly greater than the given 163 * key, or {@code null} if there is no such key. 164 * 165 * @param key the key 166 * 167 * @return an entry with the least key greater than {@code key}, or {@code null} if there is no 168 * such key 169 * 170 * @throws ClassCastException if the specified key cannot be compared with the keys currently 171 * in the map 172 * 173 * @throws NullPointerException if the specified key is null and this map does not permit null 174 * keys 175 */ 176 ReadOnlyMap.Entry<K,V> higherEntry(K key); 177 178 /** 179 * Returns the least key strictly greater than the given key, or {@code null} if there is no 180 * such key. 181 * 182 * @param key the key 183 * 184 * @return the least key greater than {@code key}, or {@code null} if there is no such key 185 * 186 * @throws ClassCastException if the specified key cannot be compared with the keys currently 187 * in the map 188 * 189 * @throws NullPointerException if the specified key is null and this map does not permit null 190 * keys 191 */ 192 K higherKey(K key); 193 194 /** 195 * Returns a key-value mapping associated with the least key in this map, or {@code null} if 196 * the map is empty. 197 * 198 * @return an entry with the least key, or {@code null} if this map is empty 199 */ 200 ReadOnlyMap.Entry<K,V> firstEntry(); 201 202 /** 203 * Returns a key-value mapping associated with the greatest key in this map, or {@code null} if 204 * the map is empty. 205 * 206 * @return an entry with the greatest key, or {@code null} if this map is empty 207 */ 208 ReadOnlyMap.Entry<K,V> lastEntry(); 209 210 /** 211 * Returns a reverse order view of the mappings contained in this map. 212 * @return a reverse order view of this map 213 */ 214 ReadOnlyNavigableMap<K,V> descendingMap(); 215 216 /** 217 * Returns a {@link ReadOnlyNavigableSet} view of the keys contained in this map. The set's 218 * iterator returns the keys in ascending order. 219 * 220 * @return a navigable set view of the keys in this map 221 */ 222 ReadOnlyNavigableSet<K> navigableKeySet(); 223 224 /** 225 * Returns a reverse order {@link ReadOnlyNavigableSet} view of the keys contained in this map. 226 * The set's iterator returns the keys in descending order. 227 * 228 * @return a reverse order navigable set view of the keys in this map 229 */ 230 ReadOnlyNavigableSet<K> descendingKeySet(); 231 232 /** 233 * Returns a view of the portion of this map whose keys range from {@code fromKey} to 234 * {@code toKey}. If {@code fromKey} and {@code toKey} are equal, the returned map is empty 235 * unless {@code fromInclusive} and {@code toInclusive} are both true. 236 * 237 * <BR /><BR />The returned map supports all optional map operations that this map supports. 238 * 239 * @param fromKey low endpoint of the keys in the returned map 240 * @param fromInclusive {@code TRUE} if the low endpoint is to be included in the returned view 241 * @param toKey high endpoint of the keys in the returned map 242 * @param toInclusive {@code TRUE} if the high endpoint is to be included in the returned view 243 * 244 * @return a view of the portion of this map whose keys range from {@code fromKey} to 245 * {@code toKey} 246 * 247 * @throws ClassCastException if {@code fromKey} and {@code toKey} cannot be compared to one 248 * another using this map's comparator (or, if the map has no comparator, using natural 249 * ordering). Implementations may, but are not required to, throw this exception if 250 * {@code fromKey} or {@code toKey} cannot be compared to keys currently in the map. 251 * 252 * @throws NullPointerException if {@code fromKey} or {@code toKey} is null and this map does 253 * not permit null keys 254 * 255 * @throws IllegalArgumentException if {@code fromKey} is greater than {@code toKey}; or if 256 * this map itself has a restricted range, and {@code fromKey} or {@code toKey} lies outside 257 * the bounds of the range 258 */ 259 ReadOnlyNavigableMap<K,V> subMap( 260 K fromKey, boolean fromInclusive, 261 K toKey, boolean toInclusive 262 ); 263 264 /** 265 * Returns a view of the portion of this map whose keys are less than (or 266 * equal to, if {@code inclusive} is true) {@code toKey}. 267 * 268 * The returned map supports all optional map operations that this map supports. 269 * 270 * @param toKey high endpoint of the keys in the returned map 271 * @param inclusive {@code TRUE} if the high endpoint is to be included in the returned view 272 * 273 * @return a view of the portion of this map whose keys are less than (or equal to, if 274 * {@code inclusive} is true) {@code toKey} 275 * 276 * @throws ClassCastException if {@code toKey} is not compatible with this map's comparator 277 * (or, if the map has no comparator, if {@code toKey} does not implement {@link Comparable}). 278 * Implementations may, but are not required to, throw this exception if {@code toKey} cannot 279 * be compared to keys currently in the map. 280 * 281 * @throws NullPointerException if {@code toKey} is null and this map does not permit null keys 282 * 283 * @throws IllegalArgumentException if this map itself has a restricted range, and 284 * {@code toKey} lies outside the bounds of the range 285 */ 286 ReadOnlyNavigableMap<K,V> headMap(K toKey, boolean inclusive); 287 288 /** 289 * Returns a view of the portion of this map whose keys are greater than (or equal to, if 290 * {@code inclusive} is true) {@code fromKey}. 291 * 292 * The returned map supports all optional map operations that this map supports. 293 * 294 * @param fromKey low endpoint of the keys in the returned map 295 * @param inclusive {@code TRUE} if the low endpoint is to be included in the returned view 296 * 297 * @return a view of the portion of this map whose keys are greater than (or equal to, if 298 * {@code inclusive} is true) {@code fromKey} 299 * 300 * @throws ClassCastException if {@code fromKey} is not compatible with this map's comparator 301 * (or, if the map has no comparator, if {@code fromKey} does not implement 302 * {@link Comparable}). Implementations may, but are not required to, throw this exception if 303 * {@code fromKey} cannot be compared to keys currently in the map. 304 * 305 * @throws NullPointerException if {@code fromKey} is null and this map does not permit null 306 * keys 307 * 308 * @throws IllegalArgumentException if this map itself has a restricted range, and 309 * {@code fromKey} lies outside the bounds of the range 310 */ 311 ReadOnlyNavigableMap<K,V> tailMap(K fromKey, boolean inclusive); 312 313 /** 314 * {@inheritDoc} 315 * 316 * <BR /><BR />Equivalent to {@code subMap(fromKey, true, toKey, false)}. 317 * 318 * @throws ClassCastException {@inheritDoc} 319 * @throws NullPointerException {@inheritDoc} 320 * @throws IllegalArgumentException {@inheritDoc} 321 */ 322 ReadOnlySortedMap<K,V> subMap(K fromKey, K toKey); 323 324 /** 325 * {@inheritDoc} 326 * 327 * <BR /><BR />Equivalent to {@code headMap(toKey, false)}. 328 * 329 * @throws ClassCastException {@inheritDoc} 330 * @throws NullPointerException {@inheritDoc} 331 * @throws IllegalArgumentException {@inheritDoc} 332 */ 333 ReadOnlySortedMap<K,V> headMap(K toKey); 334 335 /** 336 * {@inheritDoc} 337 * 338 * <BR /><BR />Equivalent to {@code tailMap(fromKey, true)}. 339 * 340 * @throws ClassCastException {@inheritDoc} 341 * @throws NullPointerException {@inheritDoc} 342 * @throws IllegalArgumentException {@inheritDoc} 343 */ 344 ReadOnlySortedMap<K,V> tailMap(K fromKey); 345 346 /** 347 * {@inheritDoc} 348 * <BR /><BR /> 349 * This method is equivalent to {@link #descendingMap descendingMap}. 350 * 351 * @implSpec 352 * The implementation in this interface returns the result of calling the 353 * {@code descendingMap} method. 354 * 355 * @return a reverse-ordered view of this map, as a {@code NavigableMap} 356 */ 357 default ReadOnlyNavigableMap<K, V> reversed() 358 { return this.descendingMap(); } 359}