org.apache.jcs.auxiliary.disk.indexed
Class IndexedDiskCache<K extends Serializable,V extends Serializable>

java.lang.Object
  org.apache.jcs.auxiliary.AbstractAuxiliaryCache<K,V>
      org.apache.jcs.auxiliary.AbstractAuxiliaryCacheEventLogging<K,V>
          org.apache.jcs.auxiliary.disk.AbstractDiskCache<K,V>
              org.apache.jcs.auxiliary.disk.indexed.IndexedDiskCache<K,V>

All Implemented Interfaces:

AuxiliaryCache<K,V>, ICache<K,V>, ICacheType

public class IndexedDiskCache<K extends Serializable,V extends Serializable>
extends AbstractDiskCache<K,V>

Disk cache that uses a RandomAccessFile with keys stored in memory. The maximum number of keys stored in memory is configurable. The disk cache tries to recycle spots on disk to limit file expansion.

log

protected static final org.apache.commons.logging.Log log

The logger

logCacheName

protected final String logCacheName

Cache name used in log messages

currentOptimizationThread

protected volatile Thread currentOptimizationThread

The thread optimizing the file.

storageLock

protected ReentrantReadWriteLock storageLock

Use this lock to synchronize reads and writes to the underlying storage mechanism.

IndexedDiskCache

public IndexedDiskCache(IndexedDiskCacheAttributes cacheAttributes)

Constructor for the DiskCache object.

Parameters:

cacheAttributes -

IndexedDiskCache

public IndexedDiskCache(IndexedDiskCacheAttributes cattr,
                        IElementSerializer elementSerializer)

Constructor for the DiskCache object.

Parameters:

cattr -

elementSerializer - used if supplied, the super's super will not set a null

loadKeys

protected void loadKeys()
                 throws InterruptedException

Loads the keys from the .key file. The keys are stored in a HashMap on disk. This is converted into a LRUMap.

Throws:

InterruptedException

checkForDedOverlaps

protected boolean checkForDedOverlaps(IndexedDiskElementDescriptor[] sortedDescriptors)

Detects any overlapping elements. This expects a sorted list.

The total length of an item is IndexedDisk.RECORD_HEADER + ded.len.

Parameters:

sortedDescriptors -

Returns:

false if there are overlaps.

saveKeys

protected void saveKeys()

Saves key file to disk. This converts the LRUMap to a HashMap for deserialization.

processUpdate

protected void processUpdate(ICacheElement<K,V> ce)

Update the disk cache. Called from the Queue. Makes sure the Item has not been retrieved from purgatory while in queue for disk. Remove items from purgatory when they go to disk.

Specified by:

processUpdate in class AbstractAuxiliaryCacheEventLogging<K extends Serializable,V extends Serializable>

Parameters:

ce - The ICacheElement to put to disk.

processGet

protected ICacheElement<K,V> processGet(K key)

Gets the key, then goes to disk to get the object.

Specified by:

processGet in class AbstractAuxiliaryCacheEventLogging<K extends Serializable,V extends Serializable>

Parameters:

key -

Returns:

ICacheElement or null

See Also:

AbstractDiskCache.doGet(K)

processGetMatching

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

Gets matching items from the cache.

Specified by:

processGetMatching in class AbstractAuxiliaryCacheEventLogging<K extends Serializable,V extends Serializable>

Parameters:

pattern -

Returns:

a map of K key to ICacheElement element, or an empty map if there is no data in cache matching keys

getGroupKeys

public Set<K> getGroupKeys(String groupName)

Gets the group keys from the disk.

Specified by:

getGroupKeys in interface AuxiliaryCache<K extends Serializable,V extends Serializable>

Specified by:

getGroupKeys in class AbstractDiskCache<K extends Serializable,V extends Serializable>

Returns:

a set of group keys

See Also:

AuxiliaryCache.getGroupKeys(java.lang.String)

getGroupNames

public Set<String> getGroupNames()

Gets the group names from the disk.

Specified by:

getGroupNames in interface AuxiliaryCache<K extends Serializable,V extends Serializable>

Specified by:

getGroupNames in class AbstractDiskCache<K extends Serializable,V extends Serializable>

Returns:

a set of group names

See Also:

AuxiliaryCache.getGroupKeys(java.lang.String)

processRemove

protected boolean processRemove(K key)

Returns true if the removal was successful; or false if there is nothing to remove. Current implementation always result in a disk orphan.

Specified by:

processRemove in class AbstractAuxiliaryCacheEventLogging<K extends Serializable,V extends Serializable>

Parameters:

key -

Returns:

true if at least one item was removed.

processRemoveAll

public void processRemoveAll()

Remove all the items from the disk cache by reseting everything.

Specified by:

processRemoveAll in class AbstractAuxiliaryCacheEventLogging<K extends Serializable,V extends Serializable>

processDispose

public void processDispose()

Dispose of the disk cache in a background thread. Joins against this thread to put a cap on the disposal time.

TODO make dispose window configurable.

Specified by:

processDispose in class AbstractAuxiliaryCacheEventLogging<K extends Serializable,V extends Serializable>

disposeInternal

protected void disposeInternal()

Internal method that handles the disposal.

addToRecycleBin

protected void addToRecycleBin(IndexedDiskElementDescriptor ded)

Add descriptor to recycle bin if it is not null. Adds the length of the item to the bytes free.

This is called in three places: (1) When an item is removed. All item removals funnel down to the removeSingleItem method. (2) When an item on disk is updated with a value that will not fit in the previous slot. (3) When the max key size is reached, the freed slot will be added.

The recylebin is not a set. If a slot it added twice, it will result in the wrong data being returned.

Parameters:

ded -

doOptimizeRealTime

protected void doOptimizeRealTime()

Performs the check for optimization, and if it is required, do it.

optimizeFile

protected void optimizeFile()

File optimization is handled by this method. It works as follows:

1. Shutdown recycling and turn on queuing of puts.
2. Take a snapshot of the current descriptors. If there are any removes, ignore them, as they will be compacted during the next optimization.
3. Optimize the snapshot. For each descriptor:
   1. Obtain the write-lock.
   2. Shift the element on the disk, in order to compact out the free space.
   3. Release the write-lock. This allows elements to still be accessible during optimization.
4. Obtain the write-lock.
5. All queued puts are made at the end of the file. Optimize these under a single write-lock.
6. Truncate the file.
7. Release the write-lock.
8. Restore system to standard operation.

getSize

public int getSize()

Returns the current cache size.

Specified by:

getSize in interface ICache<K extends Serializable,V extends Serializable>

Specified by:

getSize in class AbstractDiskCache<K extends Serializable,V extends Serializable>

Returns:

The size value

See Also:

ICache.getSize()

getRecyleBinSize

protected int getRecyleBinSize()

Returns the size of the recyclebin in number of elements.

Returns:

The number of items in the bin.

getRecyleCount

protected int getRecyleCount()

Returns the number of times we have used spots from the recycle bin.

Returns:

The number of spots used.

getBytesFree

protected long getBytesFree()

Returns the number of bytes that are free. When an item is removed, its length is recorded. When a spot is used form the recycle bin, the length of the item stored is recorded.

Returns:

The number bytes free on the disk file.

getDataFileSize

protected long getDataFileSize()
                        throws IOException

This is for debugging and testing.

Returns:

the length of the data file.

Throws:

IOException

dump

public void dump()

For debugging. This dumps the values by default.

dump

public void dump(boolean dumpValues)

For debugging.

Parameters:

dumpValues - A boolean indicating if values should be dumped.

getAuxiliaryCacheAttributes

public AuxiliaryCacheAttributes getAuxiliaryCacheAttributes()

Description copied from interface: AuxiliaryCache

This returns the generic attributes for an auxiliary cache. Most implementations will cast this to a more specific type.

Returns:

Returns the AuxiliaryCacheAttributes.

getStats

public String getStats()

Gets basic stats for the disk cache.

Specified by:

getStats in interface ICache<K extends Serializable,V extends Serializable>

Overrides:

getStats in class AbstractDiskCache<K extends Serializable,V extends Serializable>

Returns:

String

getStatistics

public IStats getStatistics()

Returns info about the disk cache.

(non-Javadoc)

Specified by:

getStatistics in interface AuxiliaryCache<K extends Serializable,V extends Serializable>

Overrides:

getStatistics in class AbstractDiskCache<K extends Serializable,V extends Serializable>

Returns:

the historical and statistical data for a region's auxiliary cache.

See Also:

AuxiliaryCache.getStatistics()

getTimesOptimized

protected int getTimesOptimized()

This is exposed for testing.

Returns:

Returns the timesOptimized.

getDiskLocation

protected String getDiskLocation()

This is used by the event logging.

Specified by:

getDiskLocation in class AbstractDiskCache<K extends Serializable,V extends Serializable>

Returns:

the location of the disk, either path or ip.