| java.lang.Object
 java.util.AbstractMap
com.opensymphony.oscache.base.algorithm.AbstractConcurrentReadCache
All known Subclasses: com.opensymphony.oscache.base.algorithm.UnlimitedCache, com.opensymphony.oscache.base.algorithm.LRUCache, com.opensymphony.oscache.base.algorithm.FIFOCache,
| AbstractConcurrentReadCache | | abstract public class AbstractConcurrentReadCache extends AbstractMap implements Map,Cloneable,Serializable(Code) | | A version of Hashtable that supports mostly-concurrent reading, but exclusive writing.
Because reads are not limited to periods
without writes, a concurrent reader policy is weaker than a classic
reader/writer policy, but is generally faster and allows more
concurrency. This class is a good choice especially for tables that
are mainly created by one thread during the start-up phase of a
program, and from then on, are mainly read (with perhaps occasional
additions or removals) in many threads. If you also need concurrency
among writes, consider instead using ConcurrentHashMap.
Successful retrievals using get(key) and containsKey(key) usually
run without locking. Unsuccessful ones (i.e., when the key is not
present) do involve brief synchronization (locking). Also, the
size and isEmpty methods are always synchronized.
Because retrieval operations can ordinarily overlap with
writing operations (i.e., put, remove, and their derivatives),
retrievals can only be guaranteed to return the results of the most
recently completed operations holding upon their
onset. Retrieval operations may or may not return results
reflecting in-progress writing operations. However, the retrieval
operations do always return consistent results -- either those
holding before any single modification or after it, but never a
nonsense result. For aggregate operations such as putAll and
clear, concurrent reads may reflect insertion or removal of only
some entries. In those rare contexts in which you use a hash table
to synchronize operations across threads (for example, to prevent
reads until after clears), you should either encase operations
in synchronized blocks, or instead use java.util.Hashtable.
This class also supports optional guaranteed
exclusive reads, simply by surrounding a call within a synchronized
block, as in
AbstractConcurrentReadCache t; ... Object v;
synchronized(t) { v = t.get(k); }
But this is not usually necessary in practice. For
example, it is generally inefficient to write:
AbstractConcurrentReadCache t; ... // Inefficient version
Object key; ...
Object value; ...
synchronized(t) {
if (!t.containsKey(key))
t.put(key, value);
// other code if not previously present
}
else {
// other code if it was previously present
}
}
Instead, just take advantage of the fact that put returns
null if the key was not previously present:
AbstractConcurrentReadCache t; ... // Use this instead
Object key; ...
Object value; ...
Object oldValue = t.put(key, value);
if (oldValue == null) {
// other code if not previously present
}
else {
// other code if it was previously present
}
Iterators and Enumerations (i.e., those returned by
keySet().iterator(), entrySet().iterator(), values().iterator(),
keys(), and elements()) return elements reflecting the state of the
hash table at some point at or since the creation of the
iterator/enumeration. They will return at most one instance of
each element (via next()/nextElement()), but might or might not
reflect puts and removes that have been processed since they were
created. They do not throw ConcurrentModificationException.
However, these iterators are designed to be used by only one
thread at a time. Sharing an iterator across multiple threads may
lead to unpredictable results if the table is being concurrently
modified. Again, you can ensure interference-free iteration by
enclosing the iteration in a synchronized block.
This class may be used as a direct replacement for any use of
java.util.Hashtable that does not depend on readers being blocked
during updates. Like Hashtable but unlike java.util.HashMap,
this class does NOT allow null to be used as a key or
value. This class is also typically faster than ConcurrentHashMap
when there is usually only one thread updating the table, but
possibly many retrieving values from it.
Implementation note: A slightly faster implementation of
this class will be possible once planned Java Memory Model
revisions are in place.
[ Introduction to this package. ]
|
| Inner Class :protected static class Entry implements Map.Entry | |
| Inner Class :protected class KeyIterator extends HashIterator | |
| Inner Class :protected class ValueIterator extends HashIterator | |
| Method Summary | |
| public synchronized int | capacity()
Return the number of slots in this table. | | public synchronized void | clear()
Removes all mappings from this map. | | public synchronized Object | clone()
Returns a shallow copy of this. | | public boolean | contains(Object value)
Tests if some key maps into the specified value in this table.
This operation is more expensive than the containsKey
method.
Note that this method is identical in functionality to containsValue,
(which is part of the Map interface in the collections framework).
Parameters:
value - a value to search for. | | public boolean | containsKey(Object key)
Tests if the specified object is a key in this table.
Parameters:
key - possible key. | | public boolean | containsValue(Object value)
Returns true if this map maps one or more keys to the
specified value. | | public Enumeration | elements()
Returns an enumeration of the values in this table. | | public Set | entrySet()
Returns a collection view of the mappings contained in this map.
Each element in the returned collection is a Map.Entry. | | protected synchronized boolean | findAndRemoveEntry(Map.Entry entry)
Helper method for entrySet remove. | | public Object | get(Object key)
Returns the value to which the specified key is mapped in this table.
Parameters:
key - a key in the table. | | public Set | getGroup(String groupName)
Returns a set of the cache keys that reside in a particular group.
Parameters:
groupName - The name of the group to retrieve. | | final protected synchronized Set | getGroupForReading(String groupName)
Get ref to group.
CACHE-127 Synchronized copying of the group entry set since
the new HashSet(Collection c) constructor uses the iterator.
This may slow things down but it is better than a
ConcurrentModificationException. | | final protected Map | getGroupsForReading()
Get ref to groups. | | public int | getMaxEntries()
Retrieve the cache capacity (number of entries). | | public PersistenceListener | getPersistenceListener()
Get the persistence listener. | | final protected Entry[] | getTableForReading()
| | public synchronized boolean | isEmpty()
Returns true if this map contains no key-value mappings. | | public boolean | isMemoryCaching()
Check if memory caching is used. | | public boolean | isOverflowPersistence()
| | public boolean | isUnlimitedDiskCache()
Check if we use unlimited disk cache. | | abstract protected void | itemPut(Object key)
Notify the underlying implementation that an item was put in the cache. | | abstract protected void | itemRemoved(Object key)
Notify the underlying implementation that an item was removed from the cache. | | abstract protected void | itemRetrieved(Object key)
Notify any underlying algorithm that an item has been retrieved from the cache. | | public Set | keySet()
Returns a set view of the keys contained in this map.
The set is backed by the map, so changes to the map are reflected in the set, and
vice-versa. | | public Enumeration | keys()
Returns an enumeration of the keys in this table. | | public float | loadFactor()
| | protected void | persistClear()
Removes the entire cache from persistent storage. | | protected void | persistRemove(Object key)
Remove an object from the persistence. | | protected void | persistRemoveGroup(String groupName)
Removes a cache group using the persistence listener. | | protected Object | persistRetrieve(Object key)
Retrieve an object from the persistence listener. | | protected Set | persistRetrieveGroup(String groupName)
Retrieves a cache group using the persistence listener. | | protected void | persistStore(Object key, Object obj)
Store an object in the cache using the persistence listener. | | protected void | persistStoreGroup(String groupName, Set group)
Creates or Updates a cache group using the persistence listener. | | public Object | put(Object key, Object value)
| | public synchronized void | putAll(Map t)
Copies all of the mappings from the specified map to this one. | | final protected void | recordModification(Object x)
Force a memory synchronization that will cause
all readers to see table. | | protected void | rehash()
Rehashes the contents of this map into a new table with a larger capacity. | | public Object | remove(Object key)
| | public Object | removeForce(Object key)
Like remove(Object), but ensures that the entry will be removed from the persistent store, too,
even if overflowPersistence or unlimitedDiskcache are true.
Parameters:
key - the key that needs to be removed. | | abstract protected Object | removeItem()
The cache has reached its cacpacity and an item needs to be removed. | | public void | setMaxEntries(int newLimit)
| | public void | setMemoryCaching(boolean memoryCaching)
Sets the memory caching flag. | | public void | setOverflowPersistence(boolean overflowPersistence)
| | public void | setPersistenceListener(PersistenceListener listener)
Set the persistence listener to use. | | public void | setUnlimitedDiskCache(boolean unlimitedDiskCache)
Sets the unlimited disk caching flag. | | public synchronized int | size()
Returns the total number of cache entries held in this map. | | protected Object | sput(Object key, Object value, int hash, boolean persist)
| | protected Object | sremove(Object key, int hash, boolean invokeAlgorithm)
| | public Collection | values()
Returns a collection view of the values contained in this map.
The collection is backed by the map, so changes to the map are reflected in
the collection, and vice-versa. |
| DEFAULT_INITIAL_CAPACITY | | final public static int DEFAULT_INITIAL_CAPACITY(Code) | | The default initial number of table slots for this table (32).
Used when not otherwise specified in constructor.
|
| DEFAULT_LOAD_FACTOR | | final public static float DEFAULT_LOAD_FACTOR(Code) | | The default load factor for this table.
Used when not otherwise specified in constructor, the default is 0.75f.
|
| DEFAULT_MAX_ENTRIES | | final protected int DEFAULT_MAX_ENTRIES(Code) | | Default cache capacity (number of entries).
|
| UNLIMITED | | final protected int UNLIMITED(Code) | | Max number of element in cache when considered unlimited.
|
| barrierLock | | final protected Boolean barrierLock(Code) | | Lock used only for its memory effects. We use a Boolean
because it is serializable, and we create a new one because
we need a unique object for each cache instance.
|
| count | | protected transient int count(Code) | | The total number of mappings in the hash table.
|
| entrySet | | protected transient Set entrySet(Code) | | |
| groups | | protected HashMap groups(Code) | | A HashMap containing the group information.
Each entry uses the group name as the key, and holds a
Set of containing keys of all
the cache entries that belong to that particular group.
|
| lastWrite | | protected transient Object lastWrite(Code) | | field written to only to guarantee lock ordering.
|
| loadFactor | | protected float loadFactor(Code) | | The load factor for the hash table.
|
| maxEntries | | protected int maxEntries(Code) | | Cache capacity (number of entries).
|
| memoryCaching | | protected boolean memoryCaching(Code) | | Use memory cache or not.
|
| table | | protected transient Entry[] table(Code) | | The hash table data.
|
| threshold | | protected int threshold(Code) | | The table is rehashed when its size exceeds this threshold.
(The value of this field is always (int)(capacity * loadFactor).)
|
| unlimitedDiskCache | | protected boolean unlimitedDiskCache(Code) | | Use unlimited disk caching.
|
| AbstractConcurrentReadCache | | public AbstractConcurrentReadCache(int initialCapacity, float loadFactor)(Code) | | Constructs a new, empty map with the specified initial capacity and the specified load factor.
Parameters:
initialCapacity - the initial capacityThe actual initial capacity is rounded to the nearest power of two.
Parameters:
loadFactor - the load factor of the AbstractConcurrentReadCache
throws:
IllegalArgumentException - if the initial maximum numberof elements is lessthan zero, or if the load factor is nonpositive. |
| AbstractConcurrentReadCache | | public AbstractConcurrentReadCache(int initialCapacity)(Code) | | Constructs a new, empty map with the specified initial capacity and default load factor.
Parameters:
initialCapacity - the initial capacity of theAbstractConcurrentReadCache.
throws:
IllegalArgumentException - if the initial maximum numberof elements is lessthan zero. |
| AbstractConcurrentReadCache | | public AbstractConcurrentReadCache()(Code) | | Constructs a new, empty map with a default initial capacity and load factor.
|
| AbstractConcurrentReadCache | | public AbstractConcurrentReadCache(Map t)(Code) | | Constructs a new map with the same mappings as the given map.
The map is created with a capacity of twice the number of mappings in
the given map or 11 (whichever is greater), and a default load factor.
|
| capacity | | public synchronized int capacity()(Code) | | Return the number of slots in this table.
|
| clear | | public synchronized void clear()(Code) | | Removes all mappings from this map.
|
| clone | | public synchronized Object clone()(Code) | | Returns a shallow copy of this.
AbstractConcurrentReadCache instance: the keys and
values themselves are not cloned.
a shallow copy of this map. |
| contains | | public boolean contains(Object value)(Code) | | Tests if some key maps into the specified value in this table.
This operation is more expensive than the containsKey
method.
Note that this method is identical in functionality to containsValue,
(which is part of the Map interface in the collections framework).
Parameters:
value - a value to search for. true if and only if some key maps to thevalue argument in this table asdetermined by the equals method;false otherwise.
exception:
NullPointerException - if the value is null.
See Also: AbstractConcurrentReadCache.containsKey(Object)
See Also: AbstractConcurrentReadCache.containsValue(Object)
See Also: Map |
| containsValue | | public boolean containsValue(Object value)(Code) | | Returns true if this map maps one or more keys to the
specified value. Note: This method requires a full internal
traversal of the hash table, and so is much slower than
method containsKey.
Parameters:
value - value whose presence in this map is to be tested. true if this map maps one or more keys to thespecified value.
exception:
NullPointerException - if the value is null. |
| entrySet | | public Set entrySet()(Code) | | Returns a collection view of the mappings contained in this map.
Each element in the returned collection is a Map.Entry. The
collection is backed by the map, so changes to the map are reflected in
the collection, and vice-versa. The collection supports element
removal, which removes the corresponding mapping from the map, via the
Iterator.remove, Collection.remove,
removeAll, retainAll, and clear operations.
It does not support the add or addAll operations.
a collection view of the mappings contained in this map. |
| findAndRemoveEntry | | protected synchronized boolean findAndRemoveEntry(Map.Entry entry)(Code) | | Helper method for entrySet remove.
|
| getGroup | | public Set getGroup(String groupName)(Code) | | Returns a set of the cache keys that reside in a particular group.
Parameters:
groupName - The name of the group to retrieve. a set containing all of the keys of cache entries that belongto this group, or null if the group was not found.
exception:
NullPointerException - if the groupName is null. |
| getGroupForReading | | final protected synchronized Set getGroupForReading(String groupName)(Code) | | Get ref to group.
CACHE-127 Synchronized copying of the group entry set since
the new HashSet(Collection c) constructor uses the iterator.
This may slow things down but it is better than a
ConcurrentModificationException. We might have to revisit the
code if performance is too adversely impacted.
|
| getGroupsForReading | | final protected Map getGroupsForReading()(Code) | | Get ref to groups.
The reference and the cells it
accesses will be at least as fresh as from last
use of barrierLock
|
| getMaxEntries | | public int getMaxEntries()(Code) | | Retrieve the cache capacity (number of entries).
|
| getTableForReading | | final protected Entry[] getTableForReading()(Code) | | Get ref to table; the reference and the cells it
accesses will be at least as fresh as from last
use of barrierLock
|
| isEmpty | | public synchronized boolean isEmpty()(Code) | | Returns true if this map contains no key-value mappings.
true if this map contains no key-value mappings. |
| isMemoryCaching | | public boolean isMemoryCaching()(Code) | | Check if memory caching is used.
|
| isOverflowPersistence | | public boolean isOverflowPersistence()(Code) | | Check if we use overflowPersistence
Returns the overflowPersistence. |
| isUnlimitedDiskCache | | public boolean isUnlimitedDiskCache()(Code) | | Check if we use unlimited disk cache.
|
| itemPut | | abstract protected void itemPut(Object key)(Code) | | Notify the underlying implementation that an item was put in the cache.
Parameters:
key - The cache key of the item that was put. |
| itemRemoved | | abstract protected void itemRemoved(Object key)(Code) | | Notify the underlying implementation that an item was removed from the cache.
Parameters:
key - The cache key of the item that was removed. |
| itemRetrieved | | abstract protected void itemRetrieved(Object key)(Code) | | Notify any underlying algorithm that an item has been retrieved from the cache.
Parameters:
key - The cache key of the item that was retrieved. |
| keySet | | public Set keySet()(Code) | | Returns a set view of the keys contained in this map.
The set is backed by the map, so changes to the map are reflected in the set, and
vice-versa. The set supports element removal, which removes the
corresponding mapping from this map, via the Iterator.remove,
Set.remove, removeAll, retainAll, and
clear operations. It does not support the add or
addAll operations.
a set view of the keys contained in this map. |
| loadFactor | | public float loadFactor()(Code) | | Return the load factor
|
| persistClear | | protected void persistClear()(Code) | | Removes the entire cache from persistent storage.
|
| persistRemove | | protected void persistRemove(Object key)(Code) | | Remove an object from the persistence.
Parameters:
key - The key of the object to remove |
| persistRemoveGroup | | protected void persistRemoveGroup(String groupName)(Code) | | Removes a cache group using the persistence listener.
Parameters:
groupName - The name of the group to remove |
| persistRetrieve | | protected Object persistRetrieve(Object key)(Code) | | Retrieve an object from the persistence listener.
Parameters:
key - The key of the object to retrieve |
| persistRetrieveGroup | | protected Set persistRetrieveGroup(String groupName)(Code) | | Retrieves a cache group using the persistence listener.
Parameters:
groupName - The name of the group to retrieve |
| persistStore | | protected void persistStore(Object key, Object obj)(Code) | | Store an object in the cache using the persistence listener.
Parameters:
key - The object key
Parameters:
obj - The object to store |
| persistStoreGroup | | protected void persistStoreGroup(String groupName, Set group)(Code) | | Creates or Updates a cache group using the persistence listener.
Parameters:
groupName - The name of the group to update
Parameters:
group - The entries for the group |
| putAll | | public synchronized void putAll(Map t)(Code) | | Copies all of the mappings from the specified map to this one.
These mappings replace any mappings that this map had for any of the
keys currently in the specified Map.
Parameters:
t - Mappings to be stored in this map. |
| recordModification | | final protected void recordModification(Object x)(Code) | | Force a memory synchronization that will cause
all readers to see table. Call only when already
holding main synch lock.
|
| rehash | | protected void rehash()(Code) | | Rehashes the contents of this map into a new table with a larger capacity.
This method is called automatically when the
number of keys in this map exceeds its capacity and load factor.
|
| removeForce | | public Object removeForce(Object key)(Code) | | Like remove(Object), but ensures that the entry will be removed from the persistent store, too,
even if overflowPersistence or unlimitedDiskcache are true.
Parameters:
key - the key that needs to be removed. the value to which the key had been mapped in this table,or null if the key did not have a mapping. |
| removeItem | | abstract protected Object removeItem()(Code) | | The cache has reached its cacpacity and an item needs to be removed.
(typically according to an algorithm such as LRU or FIFO).
The key of whichever item was removed. |
| setMaxEntries | | public void setMaxEntries(int newLimit)(Code) | | Set the cache capacity
|
| setMemoryCaching | | public void setMemoryCaching(boolean memoryCaching)(Code) | | Sets the memory caching flag.
|
| setOverflowPersistence | | public void setOverflowPersistence(boolean overflowPersistence)(Code) | | Sets the overflowPersistence flag
Parameters:
overflowPersistence - The overflowPersistence to set. |
| setPersistenceListener | | public void setPersistenceListener(PersistenceListener listener)(Code) | | Set the persistence listener to use.
|
| setUnlimitedDiskCache | | public void setUnlimitedDiskCache(boolean unlimitedDiskCache)(Code) | | Sets the unlimited disk caching flag.
|
| size | | public synchronized int size()(Code) | | Returns the total number of cache entries held in this map.
the number of key-value mappings in this map. |
| sremove | | protected Object sremove(Object key, int hash, boolean invokeAlgorithm)(Code) | | OpenSymphony BEGIN
|
| values | | public Collection values()(Code) | | Returns a collection view of the values contained in this map.
The collection is backed by the map, so changes to the map are reflected in
the collection, and vice-versa. The collection supports element
removal, which removes the corresponding mapping from this map, via the
Iterator.remove, Collection.remove,
removeAll, retainAll, and clear operations.
It does not support the add or addAll operations.
a collection view of the values contained in this map. |
|
|