sk.baka.ambient.commons
Class AbstractFileStorage

java.lang.Object
  sk.baka.ambient.commons.AbstractFileStorage

Direct Known Subclasses:

CoverCache, LRCStorage, ObjectStorage

public class AbstractFileStorage
extends Object

An abstract file cache, stores files into android application private directory. Thread-safe. Essentially a singleton, there must be at most one instance.

Author:

Martin Vysny

Field Summary

protected long	maxStorageSize Maximum storage size, in bytes.
protected Map<String,File>	theCache A read-only view of the cache.

Constructor Summary

AbstractFileStorage(String contentDesc, String... ext)
Creates new cache instance.

Method Summary

protected void	cleanup() Cleans up old files.
void	close() Closes the cache object, stopping any pending download operations.
protected FileOutputStream	createFile(String name, String ext) Registers a file to the cache.
protected void	fetchFileAsync(Object fetchInfo) Attempts to asynchronously download a file.
protected File	getCacheFile(String name) Retrieves cached file.
protected File	getCacheFileNull(String name) Retrieves cached file.
protected File	getFile(Object fetchInfo) Fetches a file.
protected String[]	getFilenameAndExt(URL url, Object fetchInfo) Retrieves target file name.
Set<String>	getNames() Returns a list of names of objects cached in this storage.
boolean	isFull() Returns true if this storage is full.
protected boolean	isProceedWithDownload(Object fetchInfo) Invoked before the download process starts.
protected void	onFileDownloaded(URL url, Object fetchInfo, boolean success) The file was downloaded and is already registered in the storage.
void	purge() Purges the cache - removes all cached files.
protected void	registerFile(String name, String ext) Registers a file to the cache.
protected void	removeFile(File file) Removes a file from the cache.
void	setMaxStorageSize(long maxCacheSize) Sets maximum cache size, removing files if required.
protected boolean	supportsExtension(String ext) Checks if this storage supports given extension.
protected URL	toURL(Object fetchInfo) Converts given fetch info to an URL object.

Methods inherited from class java.lang.Object

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

Field Detail

theCache

protected final Map<String,File> theCache

A read-only view of the cache.

maxStorageSize

protected long maxStorageSize

Maximum storage size, in bytes.

Constructor Detail

AbstractFileStorage

public AbstractFileStorage(String contentDesc,
                           String... ext)

Creates new cache instance.

Parameters:

ext - a list of ".whatever" strings - valid extensions.

contentDesc - describes content which this storage holds. Should form a correct sentence with "Downloading " + contentDesc + " failed".

Method Detail

supportsExtension

protected final boolean supportsExtension(String ext)

Checks if this storage supports given extension.

Parameters:

ext - the ".extension" format

Returns:

true if this storage supports such extensions, false otherwise.

setMaxStorageSize

public final void setMaxStorageSize(long maxCacheSize)

Sets maximum cache size, removing files if required.

Parameters:

maxCacheSize - Maximum cache size, in bytes.

isFull

public final boolean isFull()

Returns true if this storage is full.

Returns:

true if the size of all files in this storage exceeds maximum storage size.

cleanup

protected void cleanup()

Cleans up old files. Superclass should implement a strategy to pick and delete obsolete files. Default implementation does nothing. Called in setMaxStorageSize(long) method.

createFile

protected final FileOutputStream createFile(String name,
                                            String ext)
                                     throws FileNotFoundException

Registers a file to the cache. The file must exist. The file name must be passable to the Context.getFileStreamPath(String) method.

Parameters:

name - the file name, without the extension

ext - the ".ext" string.

Returns:

the name the file is registered under.

Throws:

FileNotFoundException - if the file does not exist.

registerFile

protected final void registerFile(String name,
                                  String ext)

Registers a file to the cache. The file must have been created using createFile(String, String).

Parameters:

name - the file name, without the extension

ext - the ".ext" string.

removeFile

protected final void removeFile(File file)

Removes a file from the cache. The file must exist. The file name must be passable to the Context.getFileStreamPath(String) method.

Parameters:

file - the file

getCacheFile

protected final File getCacheFile(String name)

Retrieves cached file.

Parameters:

name - the name

Returns:

File

getCacheFileNull

protected final File getCacheFileNull(String name)

Retrieves cached file. May return null if no such file exists.

Parameters:

name - the name

Returns:

File

purge

public final void purge()

Purges the cache - removes all cached files.

getNames

public Set<String> getNames()

Returns a list of names of objects cached in this storage.

Returns:

the storage.

fetchFileAsync

protected final void fetchFileAsync(Object fetchInfo)

Attempts to asynchronously download a file. Does nothing if the file is already scheduled to be downloaded.

Parameters:

fetchInfo - contains information on how to fetch the file. toURL(Object) is called asynchronously to convert the fetch info object to an URL. This object must comply to the contract imposed on a Map key.

toURL

protected URL toURL(Object fetchInfo)
             throws IOException

Converts given fetch info to an URL object. Default implementation throws UnsupportedOperationException. Must be thread-safe as it is not invoked from a Handler thread.

Parameters:

fetchInfo - the fetch info object, never null.

Returns:

URL which is used to download the file contents. If null then this download is aborted.

Throws:

IOException - if i/o error occurs

isProceedWithDownload

protected boolean isProceedWithDownload(Object fetchInfo)

Invoked before the download process starts. Must be thread-safe as it is not invoked from a Handler thread.

Parameters:

fetchInfo - the fetch info object, never null.

Returns:

if false then this download is aborted.

close

public void close()

Closes the cache object, stopping any pending download operations.

onFileDownloaded

protected void onFileDownloaded(URL url,
                                Object fetchInfo,
                                boolean success)

The file was downloaded and is already registered in the storage. Default implementation does nothing. Must be thread-safe as it is not invoked from a Handler thread.

Parameters:

url - the source URL

fetchInfo - the fetch info object

success - if true then the file is available in the cache. If false then the download process was aborted ( toURL(Object) returned null).

getFilenameAndExt

protected String[] getFilenameAndExt(URL url,
                                     Object fetchInfo)

Retrieves target file name. Default implementation throws UnsupportedOperationException. Must be thread-safe as it is not invoked from a Handler thread.

Parameters:

url - the source URL. May be null - in this case the extension is not needed and returned extension may be null or the result may contain only the name.

fetchInfo - the fetch info object

Returns:

array containing two items - filename and extension. The extension must start with a dot. If null is returned then the object is not downloadable nor storable into the storage.

getFile

protected File getFile(Object fetchInfo)

Fetches a file. Attempts to fetch it from the internet if the file is not found and we are online - in this case a background thread is run and the method returns null.

Parameters:

fetchInfo - the fetch info object

Returns:

file or null if we are unable to provide any file now.