Interface Cache<K extends Serializable,V extends Serializable>
-
- All Superinterfaces:
Map<K,V>
- All Known Implementing Classes:
CacheWrapper
,CaffeineCache
,ComponentCacheWrapper
,DefaultCache
public interface Cache<K extends Serializable,V extends Serializable> extends Map<K,V>
General purpose cache. It stores objects associated with unique keys in memory for fast access. All keys and values added to the cache must implement the Serializable interface. Values may implement the Cacheable interface, which allows the cache to determine object size much more quickly. These restrictions allow a cache to never grow larger than a specified number of bytes and to optionally be distributed over a cluster of servers.If the cache does grow too large, objects will be removed such that those that are accessed least frequently are removed first. Because expiration happens automatically, the cache makes no guarantee as to how long an object will remain in cache after it is put in.
Optionally, a maximum lifetime for all objects can be specified. In that case, objects will be deleted from cache after that amount of time, even if they are frequently accessed. This feature is useful if objects put in cache represent data that should be periodically refreshed; for example, information from a database.
All cache operations are thread safe.
Note that neither keys or values can be null; A
NullPointerException
will be thrown attempting to place or retrieve null values in to the cache. Caches can (but need not be) used as a mechanism that is used to share data in an Openfire cluster. When a cache is used for this purpose, it is important to realize that, when joining or leaving a cluster, the cache content will be cleared of all data that was added on the local cluster node. Typically,ClusterEventListener
is used to detect these events and restore the content of the cache.- See Also:
Cacheable
-
-
Field Summary
Fields Modifier and Type Field Description static AtomicBoolean
secretKey
static AtomicBoolean
secretValue
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method Description Set<Map.Entry<K,V>>
entrySet()
IMPORTANT: Unlike the standardMap.entrySet()
implementation, the set returned from this method cannot be modified.long
getCacheHits()
Returns the number of cache hits.long
getCacheMisses()
Returns the number of cache misses.int
getCacheSize()
Deprecated.default Lock
getLock(K key)
Returns an existingLock
on the specified key or creates a new one if none was found.default long
getLongCacheSize()
Returns the size of the cache contents in bytes.long
getMaxCacheSize()
Returns the maximum size of the cache in bytes.long
getMaxLifetime()
Returns the maximum number of milliseconds that any object can live in cache.String
getName()
Returns the name of the cache.default boolean
isKeySecret()
default boolean
isValueSecret()
Set<K>
keySet()
IMPORTANT: Unlike the standardMap.keySet()
implementation, the set returned from this method cannot be modified.void
setMaxCacheSize(int maxSize)
Deprecated.default void
setMaxCacheSize(long maxSize)
Sets the maximum size of the cache in bytes.void
setMaxLifetime(long maxLifetime)
Sets the maximum number of milliseconds that any object can live in cache.void
setName(String name)
Sets the name of the cachedefault void
setSecretKey()
default void
setSecretValue()
Collection<V>
values()
IMPORTANT: Unlike the standardMap.values()
implementation, the collection returned from this method cannot be modified.-
Methods inherited from interface java.util.Map
clear, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, equals, forEach, get, getOrDefault, hashCode, isEmpty, merge, put, putAll, putIfAbsent, remove, remove, replace, replace, replaceAll, size
-
-
-
-
Field Detail
-
secretKey
static final AtomicBoolean secretKey
-
secretValue
static final AtomicBoolean secretValue
-
-
Method Detail
-
getName
String getName()
Returns the name of the cache.- Returns:
- the name of the cache.
-
setName
void setName(String name)
Sets the name of the cache- Parameters:
name
- the name of the cache
-
getMaxCacheSize
long getMaxCacheSize()
Returns the maximum size of the cache in bytes. If the cache grows larger than the max size, the least frequently used items will be removed. If the max cache size is set to -1, there is no size limit.- Returns:
- the maximum size of the cache in bytes.
-
setMaxCacheSize
@Deprecated void setMaxCacheSize(int maxSize)
Deprecated.Sets the maximum size of the cache in bytes limited to integer size. If the cache grows larger than the max size, the least frequently used items will be removed. If the max cache size is set to -1, there is no size limit.Note: If using the Hazelcast clustering plugin, this will not take effect until the next time the cache is created
- Parameters:
maxSize
- the maximum size of the cache in bytes.
-
setMaxCacheSize
default void setMaxCacheSize(long maxSize)
Sets the maximum size of the cache in bytes. If the cache grows larger than the max size, the least frequently used items will be removed. If the max cache size is set to -1, there is no size limit.Note: If using the Hazelcast clustering plugin, this will not take effect until the next time the cache is created
Attention: The default implementation of this method sets the cache value limited to integer size.- Parameters:
maxSize
- the maximum size of the cache in bytes.
-
getMaxLifetime
long getMaxLifetime()
Returns the maximum number of milliseconds that any object can live in cache. Once the specified number of milliseconds passes, the object will be automatically expired from cache. If the max lifetime is set to -1, then objects never expire.- Returns:
- the maximum number of milliseconds before objects are expired.
-
setMaxLifetime
void setMaxLifetime(long maxLifetime)
Sets the maximum number of milliseconds that any object can live in cache. Once the specified number of milliseconds passes, the object will be automatically expired from cache. If the max lifetime is set to -1, then objects never expire.Note: If using the Hazelcast clustering plugin, this will not take effect until the next time the cache is created
- Parameters:
maxLifetime
- the maximum number of milliseconds before objects are expired.
-
getCacheSize
@Deprecated int getCacheSize()
Deprecated.Returns the size of the cache contents in bytes limited to integer size. This value is only a rough approximation, so cache users should expect that actual VM memory used by the cache could be significantly higher than the value reported by this method.- Returns:
- the size of the cache contents in bytes.
-
getLongCacheSize
default long getLongCacheSize()
Returns the size of the cache contents in bytes. This value is only a rough approximation, so cache users should expect that actual VM memory used by the cache could be significantly higher than the value reported by this method. Attention: The default implementation of this method returns the cache value limited to integer size.- Returns:
- the size of the cache contents in bytes.
-
getCacheHits
long getCacheHits()
Returns the number of cache hits. A cache hit occurs every time the get method is called and the cache contains the requested object.Keeping track of cache hits and misses lets one measure how efficient the cache is; the higher the percentage of hits, the more efficient.
- Returns:
- the number of cache hits.
-
getCacheMisses
long getCacheMisses()
Returns the number of cache misses. A cache miss occurs every time the get method is called and the cache does not contain the requested object.Keeping track of cache hits and misses lets one measure how efficient the cache is; the higher the percentage of hits, the more efficient.
- Returns:
- the number of cache hits.
-
values
Collection<V> values()
IMPORTANT: Unlike the standardMap.values()
implementation, the collection returned from this method cannot be modified.- Specified by:
values
in interfaceMap<K extends Serializable,V extends Serializable>
- Returns:
- an unmodifiable collection view of the values contained in this map
-
entrySet
Set<Map.Entry<K,V>> entrySet()
IMPORTANT: Unlike the standardMap.entrySet()
implementation, the set returned from this method cannot be modified.- Specified by:
entrySet
in interfaceMap<K extends Serializable,V extends Serializable>
- Returns:
- an unmodifiable set view of the mappings contained in this map
-
keySet
Set<K> keySet()
IMPORTANT: Unlike the standardMap.keySet()
implementation, the set returned from this method cannot be modified.- Specified by:
keySet
in interfaceMap<K extends Serializable,V extends Serializable>
- Returns:
- an unmodifiable set view of the keys contained in this map
-
getLock
default Lock getLock(K key)
Returns an existingLock
on the specified key or creates a new one if none was found. This operation is thread safe. Successive calls with the same key may or may not return the sameLock
. However, different threads asking for the same Lock at the same time will get the same Lock object.The supplied cache may or may not be used depending whether the server is running on cluster mode or not. When not running as part of a cluster then the lock will be unrelated to the cache and will only be visible in this JVM.
- Parameters:
key
- the object that defines the visibility or scope of the lock.- Returns:
- an existing lock on the specified key or creates a new one if none was found.
-
setSecretKey
default void setSecretKey()
-
setSecretValue
default void setSecretValue()
-
isKeySecret
default boolean isKeySecret()
-
isValueSecret
default boolean isValueSecret()
-
-