00001 /* 00002 * NavigableMap.hpp 00003 * 00004 * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. 00005 * 00006 * Oracle is a registered trademarks of Oracle Corporation and/or its 00007 * affiliates. 00008 * 00009 * This software is the confidential and proprietary information of Oracle 00010 * Corporation. You shall not disclose such confidential and proprietary 00011 * information and shall use it only in accordance with the terms of the 00012 * license agreement you entered into with Oracle. 00013 * 00014 * This notice may not be removed or altered. 00015 */ 00016 #ifndef COH_NAVIGABLE_MAP_HPP 00017 #define COH_NAVIGABLE_MAP_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 #include "coherence/util/Comparator.hpp" 00022 #include "coherence/util/Map.hpp" 00023 #include "coherence/util/SortedMap.hpp" 00024 00025 COH_OPEN_NAMESPACE2(coherence,util) 00026 00027 /** 00028 * A SortedMap extended with navigation methods returning the 00029 * closest matches for given search targets. Methods lowerKey, 00030 * floorKey, ceilingKey, and higherKey return only the associated 00031 * keys. All of these methods are designed for locating, not 00032 * traversing entries. 00033 * 00034 * Methods subMap, headMap, tailMap differ from the like-named 00035 * SortedMap methods in accepting additional arguments describing 00036 * whether lower and upper bounds are inclusive versus exclusive. 00037 * Sub-maps of any NavigableMap must implement the NavigableMap 00038 * interface. 00039 * 00040 * This interface additionally defines methods pollFirstEntry 00041 * pollLastEntry that return and remove the least and greatest mappings, 00042 * if any exist, else returning NULL. 00043 * 00044 * Implementations of entry-returning methods are expected to 00045 * return Map.Entry pairs representing snapshots of mappings 00046 * at the time they were produced, and thus generally do <em>not</em> 00047 * support the optional Entry.setValue method. Note however 00048 * that it is possible to change mappings in the associated map using 00049 * method put. 00050 * 00051 * Methods 00052 * #subMap(Object, Object) subMap(K, K), 00053 * #headMap(Object) headMap(K), and 00054 * #tailMap(Object) tailMap(K) 00055 * are specified to return SortedMap to allow existing implementations 00056 * of SortedMap to be compatibly retrofitted to implement NavigableMap, 00057 * but extensions and implementations of this interface are encouraged 00058 * to override these methods to return NavigableMap. 00059 * 00060 * @see Map 00061 * @see TreeMap 00062 * 00063 * @author Wei Lin 2013.08.30 00064 * @since Coherence 12.1.3 00065 */ 00066 class COH_EXPORT NavigableMap 00067 : public interface_spec<NavigableMap, 00068 implements<SortedMap> > 00069 { 00070 public: 00071 using SortedMap::subMap; 00072 using SortedMap::headMap; 00073 using SortedMap::tailMap; 00074 00075 // ----- NavigableMap interface ----------------------------------------- 00076 00077 public: 00078 /** 00079 * Returns the least key greater than or equal to the given key, 00080 * or NULL if there is no such key. 00081 * 00082 * @param vKey the key 00083 * 00084 * @return the least key greater than or equal to the given key, 00085 * or NULL if there is no such key. 00086 * 00087 * @throws ClassCastException if the specified key cannot be compared 00088 * with the keys currently in the map 00089 * @throws NullPointerException if the specified key is NULL 00090 * and this map does not permit NULL keys 00091 */ 00092 virtual Object::View ceilingKey(Object::View vKey) const = 0; 00093 00094 /** 00095 * Returns the greatest key less than or equal to the given key, 00096 * or NULL if there is no such key. 00097 * 00098 * @param vKey the key 00099 * 00100 * @return the greatest key less than or equal to the given key, 00101 * or NULL if there is no such key. 00102 * 00103 * @throws ClassCastException if the specified key cannot be compared 00104 * with the keys currently in the map 00105 * @throws NullPointerException if the specified key is NULL 00106 * and this map does not permit NULL keys 00107 */ 00108 virtual Object::View floorKey(Object::View vKey) const = 0; 00109 00110 /** 00111 * Returns the least key strictly greater than the given key, or 00112 * NULL if there is no such key. 00113 * 00114 * @param vKey the key 00115 * @return the least key greater than the given key, 00116 * or NULL if there is no such key 00117 * 00118 * @throws ClassCastException if the specified key cannot be compared 00119 * with the keys currently in the map 00120 * @throws NullPointerException if the specified key is NULL 00121 * and this map does not permit NULL keys 00122 */ 00123 virtual Object::View higherKey(Object::View vKey) const = 0; 00124 00125 /** 00126 * Returns the greatest key strictly less than the given key, or 00127 * NULL if there is no such key. 00128 * 00129 * @param vKey the key 00130 * @return the greatest key less than the given key, 00131 * or NULL if there is no such key 00132 * 00133 * @throws ClassCastException if the specified key cannot be compared 00134 * with the keys currently in the map 00135 * @throws NullPointerException if the specified key is NULL 00136 * and this map does not permit NULL keys 00137 */ 00138 virtual Object::View lowerKey(Object::View vKey) const = 0; 00139 00140 /** 00141 * Removes and returns a key-value mapping associated with 00142 * the least key in this map, or NULL if the map is empty. 00143 * 00144 * @return the removed first entry of this map, 00145 * or NULL if this map is empty 00146 */ 00147 virtual Map::Entry::Holder pollFirstEntry() = 0; 00148 00149 /** 00150 * Removes and returns a key-value mapping associated with 00151 * the greatest key in this map, or NULL if the map is empty. 00152 * 00153 * @return the removed last entry of this map, 00154 * or NULL if this map is empty 00155 */ 00156 virtual Map::Entry::Holder pollLastEntry() = 0; 00157 00158 /** 00159 * Returns a handle of the portion of the map whose keys are less than (or 00160 * equal to, if toInclusive is true) vToKey. 00161 * The handle is backed by this map, so changes in one show up in the 00162 * other. The sub-map supports all optional operations of the original. 00163 * 00164 * @param vToKey the exclusive upper range of the sub-map 00165 * @param toInclusive true if the high endpoint is to be included 00166 * in the returned view 00167 * 00168 * @return the sub-map 00169 * 00170 * @throws ClassCastException if vToKey is not comparable to the map 00171 * contents 00172 * @throws IllegalArgumentException if this is a sub-map, and vToKey is 00173 * out of range 00174 * @throws NullPointerException if vToKey is NULL but the map does not 00175 * allow NULL keys 00176 */ 00177 virtual NavigableMap::Handle headMap(Object::View vToKey, bool toInclusive) = 0; 00178 00179 /** 00180 * Returns a view of the portion of the map whose keys are less than (or 00181 * equal to, if toInclusive is true) vToKey. 00182 * 00183 * @param vToKey the exclusive upper range of the sub-map 00184 * @param toInclusive true if the high endpoint is to be included 00185 * in the returned view 00186 * 00187 * @return the sub-map 00188 * 00189 * @throws ClassCastException if vToKey is not comparable to the map 00190 * contents 00191 * @throws IllegalArgumentException if this is a sub-map, and toKey is 00192 * out of range 00193 * @throws NullPointerException if vToKey is NULL but the map does not 00194 * allow NULL keys 00195 */ 00196 virtual NavigableMap::View headMap(Object::View vToKey, bool toInclusive) const = 0; 00197 00198 /** 00199 * Returns a handle of the portion of this map whose keys range from 00200 * vFromKey to vToKey. If vFromKey and vToKey are equal, the returned 00201 * map is empty unless fromInclusive and toInclusive are both true. 00202 * The handle is backed by this map, so changes in one show up in the other. 00203 * The sub-map supports all optional operations of the original. 00204 * 00205 * @param vFromKey the inclusive lower range of the sub-map 00206 * @param fromInclusive true if the low endpoint is to be included 00207 * in the returned view 00208 * @param vToKey the exclusive upper range of the sub-map 00209 * @param toInclusive true if the high endpoint is to be included 00210 * in the returned view 00211 * 00212 * @return the sub-map 00213 * 00214 * @throws ClassCastException if vFromKey or vToKey is not comparable to 00215 * the map contents 00216 * @throws IllegalArgumentException if this is a sub-map, and vFromKey or 00217 * vToKey is out of range 00218 * @throws NullPointerException if vFromKey or vToKey is NULL but the map 00219 * does not allow NULL keys 00220 */ 00221 virtual NavigableMap::Handle subMap(Object::View vFromKey, bool fromInclusive, 00222 Object::View vToKey, bool toInclusive) = 0; 00223 00224 /** 00225 * Returns a view of the portion of this map whose keys range from 00226 * vFromKey to vToKey. If vFromKey and vToKey are equal, the returned 00227 * map is empty unless fromInclusive and toInclusive are both true. 00228 * 00229 * @param vFromKey the inclusive lower range of the sub-map 00230 * @param fromInclusive true if the low endpoint is to be included 00231 * in the returned view 00232 * @param vToKey the exclusive upper range of the sub-map 00233 * @param toInclusive true if the high endpoint is to be included 00234 * in the returned view 00235 * 00236 * @return the sub-map 00237 * 00238 * @throws ClassCastException if vFromKey or vToKey is not comparable to 00239 * the map contents 00240 * @throws IllegalArgumentException if this is a sub-map, and vFromKey or 00241 * vToKey is out of range 00242 * @throws NullPointerException if vFromKey or vToKey is NULL but the map 00243 * does not allow NULL keys 00244 */ 00245 virtual NavigableMap::View subMap(Object::View vFromKey, bool fromInclusive, 00246 Object::View vToKey, bool toInclusive) const = 0; 00247 00248 /** 00249 * Returns a handle of the portion of the map whose keys are greater than (or 00250 * equal to, if fromInclusive} is true) vFromKey. 00251 * The handle is backed by this map, so changes in one show up in the 00252 * other. The sub-map supports all optional operations of the original. 00253 * 00254 * @param vFromKey the inclusive lower range of the sub-map 00255 * @param fromInclusive true if the low endpoint is to be included 00256 * in the returned view 00257 * 00258 * @return the sub-map 00259 * 00260 * @throws ClassCastException if vFromKey is not comparable to the map 00261 * contents 00262 * @throws IllegalArgumentException if this is a sub-map, and vFromKey is 00263 * out of range 00264 * @throws NullPointerException if vFromKey is NULL but the map does not 00265 * allow NULL keys 00266 */ 00267 virtual NavigableMap::Handle tailMap(Object::View vFromKey, bool fromInclusive) = 0; 00268 00269 /** 00270 * Returns a view of the portion of the map whose keys are greater than (or 00271 * equal to, if fromInclusive} is true) vFromKey. 00272 * 00273 * @param vFromKey the inclusive lower range of the sub-map 00274 * @param fromInclusive true if the low endpoint is to be included 00275 * in the returned view 00276 * 00277 * @return the sub-map 00278 * 00279 * @throws ClassCastException if vFromKey is not comparable to the map 00280 * contents 00281 * @throws IllegalArgumentException if this is a sub-map, and vFromKey is 00282 * out of range 00283 * @throws NullPointerException if vFromKey is NULL but the map does not 00284 * allow NULL keys 00285 */ 00286 virtual NavigableMap::View tailMap(Object::View vFromKey, bool fromInclusive) const = 0; 00287 }; 00288 00289 COH_CLOSE_NAMESPACE2 00290 00291 #endif // COH_NAVIGABLE_MAP_HPP 00292