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