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