00001 /* 00002 * Map.hpp 00003 * 00004 * Copyright (c) 2000, 2017, 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_MAP_HPP 00017 #define COH_MAP_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 #include "coherence/util/Collection.hpp" 00022 #include "coherence/util/Iterator.hpp" 00023 #include "coherence/util/Set.hpp" 00024 00025 #include "coherence/io/pof/PofIntrinsic.hpp" 00026 00027 COH_OPEN_NAMESPACE2(coherence,util) 00028 00029 /** 00030 * An interface for associating key value pairs. 00031 * 00032 * @see Collection 00033 * @see Set 00034 */ 00035 class COH_EXPORT Map 00036 : public interface_spec<Map, 00037 implements<coherence::io::pof::PofIntrinsic> > 00038 { 00039 // ----- nested interface: Entry ---------------------------------------- 00040 00041 public: 00042 00043 /** 00044 * A map entry (key-value pair). The <tt>Map::entrySet</tt> method 00045 * returns a collection-view of the map, whose elements are of this 00046 * class. The <i>only</i> way to obtain a reference to a map entry is 00047 * from the iterator of this collection-view. These 00048 * <tt>Map::Entry</tt> objects are valid <i>only</i> for the duration 00049 * of the iteration; more formally, the behavior of a map entry is 00050 * undefined if the backing map has been modified after the entry was 00051 * returned by the iterator. 00052 * 00053 * @see Map#entrySet() 00054 */ 00055 class COH_EXPORT Entry 00056 : public interface_spec<Entry> 00057 { 00058 // ----- Map::Entry interface ----------------------------------- 00059 00060 public: 00061 /** 00062 * Return the key corresponding to this entry. 00063 * 00064 * @return the key corresponding to this entry. 00065 */ 00066 virtual Object::View getKey() const = 0; 00067 00068 /** 00069 * Return the value corresponding to this entry. 00070 * 00071 * @return the value corresponding to this entry. 00072 */ 00073 virtual Object::Holder getValue() const = 0; 00074 00075 /** 00076 * Return the value corresponding to this entry. 00077 * 00078 * @return the value corresponding to this entry. 00079 */ 00080 virtual Object::Holder getValue() = 0; 00081 00082 /** 00083 * Update the value corresponding to this entry. 00084 * 00085 * @param ohValue the new value for the entry 00086 * 00087 * @return the prior value 00088 */ 00089 virtual Object::Holder setValue(Object::Holder ohValue) = 0; 00090 }; 00091 00092 00093 // ----- Map interface -------------------------------------------------- 00094 00095 public: 00096 /** 00097 * Return the number of key-value mappings in this map. 00098 * 00099 * @return the number of key-value mappings in this map. 00100 */ 00101 virtual size32_t size() const = 0; 00102 00103 /** 00104 * Return <tt>true</tt> if this map contains no key-value mappings. 00105 * 00106 * @return <tt>true</tt> if this map contains no key-value mappings. 00107 */ 00108 virtual bool isEmpty() const = 0; 00109 00110 /** 00111 * Return <tt>true</tt> if this map contains a mapping for the 00112 * specified key. 00113 * 00114 * @param vKey key whose presence in this map is to be tested. 00115 * 00116 * @return <tt>true</tt> if this map contains a mapping for the 00117 * specified key. 00118 */ 00119 virtual bool containsKey(Object::View vKey) const = 0; 00120 00121 /** 00122 * Return <tt>true</tt> if this map maps one or more keys to the 00123 * specified value. This operation will probably require time linear 00124 * in the map size for most implementations of the <tt>Map</tt> 00125 * interface. 00126 * 00127 * @param vValue value whose presence in this map is to be tested. 00128 * 00129 * @return <tt>true</tt> if this map maps one or more keys to the 00130 * specified value. 00131 */ 00132 virtual bool containsValue(Object::View vValue) const = 0; 00133 00134 /** 00135 * Return the value to which this map maps the specified key. Return 00136 * <tt>NULL</tt> if the map contains no mapping for this key. A return 00137 * value of <tt>NULL</tt> does not <i>necessarily</i> indicate that 00138 * the map contains no mapping for the key; it's also possible that 00139 * the map explicitly maps the key to <tt>NULL</tt>. 00140 * The <tt>containsKey</tt> operation may be used to distinguish these 00141 * two cases. 00142 * 00143 * @param vKey key whose associated value is to be returned. 00144 * 00145 * @return the value to which this map maps the specified key, or 00146 * <tt>NULL</tt> if the map contains no mapping for this key. 00147 * 00148 * @see #containsKey() 00149 */ 00150 virtual Object::Holder get(Object::View vKey) const = 0; 00151 00152 /** 00153 * Return the value to which this map maps the specified key. Return 00154 * <tt>NULL</tt> if the map contains no mapping for this key. A return 00155 * value of <tt>NULL</tt> does not <i>necessarily</i> indicate that 00156 * the map contains no mapping for the key; it's also possible that 00157 * the map explicitly maps the key to <tt>NULL</tt>. 00158 * The <tt>containsKey</tt> operation may be used to distinguish these 00159 * two cases. 00160 * 00161 * @param vKey key whose associated value is to be returned. 00162 * 00163 * @return the value to which this map maps the specified key, or 00164 * <tt>NULL</tt> if the map contains no mapping for this key. 00165 * 00166 * @see #containsKey() 00167 */ 00168 virtual Object::Holder get(Object::View vKey) = 0; 00169 00170 /** 00171 * Associate the specified value with the specified key in this map. 00172 * If the map previously contained a mapping for this key, the old 00173 * value is replaced by the specified value. 00174 * 00175 * @param vKey key with which the specified value is to be associated. 00176 * @param ohValue value to be associated with the specified key. 00177 * 00178 * @return previous value associated with specified key, or 00179 * <tt>NULL</tt> if there was no mapping for key. A 00180 * <tt>NULL</tt> return can also indicate that the map 00181 * previously associated <tt>NULL</tt> with the specified key. 00182 * 00183 * @throws coherence::lang::UnsupportedOperationException 00184 * if the #put() operation is not supported by this map. 00185 */ 00186 virtual Object::Holder put(Object::View vKey, Object::Holder ohValue) = 0; 00187 00188 /** 00189 * Remove the mapping for this key from this map if it is present. 00190 * 00191 * Return the value to which the map previously associated the key, or 00192 * <tt>NULL</tt> if the map contained no mapping for this key. (A 00193 * <tt>NULL</tt> return can also indicate that the map previously 00194 * associated <tt>NULL</tt> with the specified key.) The map will not 00195 * contain a mapping for the specified key once the call returns. 00196 * 00197 * @param vKey key whose mapping is to be removed from the map. 00198 * 00199 * @return previous value associated with specified key, or <tt>NULL</tt> 00200 * if there was no mapping for key. 00201 * 00202 * @throws coherence::lang::UnsupportedOperationException 00203 * if the #remove() operation is not supported by this map. 00204 */ 00205 virtual Object::Holder remove(Object::View vKey) = 0; 00206 00207 /** 00208 * Copy all of the mappings from the specified map to this map. 00209 * The effect of this call is equivalent to that of calling 00210 * {@link #put() put(k, v)} on this map once for each mapping from 00211 * key <tt>k</tt> to value <tt>v</tt> in the specified map. The 00212 * behavior of this operation is unspecified if the specified map is 00213 * modified while the operation is in progress. 00214 * 00215 * @param vMap mappings to be stored in this map. 00216 * 00217 * @throws coherence::lang::UnsupportedOperationException 00218 * if the #put() operation is not supported by this map. 00219 */ 00220 virtual void putAll(Map::View vMap) = 0; 00221 00222 /** 00223 * Remove all mappings from this map. 00224 * 00225 * @throws coherence::lang::UnsupportedOperationException 00226 * if the #clear()operation is not supported by this map. 00227 */ 00228 virtual void clear() = 0; 00229 00230 /** 00231 * Return a set of the keys contained in this map. The set is backed 00232 * by the map, so changes to the map are reflected in the 00233 * set. If the map is modified while an iteration over the set is in 00234 * progress, the results of the iteration are undefined. 00235 * 00236 * @return a set of the keys contained in this map. 00237 */ 00238 virtual Set::View keySet() const = 0; 00239 00240 /** 00241 * Return a set of the keys contained in this map. The set is backed 00242 * by the map, so changes to one are reflected in the 00243 * other. If the map is modified while an iteration over the set is in 00244 * progress, the results of the iteration are undefined. 00245 * 00246 * @return a set of the keys contained in this map. 00247 */ 00248 virtual Set::Handle keySet() = 0; 00249 00250 /** 00251 * Return a collection of the values contained in this map. The 00252 * collection is backed by the map, so changes to the map are 00253 * reflected in the set. If the map is modified while an 00254 * iteration over the collection is in progress, the results of the 00255 * iteration are undefined. 00256 * 00257 * @return a collection of the values contained in this map. 00258 */ 00259 virtual Collection::View values() const = 0; 00260 00261 /** 00262 * Return a collection of the values contained in this map. The 00263 * collection is backed by the map, so changes to one are 00264 * reflected in the other. If the map is modified while an 00265 * iteration over the collection is in progress, the results of the 00266 * iteration are undefined. 00267 * 00268 * @return a collection of the values contained in this map. 00269 */ 00270 virtual Collection::Handle values() = 0; 00271 00272 /** 00273 * Return a set of the mappings contained in this map. Each element in 00274 * the returned set is a {@link Map::Entry::View}. The set is backed 00275 * by the map, so changes to the map are reflected in the set. If the 00276 * map is modified while an iteration over the set is in progress, the 00277 * results of the iteration are undefined. 00278 * 00279 * @return a set of the mappings contained in this map. 00280 */ 00281 virtual Set::View entrySet() const = 0; 00282 00283 /** 00284 * Return a set of the mappings contained in this map. Each element in 00285 * the returned set is a {@link Map::Entry::Handle}. The set is 00286 * backed by the map, so changes to one are reflected in the other. If 00287 * the map is modified while an iteration over the set is in progress, 00288 * the results of the iteration are undefined. 00289 * 00290 * @return a set of the mappings contained in this map. 00291 */ 00292 virtual Set::Handle entrySet() = 0; 00293 00294 // ----- Defaultable methods ---------------------------------------- 00295 00296 /** 00297 * Returns the value to which the specified key is mapped, or 00298 * ohDefaultValue if this map contains no mapping for the key. 00299 * 00300 * The default implementation makes no guarantees about 00301 * synchronization or atomicity properties of this method. Any 00302 * implementation providing atomicity guarantees must override this 00303 * method and document its concurrency properties. 00304 * 00305 * @param vKey key with which the specified value is to be associated. 00306 * @param ohDefaultValue value to be associated with the specified key. 00307 * 00308 * @return the value to which the specified key is mapped, or 00309 * ohDefaultValue if this map contains no mapping for the key 00310 * 00311 * @since 12.2.1 00312 */ 00313 virtual Object::Holder getOrDefault(Object::View vKey, 00314 Object::Holder ohDefaultValue) const 00315 { 00316 Object::Holder oh; 00317 return (((oh = get(vKey)) != NULL) || containsKey(vKey)) 00318 ? oh 00319 : ohDefaultValue; 00320 } 00321 00322 /** 00323 * If the specified key is not already associated with a value (or 00324 * is mapped to NULL) associates it with the given value and returns NULL, 00325 * else returns the current value. 00326 * 00327 * The default implementation makes no guarantees about synchronization 00328 * or atomicity properties of this method. Any implementation providing atomicity 00329 * guarantees must override this method and document its concurrency properties. 00330 * 00331 * @param vKey key with which the specified value is to be associated. 00332 * @param ohValue value to be associated with the specified key. 00333 * 00334 * @return the previous value associated with the specified key, or NULL 00335 * if there was no mapping for the key. (A NULL return can also indicate 00336 * that the map previously associated NULL with the key, if the 00337 * implementation supports NULL values.) 00338 * 00339 * @since 12.2.1 00340 */ 00341 virtual Object::Holder putIfAbsent(Object::View vKey, Object::Holder ohValue) 00342 { 00343 Object::Holder oh = get(vKey); 00344 if (oh == NULL) 00345 { 00346 oh = put(vKey, ohValue); 00347 } 00348 00349 return oh; 00350 } 00351 00352 /** 00353 * Removes the entry for the specified key only if it is currently 00354 * mapped to the specified value. 00355 * 00356 * The default implementation makes no guarantees about synchronization 00357 * or atomicity properties of this method. Any implementation providing 00358 * atomicity guarantees must override this method and document its concurrency properties. 00359 * 00360 * @param vKey key associated with the specified value to be removed. 00361 * @param vValue value to be removed, if it is associated with the specified key. 00362 * 00363 * @return true if the value was removed 00364 * 00365 * @since 12.2.1 00366 */ 00367 virtual bool remove(Object::View vKey, Object::View vValue) 00368 { 00369 Object::View vCurValue = get(vKey); 00370 if (!equals(vCurValue, vValue) || 00371 (vCurValue == NULL && !containsKey(vKey))) 00372 { 00373 return false; 00374 } 00375 remove(vKey); 00376 return true; 00377 } 00378 00379 /** 00380 * Replaces the entry for the specified key only if currently mapped to 00381 * the specified value. 00382 * 00383 * The default implementation does not throw NullPointerException for maps that 00384 * do not support NULL values if oldValue is NULL unless newValue is also NULL. 00385 * 00386 * The default implementation makes no guarantees about synchronization or 00387 * atomicity properties of this method. Any implementation providing atomicity 00388 * guarantees must override this method and document its concurrency properties. 00389 * 00390 * @param vKey key associated with the specified value to be replace. 00391 * @param vOldValue value to be replaced, if it is associated with the specified key. 00392 * @param ohNewValue value to replace old value, if old value is 00393 * associated with the specified key. 00394 * 00395 * @return true if the value was replaced 00396 * 00397 * @since 12.2.1 00398 */ 00399 virtual bool replace(Object::View vKey, Object::View vOldValue, Object::Holder ohNewValue) 00400 { 00401 Object::View vCurValue = get(vKey); 00402 if (!equals(vCurValue, vOldValue) || 00403 (vCurValue == NULL && !containsKey(vKey))) 00404 { 00405 return false; 00406 } 00407 put(vKey, ohNewValue); 00408 return true; 00409 } 00410 00411 /** 00412 * Replaces the entry for the specified key only if it is currently mapped to some value. 00413 * 00414 * The default implementation makes no guarantees about synchronization or 00415 * atomicity properties of this method. Any implementation providing atomicity 00416 * guarantees must override this method and document its concurrency properties. 00417 * 00418 * @param vKey key associated with the specified value to be replace. 00419 * @param vValue new value used to replace, if any value is associated 00420 * with the specified key. 00421 * 00422 * @return the previous value associated with the specified key, or NULL if 00423 * there was no mapping for the key. (A NULL return can also indicate that 00424 * the map previously associated NULL with the key, if the implementation 00425 * supports NULL values.) 00426 * 00427 * @since 12.2.1 00428 */ 00429 virtual Object::Holder replace(Object::View vKey, Object::Holder ohValue) 00430 { 00431 Object::Holder ohCurValue; 00432 if (((ohCurValue = get(vKey)) != NULL) || containsKey(vKey)) 00433 { 00434 ohCurValue = put(vKey, ohValue); 00435 } 00436 return ohCurValue; 00437 } 00438 }; 00439 00440 COH_CLOSE_NAMESPACE2 00441 00442 #endif // COH_MAP_HPP