Package net.sf.ehcache.constructs.blocking

Class SelfPopulatingCache

java.lang.Object

net.sf.ehcache.constructs.EhcacheDecoratorAdapter

net.sf.ehcache.constructs.blocking.BlockingCache

net.sf.ehcache.constructs.blocking.SelfPopulatingCache

All Implemented Interfaces:

java.lang.Cloneable, Ehcache, InternalEhcache

Direct Known Subclasses:

UpdatingSelfPopulatingCache

public class SelfPopulatingCache
extends BlockingCache

A selfpopulating decorator for Ehcache that creates entries on demand.

Clients of the cache simply call it without needing knowledge of whether the entry exists in the cache.

The cache is designed to be refreshed. Refreshes operate on the backing cache, and do not degrade performance of BlockingCache.get(java.io.Serializable) calls.

Thread safety depends on the factory being used. The UpdatingCacheEntryFactory should be made thread safe. In addition users of returned values should not modify their contents.

Version:

$Id$

Author:

Greg Luck

Field Summary

Fields

Modifier and Type	Field	Description
protected CacheEntryFactory	factory	A factory for creating entries, given a key

Fields inherited from class net.sf.ehcache.constructs.blocking.BlockingCache

timeoutMillis

Fields inherited from class net.sf.ehcache.constructs.EhcacheDecoratorAdapter

underlyingCache

Constructor Summary

Constructors

Constructor	Description
SelfPopulatingCache(Ehcache cache, int numberOfStripes, CacheEntryFactory factory)	Create a SelfPopulatingCache, with a specific number of stripes passed to the underlying BlockingCache.
SelfPopulatingCache(Ehcache cache, CacheEntryFactory factory)	Creates a SelfPopulatingCache.

Method Summary

Modifier and Type	Method	Description
Element	get(java.lang.Object key)	Looks up an entry.
protected static Element	makeAndCheckElement(java.lang.Object key, java.lang.Object value)	Both CacheEntryFactory can return an Element rather than just a regular value this method test this, making a fresh Element otherwise.
void	refresh()	Refresh the elements of this cache.
void	refresh(boolean quiet)	Refresh the elements of this cache.
Element	refresh(java.lang.Object key)	Refresh a single element.
Element	refresh(java.lang.Object key, boolean quiet)	Refresh a single element.
protected void	refreshElement(Element element, Ehcache backingCache)	Refresh a single element.
protected Element	refreshElement(Element element, Ehcache backingCache, boolean quiet)	Refresh a single element.

Methods inherited from class net.sf.ehcache.constructs.blocking.BlockingCache

get, getAllWithLoader, getCache, getLockForKey, getTimeoutMillis, getWithLoader, liveness, load, loadAll, put, put, putIfAbsent, putIfAbsent, putQuiet, putWithWriter, registerCacheLoader, setTimeoutMillis, unregisterCacheLoader

Methods inherited from class net.sf.ehcache.constructs.EhcacheDecoratorAdapter

acquireReadLockOnKey, acquireWriteLockOnKey, addPropertyChangeListener, bootstrap, calculateInMemorySize, calculateOffHeapSize, calculateOnDiskSize, clone, createQuery, disableDynamicFeatures, dispose, evictExpiredElements, flush, getAll, getBootstrapCacheLoader, getCacheConfiguration, getCacheEventNotificationService, getCacheExceptionHandler, getCacheManager, getDiskStoreSize, getGuid, getInternalContext, getKeys, getKeysNoDuplicateCheck, getKeysWithExpiryCheck, getMemoryStoreSize, getName, getOffHeapStoreSize, getQuiet, getQuiet, getRegisteredCacheExtensions, getRegisteredCacheLoaders, getRegisteredCacheWriter, getSearchAttribute, getSearchAttributes, getSize, getStatistics, getStatus, getWriterManager, hasAbortedSizeOf, initialise, isClusterBulkLoadEnabled, isClusterCoherent, isDisabled, isElementInMemory, isElementInMemory, isElementOnDisk, isElementOnDisk, isExpired, isKeyInCache, isNodeBulkLoadEnabled, isNodeCoherent, isReadLockedByCurrentThread, isSearchable, isValueInCache, isWriteLockedByCurrentThread, putAll, recalculateSize, registerCacheExtension, registerCacheWriter, registerDynamicAttributesExtractor, releaseReadLockOnKey, releaseWriteLockOnKey, remove, remove, remove, remove, removeAll, removeAll, removeAll, removeAll, removeAndReturnElement, removeElement, removePropertyChangeListener, removeQuiet, removeQuiet, removeWithWriter, replace, replace, setBootstrapCacheLoader, setCacheExceptionHandler, setCacheManager, setDisabled, setName, setNodeBulkLoadEnabled, setNodeCoherent, setTransactionManagerLookup, toString, tryReadLockOnKey, tryWriteLockOnKey, unregisterCacheExtension, unregisterCacheWriter, waitUntilClusterBulkLoadComplete, waitUntilClusterCoherent

Methods inherited from class java.lang.Object

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

Field Detail

factory

protected final CacheEntryFactory factory

A factory for creating entries, given a key

Constructor Detail

SelfPopulatingCache

public SelfPopulatingCache(Ehcache cache,
                           CacheEntryFactory factory)
                    throws CacheException

Creates a SelfPopulatingCache.

Throws:

CacheException

SelfPopulatingCache

public SelfPopulatingCache(Ehcache cache,
                           int numberOfStripes,
                           CacheEntryFactory factory)
                    throws CacheException

Create a SelfPopulatingCache, with a specific number of stripes passed to the underlying BlockingCache.

Throws:

CacheException

Method Detail

get

public Element get(java.lang.Object key)
            throws LockTimeoutException

Looks up an entry. creating it if not found.

Specified by:

get in interface Ehcache

Overrides:

get in class BlockingCache

Parameters:

key - an Object value

Returns:

the element, or null, if it does not exist.

Throws:

LockTimeoutException - if timeout millis is non zero and this method has been unable to acquire a lock in that time

See Also:

Ehcache.isExpired(net.sf.ehcache.Element)

refresh

public void refresh()
             throws CacheException

Refresh the elements of this cache.

Refreshes bypass the BlockingCache and act directly on the backing Ehcache. This way, BlockingCache gets can continue to return stale data while the refresh, which might be expensive, takes place.

Quiet methods are used, so that statistics are not affected. Note that the refreshed elements will not be replicated to any cache peers.

Configure ehcache.xml to stop elements from being refreshed forever:

• use timeToIdle to discard elements unused for a period of time
• use timeToLive to discard elmeents that have existed beyond their allotted lifespan

Throws:

CacheException

refresh

public void refresh(boolean quiet)
             throws CacheException

Refresh the elements of this cache.

Refreshes bypass the BlockingCache and act directly on the backing Ehcache. This way, BlockingCache gets can continue to return stale data while the refresh, which might be expensive, takes place.

Quiet methods are used if argument 0 is true, so that statistics are not affected, but note that replication will then not occur

Configure ehcache.xml to stop elements from being refreshed forever:

• use timeToIdle to discard elements unused for a period of time
• use timeToLive to discard elmeents that have existed beyond their allotted lifespan

Parameters:

quiet - whether the backing cache is quietly updated or not, if true replication will not occur

Throws:

CacheException

Since:

1.6.1

refresh

public Element refresh(java.lang.Object key)
                throws CacheException

Refresh a single element.

Refreshes bypass the BlockingCache and act directly on the backing Ehcache. This way, BlockingCache gets can continue to return stale data while the refresh, which might be expensive, takes place.

If the element is absent it is created

Quiet methods are used, so that statistics are not affected. Note that the refreshed element will not be replicated to any cache peers.

Parameters:

key -

Returns:

the refreshed Element

Throws:

CacheException

Since:

1.6.1

refresh

public Element refresh(java.lang.Object key,
                       boolean quiet)
                throws CacheException

Refresh a single element.

Refreshes bypass the BlockingCache and act directly on the backing Ehcache. This way, BlockingCache gets can continue to return stale data while the refresh, which might be expensive, takes place.

If the element is absent it is created

Quiet methods are used if argument 1 is true, so that statistics are not affected, but note that replication will then not occur

Parameters:

key -

quiet - whether the backing cache is quietly updated or not, if true replication will not occur

Returns:

the refreshed Element

Throws:

CacheException

Since:

1.6.1

refreshElement

protected void refreshElement(Element element,
                              Ehcache backingCache)
                       throws java.lang.Exception

Refresh a single element.

Parameters:

element - the Element to refresh

backingCache - the underlying Ehcache.

Throws:

java.lang.Exception

refreshElement

protected Element refreshElement(Element element,
                                 Ehcache backingCache,
                                 boolean quiet)
                          throws java.lang.Exception

Refresh a single element.

Parameters:

element - the Element to refresh

backingCache - the underlying Ehcache.

quiet - whether to use putQuiet or not, if true replication will not occur

Returns:

the refreshed Element

Throws:

java.lang.Exception

Since:

1.6.1

makeAndCheckElement

protected static Element makeAndCheckElement(java.lang.Object key,
                                             java.lang.Object value)
                                      throws CacheException

Both CacheEntryFactory can return an Element rather than just a regular value this method test this, making a fresh Element otherwise. It also enforces the rule that the CacheEntryFactory must provide the same key (via equals() not necessarily same object) if it is returning an Element.

Parameters:

key -

value -

Returns:

the Element to be put back in the cache

Throws:

CacheException - for various illegal states which could be harmful