Oracle Coherence for C++ API
Release 3.7.0.0

E18684-01

coherence/util/Map.hpp

00001 /*
00002 * Map.hpp
00003 *
00004 * Copyright (c) 2000, 2011, 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
Copyright © 2000, 2011, Oracle and/or its affiliates. All rights reserved.