org.infinispan.loaders.bdbje

Class BdbjeCacheStore

java.lang.Object

org.infinispan.loaders.AbstractCacheLoader

org.infinispan.loaders.AbstractCacheStore

org.infinispan.loaders.bdbje.BdbjeCacheStore

All Implemented Interfaces:

CacheLoader, CacheStore

public class BdbjeCacheStore
extends AbstractCacheStore

An Oracle SleepyCat JE implementation of a CacheStore.

This implementation uses two databases

1. stored entry database: /{location}/CacheInstance-name
stored entries are stored here, keyed on CacheEntry.getKey()
2. class catalog database: /{location}/CacheInstance-name_class_catalog
class descriptions are stored here for efficiency reasons.

/{location}/je.properties is optional and will override any parameters to the internal SleepyCat JE EnvironmentConfig.

All data access is transactional. Any attempted reads to locked records will block. The maximum duration of this is set in nanoseconds via the parameter BdbjeCacheStoreConfig.getLockAcquistionTimeout(). Calls to CacheStore.prepare(java.util.List, org.infinispan.transaction.xa.GlobalTransaction, boolean) will attempt to resolve deadlocks, retrying up to BdbjeCacheStoreConfig.getMaxTxRetries() attempts.

Unlike the C version of SleepyCat, JE does not support MVCC or READ_COMMITTED isolation. In other words, readers will block on any data held by a pending transaction. As such, it is best practice to keep the duration between prepare and commit as short as possible.

Since:

4.0

Author:

Adrian Cole, Manik Surtani

Field Summary

Fields inherited from class org.infinispan.loaders.AbstractCacheStore

multiThreadedPurge, purgerService

Fields inherited from class org.infinispan.loaders.AbstractCacheLoader

cache, marshaller

Constructor Summary

Constructors

Constructor and Description
BdbjeCacheStore()

Method Summary

Methods

Modifier and Type	Method and Description
protected void	applyModifications(List<? extends Modification> mods) Perform the mods atomically by creating a worker and invoking them in TransactionRunner.run(com.sleepycat.collections.TransactionWorker).
void	clear() Clears all entries in the store
void	commit(GlobalTransaction tx) Commits a transaction that has been previously prepared.
protected void	completeTransaction(GlobalTransaction tx, boolean commit) Looks up the SleepyCat transaction associated with the parameter tx.
void	fromStream(ObjectInput ois) Writes contents of the stream to the store.
Class<? extends CacheLoaderConfig>	getConfigurationClass() This method is used by the configuration parser to get a hold of the CacheLoader implementation's corresponding CacheLoaderConfig type.
void	init(CacheLoaderConfig config, Cache<?,?> cache, StreamingMarshaller m) Used to initialize a cache loader.
Set<InternalCacheEntry>	load(int numEntries) Loads up to a specific number of entries.
InternalCacheEntry	load(Object key) Loads an entry mapped to by a given key.
Set<InternalCacheEntry>	loadAll() Loads all entries in the loader.
Set<Object>	loadAllKeys(Set<Object> keysToExclude) Loads a set of all keys, excluding a filter set.
protected void	prepare(List<? extends Modification> mods, GlobalTransaction tx) Looks up the SleepyCat transaction associated with tx.
void	prepare(List<? extends Modification> mods, GlobalTransaction tx, boolean isOnePhase) Issues a prepare call with a set of modifications to be applied to the cache store
void	printLicense() prints terms of use for Berkeley DB JE
protected void	purgeInternal() Iterate through StoredMap.entrySet() and remove, if expired.
boolean	remove(Object key) Removes an entry in the store.
void	rollback(GlobalTransaction tx) Rolls back a transaction that has been previously prepared This method may be invoked on a transaction for which there is no prior CacheStore.prepare(java.util.List, org.infinispan.transaction.xa.GlobalTransaction, boolean).
void	start() Validates configuration, configures and opens the Environment, then opens the databases.
void	stop() Stops transaction and purge processing and closes the SleepyCat environment.
void	store(InternalCacheEntry ed) Stores an entry
void	toStream(ObjectOutput oos) Writes the current count of cachestore entries followed by a pair of byte[]s corresponding to the SleepyCat binary representation of key value.

Methods inherited from class org.infinispan.loaders.AbstractCacheStore

getCacheStoreConfig, getConcurrencyLevel, getMarshaller, purgeExpired, removeAll, safeClose, safeClose, 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

Constructor Detail

BdbjeCacheStore

public BdbjeCacheStore()

Method Detail

init

public void init(CacheLoaderConfig config,
        Cache<?,?> cache,
        StreamingMarshaller m)
          throws CacheLoaderException

Used to initialize a cache loader. Typically invoked by the CacheLoaderManager when setting up cache loaders. This implementation expects config to be an instance of BdbjeCacheStoreConfig

note that the m is not currently used as SleepyCat has its own efficient solution.

Specified by:

init in interface CacheLoader

Overrides:

init in class AbstractCacheStore

Parameters:

config - the cache loader configuration bean

cache - cache associated with this cache loader. Implementations may use this to determine cache name when selecting where refer to state in storage, for example, a different database table name.

m - marshaller to use when loading state from a stream, if supported by the implementation.

Throws:

CacheLoaderException

See Also:

BdbjeCacheStoreConfig

getConfigurationClass

public Class<? extends CacheLoaderConfig> getConfigurationClass()

This method is used by the configuration parser to get a hold of the CacheLoader implementation's corresponding CacheLoaderConfig type. This is usually done by instantiating the CacheLoader and then calling this method. This may result in 2 instances being created, however, since the instance created to get a hold of the configuration type is then discarded and another instance is created for actual use as a CacheLoader when the cache starts.

Since Infinispan 4.1, you can also annotate your CacheLoader implementation with CacheLoaderMetadata and provide this information via the annotation, which will prevent unnecessary instances being created.

Returns:

BdbjeCacheStoreConfig

start

public void start()
           throws CacheLoaderException

Validates configuration, configures and opens the Environment, then opens the databases. When this is finished, transactional and purging services are instantiated.

Specified by:

start in interface CacheLoader

Overrides:

start in class AbstractCacheStore

Throws:

CacheLoaderException

stop

public void stop()
          throws CacheLoaderException

Stops transaction and purge processing and closes the SleepyCat environment. The environment and databases are not removed from the file system. Exceptions during close of databases are ignored as closing the environment will ensure the databases are also.

Specified by:

stop in interface CacheLoader

Overrides:

stop in class AbstractCacheStore

Throws:

CacheLoaderException

prepare

public void prepare(List<? extends Modification> mods,
           GlobalTransaction tx,
           boolean isOnePhase)
             throws CacheLoaderException

Issues a prepare call with a set of modifications to be applied to the cache store delegates to applyModifications(java.util.List), if isOnePhase. Otherwise, delegates to prepare(java.util.List, org.infinispan.transaction.xa.GlobalTransaction)

Specified by:

prepare in interface CacheStore

Overrides:

prepare in class AbstractCacheStore

Parameters:

mods - modifications to be applied

tx - transaction identifier

isOnePhase - if true, there will not be a commit or rollback phase and changes should be flushed immediately

Throws:

CacheLoaderException - in the event of problems writing to the store

applyModifications

protected void applyModifications(List<? extends Modification> mods)
                           throws CacheLoaderException

Perform the mods atomically by creating a worker and invoking them in TransactionRunner.run(com.sleepycat.collections.TransactionWorker).

Overrides:

applyModifications in class AbstractCacheStore

Parameters:

mods - actions to perform atomically

Throws:

CacheLoaderException - on problems during the transaction

prepare

protected void prepare(List<? extends Modification> mods,
           GlobalTransaction tx)
                throws CacheLoaderException

Looks up the SleepyCat transaction associated with tx. Creates a ModificationsTransactionWorker instance from mods. Then prepares the transaction via PreparableTransactionRunner.prepare(com.sleepycat.collections.TransactionWorker). Finally, it invalidates CurrentTransaction.getTransaction() so that no other thread can accidentally commit this.

Parameters:

mods - modifications to be applied

tx - transaction identifier

Throws:

CacheLoaderException - in the event of problems writing to the store

rollback

public void rollback(GlobalTransaction tx)

Rolls back a transaction that has been previously prepared

This method may be invoked on a transaction for which there is no prior CacheStore.prepare(java.util.List, org.infinispan.transaction.xa.GlobalTransaction, boolean). The implementation would need to deal with this case accordingly. Typically, this would be a no-op, after ensuring any resources attached to the transaction are cleared up.

Also note that this method may be invoked on a thread which is different from the CacheStore.prepare(java.util.List, org.infinispan.transaction.xa.GlobalTransaction, boolean) invocation. As such, ThreadLocals should not be relied upon to maintain transaction context.

This implementation calls completeTransaction(org.infinispan.transaction.xa.GlobalTransaction, boolean) completeTransaction} with an argument of false.

Specified by:

rollback in interface CacheStore

Overrides:

rollback in class AbstractCacheStore

Parameters:

tx - tx to roll back

commit

public void commit(GlobalTransaction tx)
            throws CacheLoaderException

Commits a transaction that has been previously prepared.

This method may be invoked on a transaction for which there is no prior CacheStore.prepare(java.util.List, org.infinispan.transaction.xa.GlobalTransaction, boolean). The implementation would need to deal with this case accordingly. Typically, this would be a no-op, after ensuring any resources attached to the transaction are cleared up.

Also note that this method may be invoked on a thread which is different from the CacheStore.prepare(java.util.List, org.infinispan.transaction.xa.GlobalTransaction, boolean) invocation. As such, ThreadLocals should not be relied upon to maintain transaction context.

This implementation calls completeTransaction(org.infinispan.transaction.xa.GlobalTransaction, boolean) completeTransaction} with an argument of true.

Specified by:

commit in interface CacheStore

Overrides:

commit in class AbstractCacheStore

Parameters:

tx - tx to commit

Throws:

CacheLoaderException - in the event of problems writing to the store

completeTransaction

protected void completeTransaction(GlobalTransaction tx,
                       boolean commit)
                            throws CacheLoaderException

Looks up the SleepyCat transaction associated with the parameter tx. If there is no associated sleepycat transaction, an error is logged.

Parameters:

tx - java transaction used to lookup a SleepyCat transaction

commit - true to commit false to abort

Throws:

CacheLoaderException - if there are problems committing or aborting the transaction

remove

public boolean remove(Object key)
               throws CacheLoaderException

Removes an entry in the store. This implementation delegates to StoredMap.remove(Object)

Parameters:

key - key to remove

Returns:

true if the entry was removed; false if the entry wasn't found.

Throws:

CacheLoaderException - in the event of problems writing to the store

load

public InternalCacheEntry load(Object key)
                        throws CacheLoaderException

Loads an entry mapped to by a given key. Should return null if the entry does not exist. Expired entries are not returned. This implementation delegates to StoredMap.get(Object). If the object is expired, it will not be returned.

Parameters:

key - key

Returns:

an entry

Throws:

CacheLoaderException - in the event of problems reading from source

store

public void store(InternalCacheEntry ed)
           throws CacheLoaderException

Stores an entry This implementation delegates to StoredMap.put(Object, Object)

Parameters:

ed - entry to store

Throws:

CacheLoaderException - in the event of problems writing to the store

clear

public void clear()
           throws CacheLoaderException

Clears all entries in the store This implementation delegates to StoredContainer.clear()

Throws:

CacheLoaderException - in the event of problems writing to the store

loadAll

public Set<InternalCacheEntry> loadAll()
                                throws CacheLoaderException

Loads all entries in the loader. Expired entries are not returned. This implementation returns a Set from StoredMap.values()

Returns:

a set of entries, or an empty set if the loader is emptied.

Throws:

CacheLoaderException - in the event of problems reading from source

load

public Set<InternalCacheEntry> load(int numEntries)
                             throws CacheLoaderException

Description copied from interface: CacheLoader

Loads up to a specific number of entries. There is no guarantee as to order of entries loaded. The set returned would contain up to a maximum of numEntries entries, and no more.

Parameters:

numEntries - maximum number of entries to load

Returns:

a set of entries, which would contain between 0 and numEntries entries.

Throws:

CacheLoaderException

loadAllKeys

public Set<Object> loadAllKeys(Set<Object> keysToExclude)
                        throws CacheLoaderException

Description copied from interface: CacheLoader

Loads a set of all keys, excluding a filter set.

Parameters:

keysToExclude - a set of keys to exclude. An empty set or null will indicate that all keys should be returned.

Returns:

A set containing keys of entries stored. An empty set is returned if the loader is empty.

Throws:

CacheLoaderException

fromStream

public void fromStream(ObjectInput ois)
                throws CacheLoaderException

Writes contents of the stream to the store. Implementations should expect that the stream contains data in an implementation-specific format, typically generated using CacheStore.toStream(java.io.ObjectOutput). While not a requirement, it is recommended that implementations make use of the StreamingMarshaller when dealing with the stream to make use of efficient marshalling.

It is imperative that implementations do not close the stream after finishing with it.

It is also recommended that implementations use their own start and end markers on the stream since other processes may write additional data to the stream after the cache store has written to it. As such, either markers or some other mechanism to prevent the store from reading too much information should be employed when writing to the stream in CacheStore.fromStream(java.io.ObjectInput) to prevent data corruption.

It can be assumed that the stream passed in already performs buffering such that the cache store implementation doesn't have to.

This implementation reads the number of entries to load from the stream, then begins a transaction. During that transaction, the cachestore is cleared and replaced with entries from the stream. If there are any errors during the process, the entire transaction is rolled back. Deadlock handling is not addressed, as there is no means to rollback reads from the input stream.

Parameters:

ois - stream to read from

Throws:

CacheLoaderException - in the event of problems writing to the store

See Also:

toStream(java.io.ObjectOutput)

toStream

public void toStream(ObjectOutput oos)
              throws CacheLoaderException

Writes the current count of cachestore entries followed by a pair of byte[]s corresponding to the SleepyCat binary representation of key value.

This implementation holds a transaction open to ensure that we see no new records added while iterating.

Parameters:

oos - stream to write to

Throws:

CacheLoaderException - in the event of problems reading from the store

purgeInternal

protected void purgeInternal()
                      throws CacheLoaderException

Iterate through StoredMap.entrySet() and remove, if expired.

Specified by:

purgeInternal in class AbstractCacheStore

Throws:

CacheLoaderException

printLicense

public void printLicense()

prints terms of use for Berkeley DB JE