com.isaacrf.epicbitmaprenderer.utils

Class DiskLruCache

java.lang.Object

com.isaacrf.epicbitmaprenderer.utils.DiskLruCache

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public final class DiskLruCache
extends java.lang.Object
implements java.io.Closeable

A cache that uses a bounded amount of space on a filesystem. Each cache entry has a string key and a fixed number of values. Each key must match the regex [A-z0-9%._-]{1,127}. Values are byte sequences, accessible as streams or files. Each value must be between 0 and Integer.MAX_VALUE bytes in length.

The cache stores its data in a directory on the filesystem. This directory must be exclusive to the cache; the cache may delete or overwrite files from its directory. It is an error for multiple processes to use the same cache directory at the same time.

This cache limits the number of bytes that it will store on the filesystem. When the number of stored bytes exceeds the limit, the cache will remove entries in the background until the limit is satisfied. The limit is not strict: the cache may temporarily exceed it while waiting for files to be deleted. The limit does not include filesystem overhead or the cache journal so space-sensitive applications should set a conservative limit.

Clients call edit(java.lang.String) to create or update the values of an entry. An entry may have only one editor at one time; if a value is not available to be edited then edit(java.lang.String) will return null.

• When an entry is being created it is necessary to supply a full set of values; the empty value should be used as a placeholder if necessary.
• When an entry is being edited, it is not necessary to supply data for every value; values default to their previous value.

Every edit(java.lang.String) call must be matched by a call to DiskLruCache.Editor.commit() or DiskLruCache.Editor.abort(). Committing is atomic: a read observes the full set of values as they were before or after the commit, but never a mix of values.

Clients call get(java.lang.String) to read a snapshot of an entry. The read will observe the value at the time that get(java.lang.String) was called. Updates and removals after the call do not impact ongoing reads.

This class is tolerant of some I/O errors. If files are missing from the filesystem, the corresponding entries will be dropped from the cache. If an error occurs while writing a cache value, the edit will fail silently. Callers should handle other problems by catching IOException and responding appropriately.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	DiskLruCache.Editor Edits the values for an entry.
class	DiskLruCache.Snapshot A snapshot of the values for an entry.

Method Summary

Modifier and Type	Method and Description
void	close() Closes this cache.
boolean	containsKey(java.lang.String key) Checks if specified key exists in cache
void	delete() Closes the cache and deletes all of its stored values.
DiskLruCache.Editor	edit(java.lang.String key) Returns an editor for the entry named key, or null if another edit is in progress.
void	flush() Force buffered operations to the filesystem.
DiskLruCache.Snapshot	get(java.lang.String key) Returns a snapshot of the entry named key, or null if it doesn't exist is not currently readable.
android.graphics.Bitmap	getBitmap(java.lang.String key) Obtains a Bitmap object, if possible, from specified key's value
java.io.File	getDirectory() Returns the directory where this cache stores its data.
long	getMaxSize() Returns the maximum number of bytes that this cache should use to store its data.
boolean	isClosed() Returns true if this cache has been closed.
static DiskLruCache	open(java.io.File directory, int appVersion, int valueCount, long maxSize) Opens the cache in directory, creating a cache if none exists there.
static DiskLruCache	open(java.io.File directory, long maxSize) Opens the cache in directory, creating a cache if none exists there.
DiskLruCache.Snapshot	put(java.lang.String key, android.graphics.Bitmap bitmap) Inserts a bitmap into disk cache, along with its distinctive key.
DiskLruCache.Snapshot	put(java.lang.String key, android.graphics.Bitmap bitmap, android.graphics.Bitmap.CompressFormat compressFormat, int compressQuality) Inserts a bitmap into disk cache, along with its distinctive key.
boolean	remove(java.lang.String key) Drops the entry for key if it exists and can be removed.
void	setMaxSize(long maxSize) Changes the maximum number of bytes the cache can store and queues a job to trim the existing store, if necessary.
long	size() Returns the number of bytes currently being used to store the values in this cache.

Methods inherited from class java.lang.Object

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

Method Detail

open

public static DiskLruCache open(java.io.File directory,
                                int appVersion,
                                int valueCount,
                                long maxSize)
                         throws java.io.IOException

Opens the cache in directory, creating a cache if none exists there.

Parameters:

directory - a writable directory

valueCount - the number of values per cache entry. Must be positive.

maxSize - the maximum number of bytes this cache should use to store

Throws:

java.io.IOException - if reading or writing the cache directory fails

open

public static DiskLruCache open(java.io.File directory,
                                long maxSize)
                         throws java.io.IOException

Opens the cache in directory, creating a cache if none exists there. This method version automatically uses appVersion = 1 and valueCount = 1

Parameters:

directory - a writable directory

maxSize - the maximum number of bytes this cache should use to store

Throws:

java.io.IOException - if reading or writing the cache directory fails

get

public DiskLruCache.Snapshot get(java.lang.String key)
                          throws java.io.IOException

Returns a snapshot of the entry named key, or null if it doesn't exist is not currently readable. If a value is returned, it is moved to the head of the LRU queue.

Throws:

java.io.IOException

getBitmap

public android.graphics.Bitmap getBitmap(java.lang.String key)

Obtains a Bitmap object, if possible, from specified key's value

Parameters:

key - Value's identifier

Returns:

Bitmap object

containsKey

public boolean containsKey(java.lang.String key)

Checks if specified key exists in cache

Parameters:

key - Value's identifier

Returns:

True if key is found, False otherwise

edit

public DiskLruCache.Editor edit(java.lang.String key)
                         throws java.io.IOException

Returns an editor for the entry named key, or null if another edit is in progress.

Throws:

java.io.IOException

put

public DiskLruCache.Snapshot put(java.lang.String key,
                                 android.graphics.Bitmap bitmap,
                                 android.graphics.Bitmap.CompressFormat compressFormat,
                                 int compressQuality)

Inserts a bitmap into disk cache, along with its distinctive key.

Parameters:

key - String representing the entry key, to retrieve it later.

bitmap - Bitmap to store on disk cache.

compressFormat - Format to compress the image (JPEG, PNG, etc.)

compressQuality - Compress quality percentage of the image, from 0 to 100.

Returns:

DiskLruCache.Snapshot object with the previous value mapped by key if exists, null otherwise.

put

public DiskLruCache.Snapshot put(java.lang.String key,
                                 android.graphics.Bitmap bitmap)

Inserts a bitmap into disk cache, along with its distinctive key.

NOTE: This method uses JPEG format 100% quality by default when compressing image to store it. To manually specify format and quality of compression, use put(String, Bitmap, Bitmap.CompressFormat, int) instead.

Parameters:

key - String representing the entry key, to retrieve it later.

bitmap - Bitmap to store on disk cache.

Returns:

DiskLruCache.Snapshot object with the previous value mapped by key if exists, null otherwise.

getDirectory

public java.io.File getDirectory()

Returns the directory where this cache stores its data.

getMaxSize

public long getMaxSize()

Returns the maximum number of bytes that this cache should use to store its data.

setMaxSize

public void setMaxSize(long maxSize)

Changes the maximum number of bytes the cache can store and queues a job to trim the existing store, if necessary.

size

public long size()

Returns the number of bytes currently being used to store the values in this cache. This may be greater than the max size if a background deletion is pending.

remove

public boolean remove(java.lang.String key)
               throws java.io.IOException

Drops the entry for key if it exists and can be removed. Entries actively being edited cannot be removed.

Returns:

true if an entry was removed.

Throws:

java.io.IOException

isClosed

public boolean isClosed()

Returns true if this cache has been closed.

flush

public void flush()
           throws java.io.IOException

Force buffered operations to the filesystem.

Throws:

java.io.IOException

close

public void close()
           throws java.io.IOException

Closes this cache. Stored values will remain on the filesystem.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.io.IOException

delete

public void delete()
            throws java.io.IOException

Closes the cache and deletes all of its stored values. This will delete all files in the cache directory including files that weren't created by the cache.

Throws:

java.io.IOException