ehcache

net.sf.ehcache.constructs.blocking
Class SelfPopulatingCache

java.lang.Object
  extended by net.sf.ehcache.constructs.EhcacheDecoratorAdapter
      extended by net.sf.ehcache.constructs.blocking.BlockingCache
          extended by net.sf.ehcache.constructs.blocking.SelfPopulatingCache
All Implemented Interfaces:
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: SelfPopulatingCache.java 8566 2014-01-06 14:31:53Z cschanck $
Author:
Greg Luck

Field Summary
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
SelfPopulatingCache(Ehcache cache, CacheEntryFactory factory)
          Creates a SelfPopulatingCache.
SelfPopulatingCache(Ehcache cache, int numberOfStripes, CacheEntryFactory factory)
          Create a SelfPopulatingCache, with a specific number of stripes passed to the underlying BlockingCache.
 
Method Summary
 Element get(Object key)
          Looks up an entry.
protected static Element makeAndCheckElement(Object key, 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(Object key)
          Refresh a single element.
 Element refresh(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(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:

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:

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(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(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 Exception
Refresh a single element.

Parameters:
element - the Element to refresh
backingCache - the underlying Ehcache.
Throws:
Exception

refreshElement

protected Element refreshElement(Element element,
                                 Ehcache backingCache,
                                 boolean quiet)
                          throws 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:
Exception
Since:
1.6.1

makeAndCheckElement

protected static Element makeAndCheckElement(Object key,
                                             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

ehcache

Copyright 2001-2014, Terracotta, Inc.