Oracle Coherence for C++ API
Release 3.6.1.0
E18813-01

- Main Page
- Namespaces
- Classes
- Files

# coherence/util/Map.hpp

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