C++ Client API Reference for Oracle Coherence
14c (14.1.2.0.0)

F79659-03

coherence/net/cache/CacheMap.hpp

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
Copyright © 2000, 2025, Oracle and/or its affiliates. Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.