org.apache.jcs.engine.control
Class CompositeCache

java.lang.Object
  extended by org.apache.jcs.engine.control.CompositeCache
All Implemented Interfaces:
Serializable, ICache, ICacheType

public class CompositeCache
extends Object
implements ICache, Serializable

This is the primary hub for a single cache/region. It controls the flow of items through the cache. The auxiliary and memory caches are plugged in here.

This is the core of a JCS region. Hence, this simple class is the core of JCS.

See Also:
Serialized Form

Field Summary
 IElementEventQueue elementEventQ
          EventQueue for handling element events.
protected  IKeyMatcher keyMatcher
          Key matcher used by the getMatching API
 
Fields inherited from interface org.apache.jcs.engine.behavior.ICacheType
CACHE_HUB, DISK_CACHE, LATERAL_CACHE, REMOTE_CACHE
 
Constructor Summary
CompositeCache(String cacheName, ICompositeCacheAttributes cattr, IElementAttributes attr)
          Constructor for the Cache object
 
Method Summary
 void addElementEvent(IElementEventHandler hand, IElementEvent event)
          Adds an ElementEvent to be handled to the queue.
 void dispose()
          Flushes all cache items from memory to auxiliary caches and close the auxiliary caches.
 void dispose(boolean fromRemote)
          Invoked only by CacheManager.
 ICacheElement get(Serializable key)
          Gets an item from the cache.
protected  ICacheElement get(Serializable key, boolean localOnly)
          Look in memory, then disk, remote, or laterally for this item.
 ICompositeCacheAttributes getCacheAttributes()
          Gets the ICompositeCacheAttributes attribute of the Cache object.
 String getCacheName()
          Gets the cacheName attribute of the Cache object.
 int getCacheType()
          Gets the cacheType attribute of the Cache object.
 IElementAttributes getElementAttributes()
          Gets the default element attribute of the Cache object This returna a copy.
 IElementAttributes getElementAttributes(Serializable key)
          Gets the elementAttributes attribute of the Cache object.
 Set getGroupKeys(String group)
          Gets the set of keys of objects currently in the group.
 int getHitCountAux()
          Number of times a requested item was found in and auxiliary cache.
 int getHitCountRam()
          Number of times a requested item was found in the memory cache.
 IKeyMatcher getKeyMatcher()
          Returns the key matcher used by get matching.
 Map getMatching(String pattern)
          Build a map of all the matching elements in all of the auxiliaries and memory.
protected  Map getMatching(String pattern, boolean localOnly)
          Build a map of all the matching elements in all of the auxiliaries and memory.
protected  Map getMatchingFromMemory(String pattern)
          Gets the key array from the memcache.
 MemoryCache getMemoryCache()
          Access to the memory cache for instrumentation.
 int getMissCountExpired()
          Number of times a requested element was found but was expired.
 int getMissCountNotFound()
          Number of times a requested element was not found.
 Map getMultiple(Set keys)
          Gets multiple items from the cache based on the given set of keys.
protected  Map getMultiple(Set keys, boolean localOnly)
          Look in memory, then disk, remote, or laterally for these items.
 int getRemoveCount()
           
 int getSize()
          Gets the size attribute of the Cache object.
 ICacheStats getStatistics()
          This returns data gathered for this region and all the auxiliaries it currently uses.
 String getStats()
          Gets stats for debugging.
 int getStatus()
          Gets the status attribute of the Cache object.
 int getUpdateCount()
           
 ICacheElement localGet(Serializable key)
          Do not try to go remote or laterally for this get.
 Map localGetMatching(String pattern)
          Build a map of all the matching elements in all of the auxiliaries and memory.
 Map localGetMultiple(Set keys)
          Gets multiple items from the cache based on the given set of keys.
 boolean localRemove(Serializable key)
          Do not propagate removeall laterally or remotely.
 void localRemoveAll()
          Will not pass the remove message remotely.
 void localUpdate(ICacheElement ce)
          Standard update method.
 boolean remove(Serializable key)
          Removes an item from the cache.
protected  boolean remove(Serializable key, boolean localOnly)
          fromRemote: If a remove call was made on a cache with both, then the remote should have been called.
 void removeAll()
          Clears the region.
protected  void removeAll(boolean localOnly)
          Removes all cached items.
 void save()
          Calling save cause the entire contents of the memory cache to be flushed to all auxiliaries.
 void setAuxCaches(AuxiliaryCache[] auxCaches)
          This sets the list of auxiliary caches for this region.
 void setCacheAttributes(ICompositeCacheAttributes cattr)
          Sets the ICompositeCacheAttributes attribute of the Cache object.
 void setElementAttributes(IElementAttributes attr)
          Sets the default element attribute of the Cache object.
 void setKeyMatcher(IKeyMatcher keyMatcher)
          Sets the key matcher used by get matching.
 void setRemoveCount(int removeCount)
           
 void setUpdateCount(int updateCount)
           
 void spoolToDisk(ICacheElement ce)
          Writes the specified element to any disk auxiliaries.
 String toString()
          This returns the stats.
 void update(ICacheElement ce)
          Standard update method.
protected  void update(ICacheElement cacheElement, boolean localOnly)
          Put an item into the cache.
protected  void updateAuxiliaries(ICacheElement cacheElement, boolean localOnly)
          This method is responsible for updating the auxiliaries if they are present.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

elementEventQ

public IElementEventQueue elementEventQ
EventQueue for handling element events. Lazy initialized. One for each region. To be more eficient, the manager should pass a shared queue in.


keyMatcher

protected IKeyMatcher keyMatcher
Key matcher used by the getMatching API

Constructor Detail

CompositeCache

public CompositeCache(String cacheName,
                      ICompositeCacheAttributes cattr,
                      IElementAttributes attr)
Constructor for the Cache object

Parameters:
cacheName - The name of the region
cattr - The cache attribute
attr - The default element attributes
Method Detail

setAuxCaches

public void setAuxCaches(AuxiliaryCache[] auxCaches)
This sets the list of auxiliary caches for this region.

Parameters:
auxCaches -

update

public void update(ICacheElement ce)
            throws IOException
Standard update method.

Specified by:
update in interface ICache
Parameters:
ce -
Throws:
IOException

localUpdate

public void localUpdate(ICacheElement ce)
                 throws IOException
Standard update method.

Parameters:
ce -
Throws:
IOException

update

protected void update(ICacheElement cacheElement,
                      boolean localOnly)
               throws IOException
Put an item into the cache. If it is localOnly, then do no notify remote or lateral auxiliaries.

Parameters:
cacheElement - the ICacheElement
localOnly - Whether the operation should be restricted to local auxiliaries.
Throws:
IOException

updateAuxiliaries

protected void updateAuxiliaries(ICacheElement cacheElement,
                                 boolean localOnly)
                          throws IOException
This method is responsible for updating the auxiliaries if they are present. If it is local only, any lateral and remote auxiliaries will not be updated.

Before updating an auxiliary it checks to see if the element attributes permit the operation.

Disk auxiliaries are only updated if the disk cache is not merely used as a swap. If the disk cache is merely a swap, then items will only go to disk when they overflow from memory.

This is called by update( cacheElement, localOnly ) after it updates the memory cache.

This is protected to make it testable.

Parameters:
cacheElement -
localOnly -
Throws:
IOException

spoolToDisk

public void spoolToDisk(ICacheElement ce)
Writes the specified element to any disk auxiliaries. Might want to rename this "overflow" in case the hub wants to do something else.

If JCS is not configured to use the disk as a swap, that is if the the CompositeCacheAttribute diskUsagePattern is not SWAP_ONLY, then the item will not be spooled.

Parameters:
ce - The CacheElement

get

public ICacheElement get(Serializable key)
Gets an item from the cache.

Specified by:
get in interface ICache
Parameters:
key -
Returns:
element from the cache, or null if not present
See Also:
ICache.get(java.io.Serializable)

localGet

public ICacheElement localGet(Serializable key)
Do not try to go remote or laterally for this get.

Parameters:
key -
Returns:
ICacheElement

get

protected ICacheElement get(Serializable key,
                            boolean localOnly)
Look in memory, then disk, remote, or laterally for this item. The order is dependent on the order in the cache.ccf file.

Do not try to go remote or laterally for this get if it is localOnly. Otherwise try to go remote or lateral if such an auxiliary is configured for this region.

Parameters:
key -
localOnly -
Returns:
ICacheElement

getMultiple

public Map getMultiple(Set keys)
Gets multiple items from the cache based on the given set of keys.

Specified by:
getMultiple in interface ICache
Parameters:
keys -
Returns:
a map of Serializable key to ICacheElement element, or an empty map if there is no data in cache for any of these keys

localGetMultiple

public Map localGetMultiple(Set keys)
Gets multiple items from the cache based on the given set of keys. Do not try to go remote or laterally for this data.

Parameters:
keys -
Returns:
a map of Serializable key to ICacheElement element, or an empty map if there is no data in cache for any of these keys

getMultiple

protected Map getMultiple(Set keys,
                          boolean localOnly)
Look in memory, then disk, remote, or laterally for these items. The order is dependent on the order in the cache.ccf file. Keep looking in each cache location until either the element is found, or the method runs out of places to look.

Do not try to go remote or laterally for this get if it is localOnly. Otherwise try to go remote or lateral if such an auxiliary is configured for this region.

Parameters:
keys -
localOnly -
Returns:
ICacheElement

getMatching

public Map getMatching(String pattern)
Build a map of all the matching elements in all of the auxiliaries and memory.

Specified by:
getMatching in interface ICache
Parameters:
pattern -
Returns:
a map of Serializable key to ICacheElement element, or an empty map if there is no data in cache for any matching keys

localGetMatching

public Map localGetMatching(String pattern)
Build a map of all the matching elements in all of the auxiliaries and memory. Do not try to go remote or laterally for this data.

Parameters:
pattern -
Returns:
a map of Serializable key to ICacheElement element, or an empty map if there is no data in cache for any matching keys

getMatching

protected Map getMatching(String pattern,
                          boolean localOnly)
Build a map of all the matching elements in all of the auxiliaries and memory. Items in memory will replace from the auxiliaries in the returned map. The auxiliaries are accessed in opposite order. It's assumed that those closer to home are better.

Do not try to go remote or laterally for this get if it is localOnly. Otherwise try to go remote or lateral if such an auxiliary is configured for this region.

Parameters:
pattern -
localOnly -
Returns:
a map of Serializable key to ICacheElement element, or an empty map if there is no data in cache for any matching keys

getMatchingFromMemory

protected Map getMatchingFromMemory(String pattern)
                             throws IOException
Gets the key array from the memcache. Builds a set of matches. Calls getMultiple with the set. Returns a map: key -> result.

Parameters:
pattern -
Returns:
a map of Serializable key to ICacheElement element, or an empty map if there is no data in cache for any matching keys
Throws:
IOException

getGroupKeys

public Set getGroupKeys(String group)
Gets the set of keys of objects currently in the group.

Parameters:
group -
Returns:
A Set of keys, or null.

remove

public boolean remove(Serializable key)
Removes an item from the cache.

Specified by:
remove in interface ICache
Parameters:
key -
Returns:
true is it was removed
See Also:
ICache.remove(java.io.Serializable)

localRemove

public boolean localRemove(Serializable key)
Do not propagate removeall laterally or remotely.

Parameters:
key -
Returns:
true if the item was already in the cache.

remove

protected boolean remove(Serializable key,
                         boolean localOnly)
fromRemote: If a remove call was made on a cache with both, then the remote should have been called. If it wasn't then the remote is down. we'll assume it is down for all. If it did come from the remote then the cache is remotely configured and lateral removal is unnecessary. If it came laterally then lateral removal is unnecessary. Does this assume that there is only one lateral and remote for the cache? Not really, the initial removal should take care of the problem if the source cache was similarly configured. Otherwise the remote cache, if it had no laterals, would remove all the elements from remotely configured caches, but if those caches had some other weird laterals that were not remotely configured, only laterally propagated then they would go out of synch. The same could happen for multiple remotes. If this looks necessary we will need to build in an identifier to specify the source of a removal.

Parameters:
key -
localOnly -
Returns:
true if the item was in the cache, else false

removeAll

public void removeAll()
               throws IOException
Clears the region. This command will be sent to all auxiliaries. Some auxiliaries, such as the JDBC disk cache, can be configured to not honor removeAll requests.

Specified by:
removeAll in interface ICache
Throws:
IOException
See Also:
ICache.removeAll()

localRemoveAll

public void localRemoveAll()
                    throws IOException
Will not pass the remove message remotely.

Throws:
IOException

removeAll

protected void removeAll(boolean localOnly)
                  throws IOException
Removes all cached items.

Parameters:
localOnly - must pass in false to get remote and lateral aux's updated. This prevents looping.
Throws:
IOException

dispose

public void dispose()
Flushes all cache items from memory to auxiliary caches and close the auxiliary caches.

Specified by:
dispose in interface ICache

dispose

public void dispose(boolean fromRemote)
Invoked only by CacheManager. This method disposes of the auxiliaries one by one. For the disk cache, the items in memory are freed, meaning that they will be sent through the overflow channel to disk. After the auxiliaries are disposed, the memory cache is disposed.

Parameters:
fromRemote -

save

public void save()
Calling save cause the entire contents of the memory cache to be flushed to all auxiliaries. Though this put is extremely fast, this could bog the cache and should be avoided. The dispose method should call a version of this. Good for testing.


getSize

public int getSize()
Gets the size attribute of the Cache object. This return the number of elements, not the byte size.

Specified by:
getSize in interface ICache
Returns:
The size value

getCacheType

public int getCacheType()
Gets the cacheType attribute of the Cache object.

Specified by:
getCacheType in interface ICacheType
Returns:
The cacheType value

getStatus

public int getStatus()
Gets the status attribute of the Cache object.

Specified by:
getStatus in interface ICache
Returns:
The status value

getStats

public String getStats()
Gets stats for debugging.

Specified by:
getStats in interface ICache
Returns:
String

getStatistics

public ICacheStats getStatistics()
This returns data gathered for this region and all the auxiliaries it currently uses.

Returns:
Statistics and Info on the Region.

getCacheName

public String getCacheName()
Gets the cacheName attribute of the Cache object. This is also known as the region name.

Specified by:
getCacheName in interface ICache
Returns:
The cacheName value

getElementAttributes

public IElementAttributes getElementAttributes()
Gets the default element attribute of the Cache object This returna a copy. It does not return a reference to the attributes.

Returns:
The attributes value

setElementAttributes

public void setElementAttributes(IElementAttributes attr)
Sets the default element attribute of the Cache object.

Parameters:
attr -

getCacheAttributes

public ICompositeCacheAttributes getCacheAttributes()
Gets the ICompositeCacheAttributes attribute of the Cache object.

Returns:
The ICompositeCacheAttributes value

setCacheAttributes

public void setCacheAttributes(ICompositeCacheAttributes cattr)
Sets the ICompositeCacheAttributes attribute of the Cache object.

Parameters:
cattr - The new ICompositeCacheAttributes value

getElementAttributes

public IElementAttributes getElementAttributes(Serializable key)
                                        throws CacheException,
                                               IOException
Gets the elementAttributes attribute of the Cache object.

Parameters:
key -
Returns:
The elementAttributes value
Throws:
CacheException
IOException

getMemoryCache

public MemoryCache getMemoryCache()
Access to the memory cache for instrumentation.

Returns:
the MemoryCache implementation

getHitCountRam

public int getHitCountRam()
Number of times a requested item was found in the memory cache.

Returns:
number of hits in memory

getHitCountAux

public int getHitCountAux()
Number of times a requested item was found in and auxiliary cache.

Returns:
number of auxiliary hits.

getMissCountNotFound

public int getMissCountNotFound()
Number of times a requested element was not found.

Returns:
number of misses.

getMissCountExpired

public int getMissCountExpired()
Number of times a requested element was found but was expired.

Returns:
number of found but expired gets.

addElementEvent

public void addElementEvent(IElementEventHandler hand,
                            IElementEvent event)
                     throws IOException
Adds an ElementEvent to be handled to the queue.

Parameters:
hand - The IElementEventHandler
event - The IElementEventHandler IElementEvent event
Throws:
IOException - Description of the Exception

setKeyMatcher

public void setKeyMatcher(IKeyMatcher keyMatcher)
Sets the key matcher used by get matching.

Specified by:
setKeyMatcher in interface ICache
Parameters:
keyMatcher -

getKeyMatcher

public IKeyMatcher getKeyMatcher()
Returns the key matcher used by get matching.

Returns:
keyMatcher

setUpdateCount

public void setUpdateCount(int updateCount)
Parameters:
updateCount - The updateCount to set.

getUpdateCount

public int getUpdateCount()
Returns:
Returns the updateCount.

setRemoveCount

public void setRemoveCount(int removeCount)
Parameters:
removeCount - The removeCount to set.

getRemoveCount

public int getRemoveCount()
Returns:
Returns the removeCount.

toString

public String toString()
This returns the stats.

Overrides:
toString in class Object
Returns:
getStats()


Copyright © 2002-2012 Apache Software Foundation. All Rights Reserved.