org.infinispan.loaders.bucket
Class BucketBasedCacheStore

java.lang.Object
  org.infinispan.loaders.AbstractCacheLoader
      org.infinispan.loaders.AbstractCacheStore
          org.infinispan.loaders.LockSupportCacheStore
              org.infinispan.loaders.bucket.BucketBasedCacheStore

All Implemented Interfaces:

CacheLoader, CacheStore

Direct Known Subclasses:

CloudCacheStore, FileCacheStore, JdbcBinaryCacheStore

public abstract class BucketBasedCacheStore
extends LockSupportCacheStore

Base class for CacheStore implementations that combine entries into buckets when storing data.

A hashing algorithm is used to map keys to buckets, and a bucket consists of a collection of key/value pairs.

This approach, while adding an overhead of having to search through the contents of buckets a relevant entry, allows us to use any Serializable object as a key since the bucket is identified by a hash code. This hash code is often easy to represent in a physical store, such as a file system, database, etc.

Since:

4.0

Author:

Mircea.Markus@jboss.com, Manik Surtani

Nested Class Summary

protected static interface	BucketBasedCacheStore.BucketHandler
protected class	BucketBasedCacheStore.CollectionGeneratingBucketHandler<T>

Field Summary

Fields inherited from class org.infinispan.loaders.AbstractCacheStore

multiThreadedPurge, purgerService

Fields inherited from class org.infinispan.loaders.AbstractCacheLoader

cache, marshaller

Constructor Summary

BucketBasedCacheStore()

Method Summary

protected String	getLockFromKey(Object key) For BucketBasedCacheStores the lock should be acquired at bucket level.
protected void	insertBucket(Bucket bucket) Inserts a new Bucket in the storage system.
protected Set<Object>	loadAllKeysLockSafe(Set<Object> keysToExclude)
protected Set<InternalCacheEntry>	loadAllLockSafe()
protected abstract Bucket	loadBucket(String hash) Loads a Bucket from the store, based on the hash code of the bucket.
protected Set<InternalCacheEntry>	loadLockSafe(int max)
protected InternalCacheEntry	loadLockSafe(Object key, String lockingKey) Loads an entry from a Bucket, locating the relevant Bucket using the key's hash code.
protected abstract void	loopOverBuckets(BucketBasedCacheStore.BucketHandler handler) A mechanism to loop over all buckets in the cache store.
protected boolean	removeLockSafe(Object key, String lockingKey) Removes an entry from a Bucket, locating the relevant Bucket using the key's hash code.
protected void	storeLockSafe(InternalCacheEntry entry, String lockingKey) Stores an entry in an appropriate Bucket, based on the key's hash code.
protected abstract void	updateBucket(Bucket bucket) Updates a bucket in the store with the Bucket passed in to the method.

Methods inherited from class org.infinispan.loaders.LockSupportCacheStore

acquireGlobalLock, clear, clearLockSafe, fromStream, fromStreamLockSafe, getTotalLockCount, immediateLockForWriting, init, load, load, loadAll, loadAllKeys, lockForReading, lockForWriting, releaseGlobalLock, remove, start, store, toStream, toStreamLockSafe, unlock

Methods inherited from class org.infinispan.loaders.AbstractCacheStore

applyModifications, commit, getCacheStoreConfig, getConcurrencyLevel, getMarshaller, prepare, purgeExpired, purgeInternal, removeAll, rollback, safeClose, safeClose, stop, supportsMultiThreadedPurge

Methods inherited from class org.infinispan.loaders.AbstractCacheLoader

containsKey

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.infinispan.loaders.CacheLoader

containsKey, getConfigurationClass

Constructor Detail

BucketBasedCacheStore

public BucketBasedCacheStore()

Method Detail

loadLockSafe

protected InternalCacheEntry loadLockSafe(Object key,
                                          String lockingKey)
                                   throws CacheLoaderException

Loads an entry from a Bucket, locating the relevant Bucket using the key's hash code.

Specified by:

loadLockSafe in class LockSupportCacheStore

Parameters:

key - key of the entry to remove.

lockingKey - the hash of the key, as returned by LockSupportCacheStore.getLockFromKey(Object). This is required in order to avoid hash re-computation.

Throws:

CacheLoaderException

storeLockSafe

protected void storeLockSafe(InternalCacheEntry entry,
                             String lockingKey)
                      throws CacheLoaderException

Stores an entry in an appropriate Bucket, based on the key's hash code. If the Bucket does not exist in the underlying store, a new one is created.

Specified by:

storeLockSafe in class LockSupportCacheStore

Parameters:

entry - the entry to store

lockingKey - the hash of the key, as returned by LockSupportCacheStore.getLockFromKey(Object). This is required in order to avoid hash re-computation.

Throws:

CacheLoaderException

removeLockSafe

protected boolean removeLockSafe(Object key,
                                 String lockingKey)
                          throws CacheLoaderException

Removes an entry from a Bucket, locating the relevant Bucket using the key's hash code.

Specified by:

removeLockSafe in class LockSupportCacheStore

Parameters:

key - key of the entry to remove.

lockingKey - the hash of the key, as returned by LockSupportCacheStore.getLockFromKey(Object). This is required in order to avoid hash re-computation.

Throws:

CacheLoaderException

getLockFromKey

protected String getLockFromKey(Object key)

For BucketBasedCacheStores the lock should be acquired at bucket level. So we're locking based on the hash code of the key, as all keys having same hash code will be mapped to same bucket.

Specified by:

getLockFromKey in class LockSupportCacheStore

insertBucket

protected void insertBucket(Bucket bucket)
                     throws CacheLoaderException

Inserts a new Bucket in the storage system. If the bucket already exists, this method should simply update the store with the contents of the bucket - i.e., behave the same as updateBucket(Bucket).

Parameters:

bucket - bucket to insert

Throws:

CacheLoaderException - in case of problems with the store.

loadAllLockSafe

protected Set<InternalCacheEntry> loadAllLockSafe()
                                           throws CacheLoaderException

Specified by:

loadAllLockSafe in class LockSupportCacheStore

Throws:

CacheLoaderException

loadLockSafe

protected Set<InternalCacheEntry> loadLockSafe(int max)
                                        throws CacheLoaderException

Specified by:

loadLockSafe in class LockSupportCacheStore

Throws:

CacheLoaderException

loadAllKeysLockSafe

protected Set<Object> loadAllKeysLockSafe(Set<Object> keysToExclude)
                                   throws CacheLoaderException

Specified by:

loadAllKeysLockSafe in class LockSupportCacheStore

Throws:

CacheLoaderException

loopOverBuckets

protected abstract void loopOverBuckets(BucketBasedCacheStore.BucketHandler handler)
                                 throws CacheLoaderException

A mechanism to loop over all buckets in the cache store. Implementations should, very simply, loop over all available buckets, and for each deserialized bucket, pass it to the handler.

The implementation is expected to loop over all available buckets (in any order), until BucketBasedCacheStore.BucketHandler.handle(Bucket) returns true or there are no more buckets available.

Parameters:

handler -

Throws:

CacheLoaderException

updateBucket

protected abstract void updateBucket(Bucket bucket)
                              throws CacheLoaderException

Updates a bucket in the store with the Bucket passed in to the method. This method assumes that the bucket already exists in the store, however some implementations may choose to simply create a new bucket if the bucket does not exist.

The default behavior is that non-existent buckets are created on the fly. If this is not the case in your implementation, then you would have to override insertBucket(Bucket) as well so that it doesn't blindly forward calls to updateBucket(Bucket).

Parameters:

bucket - bucket to update.

Throws:

CacheLoaderException - in case of problems with the store.

loadBucket

protected abstract Bucket loadBucket(String hash)
                              throws CacheLoaderException

Loads a Bucket from the store, based on the hash code of the bucket.

Parameters:

hash - String representation of the Bucket's hash

Returns:

a Bucket if one exists, null otherwise.

Throws:

CacheLoaderException - in case of problems with the store.