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

- Main Page
- Namespaces
- Classes
- Files

# coherence/net/cache/CacheMap.hpp

    00001 /*
    00002 * CacheMap.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_CACHE_MAP_HPP
    00017 #define COH_CACHE_MAP_HPP
    00018
    00019 #include "coherence/lang.ns"
    00020
    00021 #include "coherence/util/Collection.hpp"
    00022 #include "coherence/util/Map.hpp"
    00023
    00024 COH_OPEN_NAMESPACE3(coherence,net,cache)
    00025
    00026 using coherence::util::Collection;
    00027 using coherence::util::Map;
    00028
    00029
    00030 /**
    00031 * A CacheMap is a coherence::util::Map that supports caching.
    00032 *
    00033 * CacheMaps maintain immutable copies of the cached entries. Thus any
    00034 * non-immutable item supplied to the cache will be cloned.  All results from
    00035 * the cache will be accessable only via Views.
    00036 *
    00037 * @author mf  2007.11.07
    00038 */
    00039 class COH_EXPORT CacheMap
    00040     : public interface_spec<CacheMap,
    00041         implements<Map> >
    00042     {
    00043     // ----- CacheMap interface ---------------------------------------------
    00044
    00045     public:
    00046         /**
    00047         * Get all the specified keys, if they are in the %cache. For each key
    00048         * that is in the %cache, that key and its corresponding value will be
    00049         * placed in the map that is returned by this method. The absence of a
    00050         * key in the returned map indicates that it was not in the %cache,
    00051         * which may imply (for caches that can load behind the scenes) that
    00052         * the requested data could not be loaded.
    00053         *
    00054         * The result of this method is defined to be semantically the same as
    00055         * the following implementation, without regards to threading issues:
    00056         * @code
    00057         * // could be a HashMap (but does not have to)
    00058         * Map::Handle hMap = SomeMap::create();
    00059         *
    00060         * for (Iterator::Handle iter = colKeys->iterator(); iter->hasNext();)
    00061         *     {
    00062         *     Object::View hKey = iter->next();
    00063         *     Object::View hVal = get(hKey);
    00064         *     if (hVal || containsKey(hKey))
    00065         *         {
    00066         *         hMap->put(hKey, hVal);
    00067         *         }
    00068         *     }
    00069         * return hMap;
    00070         * @endcode
    00071         *
    00072         * @param vKeys a collection of keys that may be in the named %cache
    00073         *
    00074         * @return a coherence::util::Map of keys to values for the specified
    00075         * keys passed in @a vKeys
    00076         */
    00077         virtual Map::View getAll(Collection::View vKeys) const = 0;
    00078
    00079         /**
    00080         * Associates the specified value with the specified key in this
    00081         * cache. If the cache previously contained a mapping for this key,
    00082         * the old value is replaced. This variation of the
    00083         * put(Object::View, Object::View) method allows the caller to specify
    00084         * an expiry (or "time to live") for the %cache entry.
    00085         *
    00086         * @param vKey    key with which the specified value is to be
    00087         *                 associated
    00088         * @param ohValue  value to be associated with the specified key
    00089         * @param cMillis  the number of milliseconds until the %cache entry
    00090         *                 will expire, also referred to as the entry's "time
    00091         *                 to live"; pass #EXPIRY_DEFAULT to use the %cache's
    00092         *                 default time-to-live setting; pass #EXPIRY_NEVER to
    00093         *                 indicate that the %cache entry should never expire;
    00094         *                 this milliseconds value is <b>not</b> a date/time
    00095         *                 value
    00096         *
    00097         * @return previous value associated with specified key, or empty
    00098         *         handle if there was no mapping for key. An empty handle
    00099         *         return can also indicate that the map previously associated
    00100         *         NULL with the specified key, if the implementation supports
    00101         *         NULL values
    00102         *
    00103         * @throws coherence::lang::UnsupportedOperationException
    00104         *         if the requested expiry is a positive value and the
    00105         *         implementation does not support expiry of %cache entries
    00106         */
    00107         virtual Object::Holder put
    00108             (Object::View vKey, Object::Holder ohValue, int64_t cMillis) = 0;
    00109
    00110         /**
    00111         * Associates the specified value with the specified key in this
    00112         * cache. If the cache previously contained a mapping for this key,
    00113         * the old value is replaced.
    00114         *
    00115         * Invoking this method is equivalent to the following call:
    00116         * @code
    00117         * put(vKey, vValue, EXPIRY_DEFAULT);
    00118         * @endcode
    00119         *
    00120         * @param vKey    key with which the specified value is to be
    00121         *                 associated
    00122         * @param ohValue  value to be associated with the specified key
    00123         *
    00124         * @return previous value associated with specified key, or empty
    00125         *         handle if there was no mapping for key. An empty handle
    00126         *         return can also indicate that the map previously associated
    00127         *         NULL with the specified key, if the implementation supports
    00128         *         NULL values
    00129         */
    00130         using Map::put;
    00131
    00132
    00133     // ----- constants ------------------------------------------------------
    00134
    00135     public:
    00136         /**
    00137         * A special time-to-live value that can be passed to the extended
    00138         * put(Object#Handle, Object#Handle, int64_t) method to indicate that
    00139         * the %cache's default expiry should be used.
    00140         */
    00141         static const int64_t EXPIRY_DEFAULT = 0;
    00142
    00143         /**
    00144         * A special time-to-live value that can be passed to the extended
    00145         * put(Object#Handle, Object#Handle, int64_t) method to indicate that the
    00146         * %cache entry should never expire.
    00147         */
    00148         static const int64_t EXPIRY_NEVER   = -1;
    00149     };
    00150
    00151 COH_CLOSE_NAMESPACE3
    00152
    00153 #endif // COH_CACHE_MAP_HPP

Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.