PartitionedCacheAccess (Apache Commons JCS

java.lang.Object
- org.apache.commons.jcs.utils.props.AbstractPropertyContainer
- - org.apache.commons.jcs.access.PartitionedCacheAccess<K,V>

All Implemented Interfaces:

ICacheAccess<K,V>, ICacheAccessManagement
```
public class PartitionedCacheAccess<K,V>
extends AbstractPropertyContainer
implements ICacheAccess<K,V>
```
TODO: Add new methods that will allow you to provide a partition indicator for all major calls. Add an interface as well.
This handles dividing puts and gets.
There are two required properties.
1. .numberOfPartitions
2. .partitionRegionNamePrefix
System properties will override values in the properties file.
We use a JCS region name for each partition that looks like this: partitionRegionNamePrefix + "_" + partitionNumber. The number is 0 indexed based.
Author:

Aaron Smuts

Constructor Summary

Constructors
Constructor and Description

PartitionedCacheAccess()
Sets default properties heading and group.

Constructors
Constructor and Description
`PartitionedCacheAccess()` Sets default properties heading and group.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`clear()` Removes all of the elements from a region.
`void`	`dispose()` Dispose this region.
`protected boolean`	`ensureInit()` Initialize if we haven't already.
`int`	`freeMemoryElements(int numberToFree)` Calls free on each partition.
`V`	`get(K key)` Gets the object for the key from the desired partition.
`ICompositeCacheAttributes`	`getCacheAttributes()` Gets the ICompositeCacheAttributes of the cache region
`ICacheElement<K,V>`	`getCacheElement(K key)` Gets the ICacheElement<K, V> (the wrapped object) for the key from the desired partition.
`Map<K,ICacheElement<K,V>>`	`getCacheElements(Set<K> names)` This is a getMultiple.
`IElementAttributes`	`getDefaultElementAttributes()` GetElementAttributes will return an attribute object describing the current attributes associated with the object name.
`IElementAttributes`	`getElementAttributes(K key)` This is no more efficient than simply getting the cache element.
`Map<K,V>`	`getMatching(String pattern)` This is tricky.
`Map<K,ICacheElement<K,V>>`	`getMatchingCacheElements(String pattern)` This is tricky.
`protected int`	`getNumberOfPartitions()`
`long`	`getNumericValueForKey(K key)` This can be overridden for special purposes.
`protected int`	`getPartitionNumberForKey(K key)` This expects a numeric key.
`protected String`	`getPartitionRegionNamePrefix()`
`protected ICacheAccess<K,V>[]`	`getPartitions()`
`protected String`	`getPropertyForName(String propertyName, boolean required)` Checks the system properties before the properties.
`ICacheStats`	`getStatistics()` This returns the ICacheStats object with information on this region and its auxiliaries.
`String`	`getStats()`
`protected void`	`handleProperties()` Loads in the needed configuration settings.
`protected void`	`initialize()` Use the partition prefix and the number of partitions to get JCS regions.
`void`	`put(K key, V object)` Puts the value into the appropriate cache partition.
`void`	`put(K key, V object, IElementAttributes attr)` Puts the value into the appropriate cache partition.
`void`	`putSafe(K key, V object)` Puts in cache if an item does not exist with the name in that region.
`void`	`remove(K key)` Removes the item from the appropriate partition.
`void`	`resetElementAttributes(K key, IElementAttributes attributes)` Resets the attributes for this item.
`void`	`setCacheAttributes(ICompositeCacheAttributes cattr)` Sets the attributes on all the partitions.
`void`	`setDefaultElementAttributes(IElementAttributes attr)` This method is does not reset the attributes for items already in the cache.
`protected void`	`setNumberOfPartitions(int numberOfPartitions)`
`protected void`	`setPartitionRegionNamePrefix(String partitionRegionNamePrefix)`
`protected void`	`setPartitions(ICacheAccess<K,V>[] partitions)`

Methods inherited from class org.apache.commons.jcs.utils.props.AbstractPropertyContainer
ensureProperties, getProperties, getPropertiesFactory, getPropertiesGroup, getPropertiesHeading, initializeProperties, setProperties, setPropertiesFactory, setPropertiesGroup, setPropertiesHeading

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - PartitionedCacheAccess
```
public PartitionedCacheAccess()
```
    Sets default properties heading and group.
- Method Detail
  - put
```
public void put(K key,
                V object)
         throws CacheException
```
    Puts the value into the appropriate cache partition.
    
    Specified by:
    
    put in interface ICacheAccess<K,V>
    
    Parameters:
    
    key - key
    
    object - object
    
    Throws:
    
    CacheException - on configuration problem
  - putSafe
```
public void putSafe(K key,
                    V object)
             throws CacheException
```
    Puts in cache if an item does not exist with the name in that region.
    
    Specified by:
    
    putSafe in interface ICacheAccess<K,V>
    
    Parameters:
    
    key -
    
    object -
    
    Throws:
    
    CacheException
  - put
```
public void put(K key,
                V object,
                IElementAttributes attr)
         throws CacheException
```
    Puts the value into the appropriate cache partition.
    
    Specified by:
    
    put in interface ICacheAccess<K,V>
    
    Parameters:
    
    key - key
    
    object - object
    
    attr -
    
    Throws:
    
    CacheException - on configuration problem
  - get
```
public V get(K key)
```
    Gets the object for the key from the desired partition.
    
    Specified by:
    
    get in interface ICacheAccess<K,V>
    
    Parameters:
    
    key - key
    
    Returns:
    
    result, null if not found.
  - getCacheElement
```
public ICacheElement<K,V> getCacheElement(K key)
```
    Gets the ICacheElement<K, V> (the wrapped object) for the key from the desired partition.
    
    Specified by:
    
    getCacheElement in interface ICacheAccess<K,V>
    
    Parameters:
    
    key - key
    
    Returns:
    
    result, null if not found.
  - getCacheElements
```
public Map<K,ICacheElement<K,V>> getCacheElements(Set<K> names)
```
    This is a getMultiple. We try to group the keys so that we make as few calls as needed.
    
    Specified by:
    
    getCacheElements in interface ICacheAccess<K,V>
    
    Parameters:
    
    names -
    
    Returns:
    
    Map of keys to ICacheElement
  - getMatching
```
public Map<K,V> getMatching(String pattern)
```
    This is tricky. Do we need to get from all the partitions?
    If this interface took an object, we could use the hashcode to determine the partition. Then we could use the toString for the pattern.
    
    Specified by:
    
    getMatching in interface ICacheAccess<K,V>
    
    Parameters:
    
    pattern -
    
    Returns:
    
    HashMap key to value
  - getMatchingCacheElements
```
public Map<K,ICacheElement<K,V>> getMatchingCacheElements(String pattern)
```
    This is tricky. Do we need to get from all the partitions?
    
    Specified by:
    
    getMatchingCacheElements in interface ICacheAccess<K,V>
    
    Parameters:
    
    pattern -
    
    Returns:
    
    HashMap key to ICacheElement
  - remove
```
public void remove(K key)
            throws CacheException
```
    Removes the item from the appropriate partition.
    
    Specified by:
    
    remove in interface ICacheAccess<K,V>
    
    Parameters:
    
    key -
    
    Throws:
    
    CacheException
  - freeMemoryElements
```
public int freeMemoryElements(int numberToFree)
                       throws CacheException
```
    Calls free on each partition.
    
    Specified by:
    
    freeMemoryElements in interface ICacheAccessManagement
    
    Parameters:
    
    numberToFree -
    
    Returns:
    
    number removed
    
    Throws:
    
    CacheException
  - getCacheAttributes
```
public ICompositeCacheAttributes getCacheAttributes()
```
    Description copied from interface: ICacheAccessManagement
    
    Gets the ICompositeCacheAttributes of the cache region
    
    Specified by:
    
    getCacheAttributes in interface ICacheAccessManagement
    
    Returns:
    
    ICompositeCacheAttributes from the first partition.
  - getDefaultElementAttributes
```
public IElementAttributes getDefaultElementAttributes()
                                               throws CacheException
```
    Description copied from interface: ICacheAccessManagement
    
    GetElementAttributes will return an attribute object describing the current attributes associated with the object name. If no name parameter is available, the attributes for the region will be returned. The name object must override the Object.equals and Object.hashCode methods.
    
    Specified by:
    
    getDefaultElementAttributes in interface ICacheAccessManagement
    
    Returns:
    
    IElementAttributes from the first partition.
    
    Throws:
    
    CacheException
  - getElementAttributes
```
public IElementAttributes getElementAttributes(K key)
                                        throws CacheException
```
    This is no more efficient than simply getting the cache element.
    
    Specified by:
    
    getElementAttributes in interface ICacheAccess<K,V>
    
    Parameters:
    
    key -
    
    Returns:
    
    IElementAttributes
    
    Throws:
    
    CacheException
  - resetElementAttributes
```
public void resetElementAttributes(K key,
                                   IElementAttributes attributes)
                            throws CacheException
```
    Resets the attributes for this item. This has the same effect as an update, in most cases. None of the auxiliaries are optimized to do this more efficiently than a simply update.
    
    Specified by:
    
    resetElementAttributes in interface ICacheAccess<K,V>
    
    Parameters:
    
    key -
    
    attributes -
    
    Throws:
    
    CacheException
  - setCacheAttributes
```
public void setCacheAttributes(ICompositeCacheAttributes cattr)
```
    Sets the attributes on all the partitions.
    
    Specified by:
    
    setCacheAttributes in interface ICacheAccessManagement
    
    Parameters:
    
    cattr -
  - clear
```
public void clear()
           throws CacheException
```
    Removes all of the elements from a region.
    
    Specified by:
    
    clear in interface ICacheAccessManagement
    
    Throws:
    
    CacheException
  - setDefaultElementAttributes
```
public void setDefaultElementAttributes(IElementAttributes attr)
                                 throws CacheException
```
    This method is does not reset the attributes for items already in the cache. It could potentially do this for items in memory, and maybe on disk (which would be slow) but not remote items. Rather than have unpredictable behavior, this method just sets the default attributes. Items subsequently put into the cache will use these defaults if they do not specify specific attributes.
    
    Specified by:
    
    setDefaultElementAttributes in interface ICacheAccessManagement
    
    Parameters:
    
    attr - the default attributes.
    
    Throws:
    
    CacheException - if something goes wrong.
  - getStatistics
```
public ICacheStats getStatistics()
```
    This returns the ICacheStats object with information on this region and its auxiliaries.
    This data can be formatted as needed.
    
    Specified by:
    
    getStatistics in interface ICacheAccessManagement
    
    Returns:
    
    ICacheStats
  - getStats
```
public String getStats()
```
    Specified by:
    
    getStats in interface ICacheAccessManagement
    
    Returns:
    
    A String version of the stats.
  - dispose
```
public void dispose()
```
    Dispose this region. Flushes objects to and closes auxiliary caches. This is a shutdown command!
    To simply remove all elements from the region use clear().
    
    Specified by:
    
    dispose in interface ICacheAccessManagement
  - getPartitionNumberForKey
```
protected int getPartitionNumberForKey(K key)
```
    This expects a numeric key. If the key cannot be converted into a number, we will return 0. TODO we could md5 it or get the hashcode.
    We determine the partition by taking the mod of the number of partitions.
    
    Parameters:
    
    key - key
    
    Returns:
    
    the partition number.
  - getNumericValueForKey
```
public long getNumericValueForKey(K key)
```
    This can be overridden for special purposes.
    
    Parameters:
    
    key - key
    
    Returns:
    
    long
  - ensureInit
```
protected boolean ensureInit()
```
    Initialize if we haven't already.
    
    Throws:
    
    ConfigurationException - on configuration problem
  - initialize
```
protected void initialize()
                   throws ConfigurationException
```
    Use the partition prefix and the number of partitions to get JCS regions.
    
    Throws:
    
    ConfigurationException - on configuration problem
  - handleProperties
```
protected void handleProperties()
                         throws ConfigurationException
```
    Loads in the needed configuration settings. System properties are checked first. A system property will override local property value.
    Loads the following JCS Cache specific properties:
    - heading.numberOfPartitions
    - heading.partitionRegionNamePrefix
    Specified by:
    
    handleProperties in class AbstractPropertyContainer
    
    Throws:
    
    ConfigurationException - on configuration problem
  - getPropertyForName
```
protected String getPropertyForName(String propertyName,
                                    boolean required)
                             throws ConfigurationException
```
    Checks the system properties before the properties.
    
    Parameters:
    
    propertyName - name
    
    required - is it required?
    
    Returns:
    
    the property value if one is found
    
    Throws:
    
    ConfigurationException - thrown if it is required and not found.
  - setNumberOfPartitions
```
protected void setNumberOfPartitions(int numberOfPartitions)
```
    Parameters:
    
    numberOfPartitions - The numberOfPartitions to set.
  - getNumberOfPartitions
```
protected int getNumberOfPartitions()
```
    Returns:
    
    Returns the numberOfPartitions.
  - setPartitionRegionNamePrefix
```
protected void setPartitionRegionNamePrefix(String partitionRegionNamePrefix)
```
    Parameters:
    
    partitionRegionNamePrefix - The partitionRegionNamePrefix to set.
  - getPartitionRegionNamePrefix
```
protected String getPartitionRegionNamePrefix()
```
    Returns:
    
    Returns the partitionRegionNamePrefix.
  - setPartitions
```
protected void setPartitions(ICacheAccess<K,V>[] partitions)
```
    Parameters:
    
    partitions - The partitions to set.
  - getPartitions
```
protected ICacheAccess<K,V>[] getPartitions()
```
    Returns:
    
    Returns the partitions.

Class PartitionedCacheAccess<K,V>

Constructor Summary

Method Summary

Methods inherited from class org.apache.commons.jcs.utils.props.AbstractPropertyContainer

Methods inherited from class java.lang.Object

Constructor Detail

PartitionedCacheAccess

Method Detail

put

putSafe

put

get

getCacheElement

getCacheElements

getMatching

getMatchingCacheElements

remove

freeMemoryElements

getCacheAttributes

getDefaultElementAttributes

getElementAttributes

resetElementAttributes

setCacheAttributes

clear

setDefaultElementAttributes

getStatistics

getStats

dispose

getPartitionNumberForKey

getNumericValueForKey

ensureInit

initialize

handleProperties

getPropertyForName

setNumberOfPartitions

getNumberOfPartitions

setPartitionRegionNamePrefix

getPartitionRegionNamePrefix

setPartitions

getPartitions