org.jboss.cache.loader
Class FileCacheLoader

java.lang.Object
  org.jboss.cache.loader.AbstractCacheLoader
      org.jboss.cache.loader.FileCacheLoader

All Implemented Interfaces:

CacheLoader

@ThreadSafe
public class FileCacheLoader
extends AbstractCacheLoader

Simple file-based CacheLoader implementation. Nodes are directories, attributes of a node is a file in the directory

The FileCacheLoader has some severe limitations which restrict its use in a production environment, or if used in such an environment, it should be used with due care and sufficient understanding of these limitations.

• Due to the way the FileCacheLoader represents a tree structure on disk (directories and files) traversal is inefficient for deep trees.
• Usage on shared filesystems like NFS, Windows shares, etc. should be avoided as these do not implement proper file locking and can cause data corruption.
• Usage with an isolation level of NONE can cause corrupt writes as multiple threads attempt to write to the same file.
• File systems are inherently not transactional, so when attempting to use your cache in a transactional context, failures when writing to the file (which happens during the commit phase) cannot be recovered.

As a rule of thumb, it is recommended that the FileCacheLoader not be used in a highly concurrent, transactional or stressful environment, and its use is restricted to testing.

In terms of concurrency, file systems are notoriously inconsistent in their implementations of concurrent locks. To get around this and to meet the thread safety contracts set out in CacheLoader, this implementation uses a StripedLock

Version:

$Id: FileCacheLoader.java 7006 2008-10-23 14:33:36Z manik.surtani@jboss.com $

Author:

Bela Ban, Galder Zamarreno, Manik Surtani

Field Summary

static String	DATA CacheImpl data file.
static String	DIR_SUFFIX CacheImpl directory suffix.
static Pattern	FQN_PATTERN For fqn, check '*' '<' '>' '|' '"' '?'
protected StripedLock	lock
static Pattern	PATH_PATTERN For full path, check '*' '<' '>' '|' '"' '?'

Fields inherited from class org.jboss.cache.loader.AbstractCacheLoader

buddyFqnTransformer, cache, regionManager, transactions

Constructor Summary

FileCacheLoader()

Method Summary

void	create() Lifecycle method, called when the cache loader is created.
protected void	doMarshall(Fqn fqn, Object toMarshall)
protected Object	doUnmarshall(Fqn fqn, Object fromFile)
boolean	exists(Fqn fqn) Returns true if the CacheLoader has a node with a Fqn.
Map	get(Fqn fqn) Returns all keys and values from the persistent store, given a Fqn
CacheLoaderConfig.IndividualCacheLoaderConfig	getConfig() Gets the configuration.
Set<String>	getChildrenNames(Fqn fqn) Returns a set of children node names.
protected boolean	isCharacterPortableLocation(String fileAbsolutePath)
protected boolean	isCharacterPortableTree(Fqn fqn)
protected boolean	isLengthPortablePath(String absoluteFqnPath)
protected Map	loadAttributes(Fqn fqn)
void	put(Fqn fqn, Map attributes) Puts all entries of the map into the existing map of the given node, overwriting existing keys, but not clearing the existing map before insertion.
void	put(Fqn fqn, Map attributes, boolean erase)
Object	put(Fqn fqn, Object key, Object value) Puts a key and value into the attribute map of a given node.
void	remove(Fqn fqn) Removes the given node and all its subnodes, does nothing if the node does not exist.
Object	remove(Fqn fqn, Object key) Removes the given key and value from the attributes of the given node.
void	removeData(Fqn fqn) Removes all attributes from a given node, but doesn't delete the node itself or any subnodes.
void	setConfig(CacheLoaderConfig.IndividualCacheLoaderConfig base) Sets the configuration.
protected void	storeAttributes(Fqn fqn, Map attrs)

Methods inherited from class org.jboss.cache.loader.AbstractCacheLoader

commit, destroy, getMarshaller, getNodeDataList, loadEntireState, loadState, loadStateHelper, move, prepare, put, regionAwareMarshall, regionAwareUnmarshall, rollback, setCache, setRegionManager, start, stop, storeEntireState, storeState, storeStateHelper

Methods inherited from class java.lang.Object

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

Field Detail

lock

protected final StripedLock lock

DATA

public static final String DATA

CacheImpl data file.

See Also:

Constant Field Values

DIR_SUFFIX

public static final String DIR_SUFFIX

CacheImpl directory suffix.

See Also:

Constant Field Values

PATH_PATTERN

public static final Pattern PATH_PATTERN

For full path, check '*' '<' '>' '|' '"' '?' Regex: [\*<>|"?]

FQN_PATTERN

public static final Pattern FQN_PATTERN

For fqn, check '*' '<' '>' '|' '"' '?' and also '\' '/' and ':'

Constructor Detail

FileCacheLoader

public FileCacheLoader()

Method Detail

setConfig

public void setConfig(CacheLoaderConfig.IndividualCacheLoaderConfig base)

Description copied from interface: CacheLoader

Sets the configuration. This is called before CacheLoader.create() and CacheLoader.start().

Parameters:

base - May be an instance of the CacheLoaderConfig.IndividualCacheLoaderConfig base class, in which case the cache loader should use the PluggableConfigurationComponent.getProperties() method to find configuration information. Alternatively, may be a type-specific subclass of CacheLoaderConfig.IndividualCacheLoaderConfig, if there is one.

getConfig

public CacheLoaderConfig.IndividualCacheLoaderConfig getConfig()

Description copied from interface: CacheLoader

Gets the configuration.

Returns:

the configuration, represented by a CacheLoaderConfig.IndividualCacheLoaderConfig object.

create

public void create()
            throws Exception

Description copied from interface: CacheLoader

Lifecycle method, called when the cache loader is created.

Specified by:

create in interface CacheLoader

Overrides:

create in class AbstractCacheLoader

Throws:

Exception

getChildrenNames

public Set<String> getChildrenNames(Fqn fqn)
                             throws Exception

Description copied from interface: CacheLoader

Returns a set of children node names. All names are relative to this parent Fqn. Returns null if the named node is not found or there are no children. The returned set must not be modifiable. Implementors can use Collections.unmodifiableSet(java.util.Set) to make the set unmodifiable.

Implementors may impose restrictions on the contents of an Fqn (such as Strings-only) and as such, indirectly impose the same restriction on the contents of a Set returned by getChildrenNames().

Parameters:

fqn - The Fqn of the parent

Returns:

Set a set of children. Returns null if no children nodes are present, or the parent is not present

Throws:

Exception

get

public Map get(Fqn fqn)
        throws Exception

Description copied from interface: CacheLoader

Returns all keys and values from the persistent store, given a Fqn

Parameters:

fqn - the Fqn to search for.

Returns:

Map keys and values for the given node. Returns null if the node is not found. If the node is found but has no attributes, this method returns an empty Map.

Throws:

Exception

exists

public boolean exists(Fqn fqn)
               throws Exception

Description copied from interface: CacheLoader

Returns true if the CacheLoader has a node with a Fqn.

Returns:

true if node exists, false otherwise

Throws:

Exception

put

public Object put(Fqn fqn,
                  Object key,
                  Object value)
           throws Exception

Description copied from interface: CacheLoader

Puts a key and value into the attribute map of a given node. If the node does not exist, all parent nodes from the root down are created automatically. Returns the old value.

Throws:

Exception

put

public void put(Fqn fqn,
                Map attributes)
         throws Exception

Description copied from interface: CacheLoader

Puts all entries of the map into the existing map of the given node, overwriting existing keys, but not clearing the existing map before insertion. This is the same behavior as Map.putAll(java.util.Map). If the node does not exist, all parent nodes from the root down are created automatically

Note since 3.0, as an optimization, this method will require a definitive attribute map and not just a subset. This will allow cache loader implementations to overwrite rather than merge, if that is deemed more efficient. This will not break backward compatibility since performing a merge will not cause any loss of data even though it is an unnecessary step.

Parameters:

fqn - The fully qualified name of the node

attributes - A Map of attributes. Can be null

Throws:

Exception

put

public void put(Fqn fqn,
                Map attributes,
                boolean erase)
         throws Exception

Overrides:

put in class AbstractCacheLoader

Throws:

Exception

remove

public Object remove(Fqn fqn,
                     Object key)
              throws Exception

Description copied from interface: CacheLoader

Removes the given key and value from the attributes of the given node. Does nothing if the node doesn't exist Returns the removed value.

Throws:

Exception

remove

public void remove(Fqn fqn)
            throws Exception

Description copied from interface: CacheLoader

Removes the given node and all its subnodes, does nothing if the node does not exist.

Parameters:

fqn - the Fqn of the node

Throws:

Exception

removeData

public void removeData(Fqn fqn)
                throws Exception

Description copied from interface: CacheLoader

Removes all attributes from a given node, but doesn't delete the node itself or any subnodes.

Parameters:

fqn - the Fqn of the node

Throws:

Exception

loadAttributes

protected Map loadAttributes(Fqn fqn)
                      throws Exception

Throws:

Exception

storeAttributes

protected void storeAttributes(Fqn fqn,
                               Map attrs)
                        throws Exception

Throws:

Exception

doMarshall

protected void doMarshall(Fqn fqn,
                          Object toMarshall)
                   throws Exception

Overrides:

doMarshall in class AbstractCacheLoader

Throws:

Exception

doUnmarshall

protected Object doUnmarshall(Fqn fqn,
                              Object fromFile)
                       throws Exception

Overrides:

doUnmarshall in class AbstractCacheLoader

Throws:

Exception

isCharacterPortableLocation

protected boolean isCharacterPortableLocation(String fileAbsolutePath)

isCharacterPortableTree

protected boolean isCharacterPortableTree(Fqn fqn)

isLengthPortablePath

protected boolean isLengthPortablePath(String absoluteFqnPath)