coherence/net/cache/CacheMap.hpp

00001 /*
00002 * CacheMap.hpp
00003 *
00004 * Copyright 2001-2008 by Oracle. 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 (c) 2000-2008 Oracle. All rights reserved.