org.aspectj.org.eclipse.jdt.internal.core
Class OverflowingLRUCache

java.lang.Object
  org.aspectj.org.eclipse.jdt.internal.core.util.LRUCache
      org.aspectj.org.eclipse.jdt.internal.core.OverflowingLRUCache

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

BufferCache, ElementCache

public abstract class OverflowingLRUCache
extends LRUCache

The OverflowingLRUCache is an LRUCache which attempts to maintain a size equal or less than its fSpaceLimit by removing the least recently used elements.

The cache will remove elements which successfully close and all elements which are explicitly removed.

If the cache cannot remove enough old elements to add new elements it will grow beyond fSpaceLimit. Later, it will attempt to shink back to the maximum space limit. The method close should attempt to close the element. If the element is successfully closed it will return true and the element will be removed from the cache. Otherwise the element will remain in the cache.

The cache implicitly attempts shrinks on calls to putand setSpaceLimit. Explicitly calling the shrink method will also cause the cache to attempt to shrink.

The cache calculates the used space of all elements which implement ILRUCacheable. All other elements are assumed to be of size one.

Use the #peek(Object) and #disableTimestamps() method to circumvent the timestamp feature of the cache. This feature is intended to be used only when the #close(LRUCacheEntry) method causes changes to the cache. For example, if a parent closes its children when #close(LRUCacheEntry) is called, it should be careful not to change the LRU linked list. It can be sure it is not causing problems by calling #peek(Object) instead of #get(Object) method.

See Also:

LRUCache

Nested Class Summary

Nested classes/interfaces inherited from class org.aspectj.org.eclipse.jdt.internal.core.util.LRUCache

LRUCache.LRUCacheEntry, LRUCache.Stats

Field Summary

protected double	loadFactor Indicates how much space should be reclaimed when the cache overflows.
protected int	overflow Indicates if the cache has been over filled and by how much.
protected boolean	timestampsOn Indicates whether or not timestamps should be updated

Fields inherited from class org.aspectj.org.eclipse.jdt.internal.core.util.LRUCache

currentSpace, DEFAULT_SPACELIMIT, entryQueue, entryQueueTail, entryTable, spaceLimit, timestampCounter

Constructor Summary

OverflowingLRUCache(int size)
Creates a OverflowingLRUCache.

OverflowingLRUCache(int size, int overflow)
Creates a OverflowingLRUCache.

Method Summary

java.lang.Object	clone() Returns a new cache containing the same contents.
protected abstract boolean	close(LRUCache.LRUCacheEntry entry) Returns true if the element is successfully closed and removed from the cache, otherwise false.
java.util.Enumeration	elements() Returns an enumerator of the values in the cache with the most recently used first.
double	fillingRatio()
java.util.Hashtable	getEntryTable() For internal testing only.
double	getLoadFactor() Returns the load factor for the cache.
int	getOverflow()
protected boolean	makeSpace(int space) Ensures there is the specified amount of free space in the receiver, by removing old entries if necessary.
protected abstract LRUCache	newInstance(int size, int newOverflow) Returns a new instance of the reciever.
void	printStats() For testing purposes only
protected void	privateRemoveEntry(LRUCache.LRUCacheEntry entry, boolean shuffle) Removes the entry from the entry queue.
protected void	privateRemoveEntry(LRUCache.LRUCacheEntry entry, boolean shuffle, boolean external) Removes the entry from the entry queue.
java.lang.Object	put(java.lang.Object key, java.lang.Object value) Sets the value in the cache at the given key.
java.lang.Object	remove(java.lang.Object key) Removes and returns the value in the cache for the given key.
void	setLoadFactor(double newLoadFactor) Sets the load factor for the cache.
void	setSpaceLimit(int limit) Sets the maximum amount of space that the cache can store
boolean	shrink() Attempts to shrink the cache if it has overflown.
java.lang.String	toString() Returns a String that represents the value of this object.
protected void	updateTimestamp(LRUCache.LRUCacheEntry entry) Updates the timestamp for the given entry, ensuring that the queue is kept in correct order.

Methods inherited from class org.aspectj.org.eclipse.jdt.internal.core.util.LRUCache

flush, flush, get, getCurrentSpace, getKey, getNewestTimestampCounter, getOldestElement, getOldestTimestampCounter, getSpaceLimit, keys, keysAndValues, newInstance, peek, privateAdd, privateAddEntry, removeKey, spaceFor, toStringContents, toStringFillingRation

Methods inherited from class java.lang.Object

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

Field Detail

overflow

protected int overflow

Indicates if the cache has been over filled and by how much.

timestampsOn

protected boolean timestampsOn

Indicates whether or not timestamps should be updated

loadFactor

protected double loadFactor

Indicates how much space should be reclaimed when the cache overflows. Inital load factor of one third.

Constructor Detail

OverflowingLRUCache

public OverflowingLRUCache(int size)

Creates a OverflowingLRUCache.

Parameters:

size - Size limit of cache.

OverflowingLRUCache

public OverflowingLRUCache(int size,
                           int overflow)

Creates a OverflowingLRUCache.

Parameters:

size - Size limit of cache.

overflow - Size of the overflow.

Method Detail

clone

public java.lang.Object clone()

Returns a new cache containing the same contents.

Overrides:

clone in class LRUCache

Returns:

New copy of this object.

close

protected abstract boolean close(LRUCache.LRUCacheEntry entry)

Returns true if the element is successfully closed and removed from the cache, otherwise false.

NOTE: this triggers an external remove from the cache by closing the obejct.

elements

public java.util.Enumeration elements()

Returns an enumerator of the values in the cache with the most recently used first.

fillingRatio

public double fillingRatio()

Overrides:

fillingRatio in class LRUCache

getEntryTable

public java.util.Hashtable getEntryTable()

For internal testing only. This method exposed only for testing purposes!

Returns:

Hashtable of entries

getLoadFactor

public double getLoadFactor()

Returns the load factor for the cache. The load factor determines how much space is reclaimed when the cache exceeds its space limit.

Returns:

double

getOverflow

public int getOverflow()

Returns:

The space by which the cache has overflown.

makeSpace

protected boolean makeSpace(int space)

Ensures there is the specified amount of free space in the receiver, by removing old entries if necessary. Returns true if the requested space was made available, false otherwise. May not be able to free enough space since some elements cannot be removed until they are saved.

Overrides:

makeSpace in class LRUCache

Parameters:

space - Amount of space to free up

newInstance

protected abstract LRUCache newInstance(int size,
                                        int newOverflow)

Returns a new instance of the reciever.

printStats

public void printStats()

For testing purposes only

privateRemoveEntry

protected void privateRemoveEntry(LRUCache.LRUCacheEntry entry,
                                  boolean shuffle)

Removes the entry from the entry queue. Calls privateRemoveEntry with the external functionality enabled.

Overrides:

privateRemoveEntry in class LRUCache

Parameters:

shuffle - indicates whether we are just shuffling the queue (in which case, the entry table is not modified).

privateRemoveEntry

protected void privateRemoveEntry(LRUCache.LRUCacheEntry entry,
                                  boolean shuffle,
                                  boolean external)

Removes the entry from the entry queue. If external is true, the entry is removed without checking if it can be removed. It is assumed that the client has already closed the element it is trying to remove (or will close it promptly). If external is false, and the entry could not be closed, it is not removed and the pointers are not changed.

Parameters:

shuffle - indicates whether we are just shuffling the queue (in which case, the entry table is not modified).

put

public java.lang.Object put(java.lang.Object key,
                            java.lang.Object value)

Sets the value in the cache at the given key. Returns the value.

Overrides:

put in class LRUCache

Parameters:

key - Key of object to add.

value - Value of object to add.

Returns:

added value.

remove

public java.lang.Object remove(java.lang.Object key)

Removes and returns the value in the cache for the given key. If the key is not in the cache, returns null.

Parameters:

key - Key of object to remove from cache.

Returns:

Value removed from cache.

setLoadFactor

public void setLoadFactor(double newLoadFactor)
                   throws java.lang.IllegalArgumentException

Sets the load factor for the cache. The load factor determines how much space is reclaimed when the cache exceeds its space limit.

Parameters:

newLoadFactor - double

Throws:

java.lang.IllegalArgumentException - when the new load factor is not in (0.0, 1.0]

setSpaceLimit

public void setSpaceLimit(int limit)

Sets the maximum amount of space that the cache can store

Overrides:

setSpaceLimit in class LRUCache

Parameters:

limit - Number of units of cache space

shrink

public boolean shrink()

Attempts to shrink the cache if it has overflown. Returns true if the cache shrinks to less than or equal to fSpaceLimit.

toString

public java.lang.String toString()

Returns a String that represents the value of this object. This method is for debugging purposes only.

Overrides:

toString in class LRUCache

updateTimestamp

protected void updateTimestamp(LRUCache.LRUCacheEntry entry)

Updates the timestamp for the given entry, ensuring that the queue is kept in correct order. The entry must exist.

This method will do nothing if timestamps have been disabled.

Overrides:

updateTimestamp in class LRUCache