00001 /* 00002 * CacheMap.hpp 00003 * 00004 * Copyright (c) 2000, 2013, 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