org.apache.jcs.engine.control
Class CompositeCache<K extends Serializable,V extends Serializable>

java.lang.Object
  org.apache.jcs.engine.control.CompositeCache<K,V>

All Implemented Interfaces:

Serializable, ICache<K,V>, ICacheType

public class CompositeCache<K extends Serializable,V extends Serializable>
extends Object
implements ICache<K,V>, 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

elementEventQ

public IElementEventQueue elementEventQ

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

keyMatcher

protected IKeyMatcher<K extends Serializable> keyMatcher

Key matcher used by the getMatching API

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

setAuxCaches

public void setAuxCaches(AuxiliaryCache<K,V>[] auxCaches)

This sets the list of auxiliary caches for this region.

Parameters:

auxCaches -

getAuxCaches

public AuxiliaryCache<K,V>[] getAuxCaches()

Get the list of auxiliary caches for this region.

Returns:

an array of auxiliary caches, may be empty, never null

update

public void update(ICacheElement<K,V> ce)
            throws IOException

Standard update method.

Specified by:

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

Parameters:

ce -

Throws:

IOException

localUpdate

public void localUpdate(ICacheElement<K,V> ce)
                 throws IOException

Standard update method.

Parameters:

ce -

Throws:

IOException

update

protected void update(ICacheElement<K,V> 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<K,V> 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<K,V> 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<K,V> get(K key)

Gets an item from the cache.

Specified by:

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

Parameters:

key -

Returns:

element from the cache, or null if not present

See Also:

ICache.get(java.io.Serializable)

localGet

public ICacheElement<K,V> localGet(K key)

Do not try to go remote or laterally for this get.

Parameters:

key -

Returns:

ICacheElement

get

protected ICacheElement<K,V> get(K 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<K,ICacheElement<K,V>> getMultiple(Set<K> keys)

Gets multiple items from the cache based on the given set of keys.

Specified by:

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

Parameters:

keys -

Returns:

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

localGetMultiple

public Map<K,ICacheElement<K,V>> localGetMultiple(Set<K> 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 K key to ICacheElement element, or an empty map if there is no data in cache for any of these keys

getMultiple

protected Map<K,ICacheElement<K,V>> getMultiple(Set<K> 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<K,ICacheElement<K,V>> getMatching(String pattern)

Build a map of all the matching elements in all of the auxiliaries and memory.

Specified by:

getMatching in interface ICache<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 for any matching keys

localGetMatching

public Map<K,ICacheElement<K,V>> 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 K key to ICacheElement element, or an empty map if there is no data in cache for any matching keys

getMatching

protected Map<K,ICacheElement<K,V>> 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 K key to ICacheElement element, or an empty map if there is no data in cache for any matching keys

getMatchingFromMemory

protected Map<K,ICacheElement<K,V>> 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 K key to ICacheElement element, or an empty map if there is no data in cache for any matching keys

Throws:

IOException

isExpired

protected boolean isExpired(ICacheElement<K,V> element)

Determine if the element has exceeded its max life.

Parameters:

element -

Returns:

true if the element is expired, else false.

getGroupKeys

public Set<K> getGroupKeys(String group)

Gets the set of keys of objects currently in the group.

Parameters:

group - the name of the group

Returns:

A Set of keys, or null.

getGroupKeys

public Set<K> getGroupKeys(String group,
                           boolean localOnly)

Gets the set of keys of objects currently in the group.

Parameters:

group - the name of the group

Returns:

A Set of keys, or null.

getGroupNames

public Set<String> getGroupNames()

Gets the set of group names in the cache

Returns:

a Set of group names.

getGroupNames

public Set<String> getGroupNames(boolean localOnly)

Gets the set of group names in the cache

Parameters:

localOnly - whether to get the group names only from local caches or not

Returns:

a Set of group names.

remove

public boolean remove(K key)

Removes an item from the cache.

Specified by:

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

Parameters:

key -

Returns:

true is it was removed

See Also:

ICache.remove(java.io.Serializable)

localRemove

public boolean localRemove(K key)

Do not propagate removeall laterally or remotely.

Parameters:

key -

Returns:

true if the item was already in the cache.

remove

protected boolean remove(K 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<K extends Serializable,V extends Serializable>

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<K extends Serializable,V extends Serializable>

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<K extends Serializable,V extends Serializable>

Returns:

The size value

getCacheType

public ICacheType.CacheType getCacheType()

Gets the cacheType attribute of the Cache object.

Specified by:

getCacheType in interface ICacheType

Returns:

The cacheType value

getStatus

public CacheStatus getStatus()

Gets the status attribute of the Cache object.

Specified by:

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

Returns:

The status value

getStats

public String getStats()

Gets stats for debugging.

Specified by:

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

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<K extends Serializable,V extends Serializable>

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(K key)
                                        throws CacheException,
                                               IOException

Gets the elementAttributes attribute of the Cache object.

Parameters:

key -

Returns:

The elementAttributes value

Throws:

CacheException

IOException

getMemoryCache

public IMemoryCache<K,V> 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<K> keyMatcher)

Sets the key matcher used by get matching.

Specified by:

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

Parameters:

keyMatcher -

getKeyMatcher

public IKeyMatcher<K> 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()