00001 /* 00002 * Map.hpp 00003 * 00004 * Copyright (c) 2000, 2009, 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 COH_OPEN_NAMESPACE2(coherence,util) 00026 00027 00028 /** 00029 * An interface for associating key value pairs. 00030 * 00031 * @see Collection 00032 * @see Set 00033 */ 00034 class COH_EXPORT Map 00035 : public interface_spec<Map> 00036 { 00037 // ----- nested interface: Entry ---------------------------------------- 00038 00039 public: 00040 00041 /** 00042 * A map entry (key-value pair). The <tt>Map::entrySet</tt> method 00043 * returns a collection-view of the map, whose elements are of this 00044 * class. The <i>only</i> way to obtain a reference to a map entry is 00045 * from the iterator of this collection-view. These 00046 * <tt>Map::Entry</tt> objects are valid <i>only</i> for the duration 00047 * of the iteration; more formally, the behavior of a map entry is 00048 * undefined if the backing map has been modified after the entry was 00049 * returned by the iterator. 00050 * 00051 * @see Map#entrySet() 00052 */ 00053 class COH_EXPORT Entry 00054 : public interface_spec<Entry> 00055 { 00056 // ----- Map::Entry interface ----------------------------------- 00057 00058 public: 00059 /** 00060 * Return the key corresponding to this entry. 00061 * 00062 * @return the key corresponding to this entry. 00063 */ 00064 virtual Object::View getKey() 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() const = 0; 00072 00073 /** 00074 * Return the value corresponding to this entry. 00075 * 00076 * @return the value corresponding to this entry. 00077 */ 00078 virtual Object::Holder getValue() = 0; 00079 00080 /** 00081 * Update the value corresponding to this entry. 00082 * 00083 * @param ohValue the new value for the entry 00084 * 00085 * @return the prior value 00086 */ 00087 virtual Object::Holder setValue(Object::Holder ohValue) = 0; 00088 }; 00089 00090 00091 // ----- Map interface -------------------------------------------------- 00092 00093 public: 00094 /** 00095 * Return the number of key-value mappings in this map. 00096 * 00097 * @return the number of key-value mappings in this map. 00098 */ 00099 virtual size32_t size() const = 0; 00100 00101 /** 00102 * Return <tt>true</tt> if this map contains no key-value mappings. 00103 * 00104 * @return <tt>true</tt> if this map contains no key-value mappings. 00105 */ 00106 virtual bool isEmpty() const = 0; 00107 00108 /** 00109 * Return <tt>true</tt> if this map contains a mapping for the 00110 * specified key. 00111 * 00112 * @param vKey key whose presence in this map is to be tested. 00113 * 00114 * @return <tt>true</tt> if this map contains a mapping for the 00115 * specified key. 00116 */ 00117 virtual bool containsKey(Object::View vKey) const = 0; 00118 00119 /** 00120 * Return <tt>true</tt> if this map maps one or more keys to the 00121 * specified value. This operation will probably require time linear 00122 * in the map size for most implementations of the <tt>Map</tt> 00123 * interface. 00124 * 00125 * @param vValue value whose presence in this map is to be tested. 00126 * 00127 * @return <tt>true</tt> if this map maps one or more keys to the 00128 * specified value. 00129 */ 00130 virtual bool containsValue(Object::View vValue) const = 0; 00131 00132 /** 00133 * Return the value to which this map maps the specified key. Return 00134 * <tt>NULL</tt> if the map contains no mapping for this key. A return 00135 * value of <tt>NULL</tt> does not <i>necessarily</i> indicate that 00136 * the map contains no mapping for the key; it's also possible that 00137 * the map explicitly maps the key to <tt>NULL</tt>. 00138 * The <tt>containsKey</tt> operation may be used to distinguish these 00139 * two cases. 00140 * 00141 * @param vKey key whose associated value is to be returned. 00142 * 00143 * @return the value to which this map maps the specified key, or 00144 * <tt>NULL</tt> if the map contains no mapping for this key. 00145 * 00146 * @see #containsKey() 00147 */ 00148 virtual Object::Holder get(Object::View vKey) const = 0; 00149 00150 /** 00151 * Return the value to which this map maps the specified key. Return 00152 * <tt>NULL</tt> if the map contains no mapping for this key. A return 00153 * value of <tt>NULL</tt> does not <i>necessarily</i> indicate that 00154 * the map contains no mapping for the key; it's also possible that 00155 * the map explicitly maps the key to <tt>NULL</tt>. 00156 * The <tt>containsKey</tt> operation may be used to distinguish these 00157 * two cases. 00158 * 00159 * @param vKey key whose associated value is to be returned. 00160 * 00161 * @return the value to which this map maps the specified key, or 00162 * <tt>NULL</tt> if the map contains no mapping for this key. 00163 * 00164 * @see #containsKey() 00165 */ 00166 virtual Object::Holder get(Object::View vKey) = 0; 00167 00168 /** 00169 * Associate the specified value with the specified key in this map. 00170 * If the map previously contained a mapping for this key, the old 00171 * value is replaced by the specified value. 00172 * 00173 * @param vKey key with which the specified value is to be associated. 00174 * @param ohValue value to be associated with the specified key. 00175 * 00176 * @return previous value associated with specified key, or 00177 * <tt>NULL</tt> if there was no mapping for key. A 00178 * <tt>NULL</tt> return can also indicate that the map 00179 * previously associated <tt>NULL</tt> with the specified key. 00180 * 00181 * @throws coherence::lang::UnsupportedOperationException 00182 * if the #put() operation is not supported by this map. 00183 */ 00184 virtual Object::Holder put(Object::View vKey, Object::Holder ohValue) = 0; 00185 00186 /** 00187 * Remove the mapping for this key from this map if it is present. 00188 * 00189 * Return the value to which the map previously associated the key, or 00190 * <tt>NULL</tt> if the map contained no mapping for this key. (A 00191 * <tt>NULL</tt> return can also indicate that the map previously 00192 * associated <tt>NULL</tt> with the specified key.) The map will not 00193 * contain a mapping for the specified key once the call returns. 00194 * 00195 * @param vKey key whose mapping is to be removed from the map. 00196 * 00197 * @return previous value associated with specified key, or <tt>NULL</tt> 00198 * if there was no mapping for key. 00199 * 00200 * @throws coherence::lang::UnsupportedOperationException 00201 * if the #remove() operation is not supported by this map. 00202 */ 00203 virtual Object::Holder remove(Object::View vKey) = 0; 00204 00205 /** 00206 * Copy all of the mappings from the specified map to this map. 00207 * The effect of this call is equivalent to that of calling 00208 * {@link #put() put(k, v)} on this map once for each mapping from 00209 * key <tt>k</tt> to value <tt>v</tt> in the specified map. The 00210 * behavior of this operation is unspecified if the specified map is 00211 * modified while the operation is in progress. 00212 * 00213 * @param vMap mappings to be stored in this map. 00214 * 00215 * @throws coherence::lang::UnsupportedOperationException 00216 * if the #put() operation is not supported by this map. 00217 */ 00218 virtual void putAll(Map::View vMap) = 0; 00219 00220 /** 00221 * Remove all mappings from this map. 00222 * 00223 * @throws coherence::lang::UnsupportedOperationException 00224 * if the #clear()operation is not supported by this map. 00225 */ 00226 virtual void clear() = 0; 00227 00228 /** 00229 * Return a set of the keys contained in this map. The set is backed 00230 * by the map, so changes to the map are reflected in the 00231 * set. If the map is modified while an iteration over the set is in 00232 * progress, the results of the iteration are undefined. 00233 * 00234 * @return a set of the keys contained in this map. 00235 */ 00236 virtual Set::View keySet() const = 0; 00237 00238 /** 00239 * Return a set of the keys contained in this map. The set is backed 00240 * by the map, so changes to one are reflected in the 00241 * other. If the map is modified while an iteration over the set is in 00242 * progress, the results of the iteration are undefined. 00243 * 00244 * @return a set of the keys contained in this map. 00245 */ 00246 virtual Set::Handle keySet() = 0; 00247 00248 /** 00249 * Return a collection of the values contained in this map. The 00250 * collection is backed by the map, so changes to the map are 00251 * reflected in the set. If the map is modified while an 00252 * iteration over the collection is in progress, the results of the 00253 * iteration are undefined. 00254 * 00255 * @return a collection of the values contained in this map. 00256 */ 00257 virtual Collection::View values() const = 0; 00258 00259 /** 00260 * Return a collection of the values contained in this map. The 00261 * collection is backed by the map, so changes to one are 00262 * reflected in the other. If the map is modified while an 00263 * iteration over the collection is in progress, the results of the 00264 * iteration are undefined. 00265 * 00266 * @return a collection of the values contained in this map. 00267 */ 00268 virtual Collection::Handle values() = 0; 00269 00270 /** 00271 * Return a set of the mappings contained in this map. Each element in 00272 * the returned set is a {@link Map::Entry::View}. The set is backed 00273 * by the map, so changes to the map are reflected in the set. If the 00274 * map is modified while an iteration over the set is in progress, the 00275 * results of the iteration are undefined. 00276 * 00277 * @return a set of the mappings contained in this map. 00278 */ 00279 virtual Set::View entrySet() const = 0; 00280 00281 /** 00282 * Return a set of the mappings contained in this map. Each element in 00283 * the returned set is a {@link Map::Entry::Handle}. The set is 00284 * backed by the map, so changes to one are reflected in the other. If 00285 * the map is modified while an iteration over the set is in progress, 00286 * the results of the iteration are undefined. 00287 * 00288 * @return a set of the mappings contained in this map. 00289 */ 00290 virtual Set::Handle entrySet() = 0; 00291 }; 00292 00293 COH_CLOSE_NAMESPACE2 00294 00295 #endif // COH_MAP_HPP