00001 /* 00002 * Map.hpp 00003 * 00004 * Copyright (c) 2000, 2014, 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 00295 COH_CLOSE_NAMESPACE2 00296 00297 #endif // COH_MAP_HPP