Package org.apache.commons.jcs3.access

Class CacheAccess<K,V>

java.lang.Object

org.apache.commons.jcs3.access.AbstractCacheAccess<K,V>

org.apache.commons.jcs3.access.CacheAccess<K,V>

All Implemented Interfaces:

ICacheAccess<K,V>, ICacheAccessManagement

public class CacheAccess<K,V>
extends AbstractCacheAccess<K,V>
implements ICacheAccess<K,V>

This class provides an interface for all types of access to the cache.

An instance of this class is tied to a specific cache region. Static methods are provided to get such instances.

Using this class you can retrieve an item, the item's wrapper, and the element's configuration. You can also put an item in the cache, remove an item, and clear a region.

The JCS class is the preferred way to access these methods.

Constructor Summary

Constructors

Constructor	Description
CacheAccess(CompositeCache<K,V> cacheControl)	Constructor for the CacheAccess object.

Method Summary

Modifier and Type	Method	Description
V	get(K name)	Retrieve an object from the cache region this instance provides access to.
V	get(K name, Supplier<V> supplier)	Retrieve an object from the cache region this instance provides access to.
ICacheElement<K,V>	getCacheElement(K name)	This method returns the ICacheElement<K, V> wrapper which provides access to element info and other attributes.
Map<K,ICacheElement<K,V>>	getCacheElements(Set<K> names)	Get multiple elements from the cache based on a set of cache keys.
IElementAttributes	getElementAttributes(K name)	GetElementAttributes will return an attribute object describing the current attributes associated with the object name.
Map<K,V>	getMatching(String pattern)	Retrieve matching objects from the cache region this instance provides access to.
Map<K,ICacheElement<K,V>>	getMatchingCacheElements(String pattern)	Get multiple elements from the cache based on a set of cache keys.
void	put(K name, V obj)	Place a new object in the cache, associated with key name.
void	put(K key, V val, IElementAttributes attr)	Constructs a cache element with these attributes, and puts it into the cache.
void	putSafe(K key, V value)	Place a new object in the cache, associated with key name.
void	remove(K name)	Removes a single item by name.
void	resetElementAttributes(K name, IElementAttributes attr)	Reset attributes for a particular element in the cache.

Methods inherited from class org.apache.commons.jcs3.access.AbstractCacheAccess

clear, dispose, freeMemoryElements, getCacheAttributes, getCacheControl, getDefaultElementAttributes, getStatistics, getStats, setCacheAttributes, setDefaultElementAttributes

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.commons.jcs3.access.behavior.ICacheAccessManagement

clear, dispose, freeMemoryElements, getCacheAttributes, getDefaultElementAttributes, getStatistics, getStats, setCacheAttributes, setDefaultElementAttributes

Constructor Details

CacheAccess

public CacheAccess(CompositeCache<K,V> cacheControl)

Constructor for the CacheAccess object.

Parameters:

cacheControl - The cache which the created instance accesses

Method Details

get

public V get(K name)

Retrieve an object from the cache region this instance provides access to.

Specified by:

get in interface ICacheAccess<K,V>

Parameters:

name - Key the object is stored as

Returns:

The object if found or null

get

public V get(K name,
 Supplier<V> supplier)

Retrieve an object from the cache region this instance provides access to. If the object cannot be found in the cache, it will be retrieved by calling the supplier and subsequently storing it in the cache.

Specified by:

get in interface ICacheAccess<K,V>

Parameters:

name -

supplier - supplier to be called if the value is not found

Returns:

Object.

getMatching

public Map<K,V> getMatching(String pattern)

Retrieve matching objects from the cache region this instance provides access to.

Specified by:

getMatching in interface ICacheAccess<K,V>

Parameters:

pattern - - a key pattern for the objects stored

Returns:

A map of key to values. These are stripped from the wrapper.

getCacheElement

public ICacheElement<K,V> getCacheElement(K name)

This method returns the ICacheElement<K, V> wrapper which provides access to element info and other attributes.

This returns a reference to the wrapper. Any modifications will be reflected in the cache. No defensive copy is made.

This method is most useful if you want to determine things such as the how long the element has been in the cache.

The last access time in the ElementAttributes should be current.

Specified by:

getCacheElement in interface ICacheAccess<K,V>

Parameters:

name - Key the Serializable is stored as

Returns:

The ICacheElement<K, V> if the object is found or null

getCacheElements

public Map<K,ICacheElement<K,V>> getCacheElements(Set<K> names)

Get multiple elements from the cache based on a set of cache keys.

This method returns the ICacheElement<K, V> wrapper which provides access to element info and other attributes.

This returns a reference to the wrapper. Any modifications will be reflected in the cache. No defensive copy is made.

This method is most useful if you want to determine things such as the how long the element has been in the cache.

The last access time in the ElementAttributes should be current.

Specified by:

getCacheElements in interface ICacheAccess<K,V>

Parameters:

names - set of Serializable cache keys

Returns:

a map of K key to ICacheElement<K, V> element, or empty map if none of the keys are present

getMatchingCacheElements

public Map<K,ICacheElement<K,V>> getMatchingCacheElements(String pattern)

Get multiple elements from the cache based on a set of cache keys.

This method returns the ICacheElement<K, V> wrapper which provides access to element info and other attributes.

This returns a reference to the wrapper. Any modifications will be reflected in the cache. No defensive copy is made.

This method is most useful if you want to determine things such as the how long the element has been in the cache.

The last access time in the ElementAttributes should be current.

Specified by:

getMatchingCacheElements in interface ICacheAccess<K,V>

Parameters:

pattern - key search pattern

Returns:

a map of K key to ICacheElement<K, V> element, or empty map if no keys match the pattern

putSafe

public void putSafe(K key,
 V value)

Place a new object in the cache, associated with key name. If there is currently an object associated with name in the region an ObjectExistsException is thrown. Names are scoped to a region so they must be unique within the region they are placed.

Specified by:

putSafe in interface ICacheAccess<K,V>

Parameters:

key - Key object will be stored with

value - Object to store

Throws:

CacheException - and ObjectExistsException is thrown if the item is already in the cache.

put

public void put(K name,
 V obj)

Place a new object in the cache, associated with key name. If there is currently an object associated with name in the region it is replaced. Names are scoped to a region so they must be unique within the region they are placed.

Specified by:

put in interface ICacheAccess<K,V>

Parameters:

name - Key object will be stored with

obj - Object to store

put

public void put(K key,
 V val,
 IElementAttributes attr)

Constructs a cache element with these attributes, and puts it into the cache.

If the key or the value is null, and InvalidArgumentException is thrown.

Specified by:

put in interface ICacheAccess<K,V>

See Also:

• ICacheAccess.put(Object, Object, IElementAttributes)

remove

public void remove(K name)

Removes a single item by name.

Specified by:

remove in interface ICacheAccess<K,V>

Parameters:

name - the name of the item to remove.

resetElementAttributes

public void resetElementAttributes(K name,
 IElementAttributes attr)

Reset attributes for a particular element in the cache. NOTE: this method is currently not implemented.

Specified by:

resetElementAttributes in interface ICacheAccess<K,V>

Parameters:

name - Key of object to reset attributes for

attr - New attributes for the object

Throws:

InvalidHandleException - if the item does not exist.

getElementAttributes

public IElementAttributes getElementAttributes(K name)
                                        throws CacheException

GetElementAttributes will return an attribute object describing the current attributes associated with the object name. The name object must override the Object.equals and Object.hashCode methods.

Specified by:

getElementAttributes in interface ICacheAccess<K,V>

Parameters:

name - Key of object to get attributes for

Returns:

Attributes for the object, null if object not in cache

Throws:

CacheException