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