de.umass.lastfm.cache
Class Cache

java.lang.Object
  de.umass.lastfm.cache.Cache

Direct Known Subclasses:

DatabaseCache, FileSystemCache, MemoryCache

public abstract class Cache
extends Object

The Cache handles storing and loading to a permanent storage for last.fm api requests. This could be a file system or a sql database.

Author:

Janni Kovacs

See Also:

Caller.setCache(Cache), ExpirationPolicy

Constructor Summary

protected

Cache()

Method Summary

abstract void	clear() Clears the cache by effectively removing all cached data.
abstract boolean	contains(String cacheEntryName) Checks if the cache contains an entry with the given name.
static String	createCacheEntryName(String method, Map<String,String> params) Creates a unique entry name string for a request.
long	findExpirationDate(String method, Map<String,String> params) Finds the expiration date, returned as a unix timestamp, for a given method/parameters combination, or -1 if there's no expiration time found in this Cache's ExpirationPolicy. It uses this cache's ExpirationPolicy and the current timestamp to calculate the expiration date.
ExpirationPolicy	getExpirationPolicy() Returns the active ExpirationPolicy
abstract boolean	isExpired(String cacheEntryName) Checks if the specified entry is expired.
abstract InputStream	load(String cacheEntryName) Loads the specified entry from the cache and returns an InputStream to be read from.
abstract void	remove(String cacheEntryName) Removes the specified entry from the cache if available.
void	setExpirationPolicy(ExpirationPolicy expirationPolicy) Sets the active ExpirationPolicy.
static void	setHashCacheEntryNames(boolean hashCacheEntryNames) If hashCacheEntryNames is set to true the createCacheEntryName(java.lang.String, java.util.Map) method will return a hash of the original entry name instead of the name itself.
abstract void	store(String cacheEntryName, InputStream inputStream, long expirationDate) Stores a request in the cache.

Methods inherited from class java.lang.Object

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

Constructor Detail

Cache

protected Cache()

Method Detail

getExpirationPolicy

public ExpirationPolicy getExpirationPolicy()

Returns the active ExpirationPolicy

Returns:

the ExpirationPolicy

setExpirationPolicy

public void setExpirationPolicy(ExpirationPolicy expirationPolicy)

Sets the active ExpirationPolicy.

Parameters:

expirationPolicy - An ExpirationPolicy, not null

contains

public abstract boolean contains(String cacheEntryName)

Checks if the cache contains an entry with the given name.

Parameters:

cacheEntryName - An entry name

Returns:

true if the cache contains this entry

load

public abstract InputStream load(String cacheEntryName)

Loads the specified entry from the cache and returns an InputStream to be read from. Returns null if the cache does not contain the specified cacheEntryName.

Parameters:

cacheEntryName - An entry name

Returns:

an InputStream or null

remove

public abstract void remove(String cacheEntryName)

Removes the specified entry from the cache if available. Does nothing if no such entry is available.

Parameters:

cacheEntryName - An entry name

store

public abstract void store(String cacheEntryName,
                           InputStream inputStream,
                           long expirationDate)

Stores a request in the cache.

Parameters:

cacheEntryName - The entry name to be stored to

inputStream - An InputStream containing the data to be cached

expirationDate - The date of expiration represented in milliseconds since 1.1.1970

isExpired

public abstract boolean isExpired(String cacheEntryName)

Checks if the specified entry is expired.

Parameters:

cacheEntryName - An entry name

Returns:

true if the entry is expired

clear

public abstract void clear()

Clears the cache by effectively removing all cached data.

findExpirationDate

public final long findExpirationDate(String method,
                                     Map<String,String> params)

Finds the expiration date, returned as a unix timestamp, for a given method/parameters combination, or -1 if there's no expiration time found in this Cache's ExpirationPolicy.
It uses this cache's ExpirationPolicy and the current timestamp to calculate the expiration date.

Parameters:

method - The method called

params - The parameters sent

Returns:

The expiration date for this specific API call, or -1 if no expiration date was found

See Also:

ExpirationPolicy.getExpirationTime(String, java.util.Map)

createCacheEntryName

public static String createCacheEntryName(String method,
                                          Map<String,String> params)

Creates a unique entry name string for a request. It consists of the method name and all the parameter names and values concatenated in alphabetical order. It is used to identify cache entries in the backend storage. If hashCacheEntryNames is set to true this method will return a MD5 hash of the generated name.

Parameters:

method - The request method

params - The request parameters

Returns:

a cache entry name

setHashCacheEntryNames

public static void setHashCacheEntryNames(boolean hashCacheEntryNames)

If hashCacheEntryNames is set to true the createCacheEntryName(java.lang.String, java.util.Map) method will return a hash of the original entry name instead of the name itself.

Parameters:

hashCacheEntryNames - true to generate hashes