public final class DiskLruCache
extends java.lang.Object
implements java.io.Closeable, java.io.Flushable
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.
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.
Modifier and Type | Class and Description |
---|---|
class |
DiskLruCache.Editor
Edits the values for an entry.
|
private class |
DiskLruCache.Entry |
class |
DiskLruCache.Snapshot
A snapshot of the values for an entry.
|
Modifier and Type | Field and Description |
---|---|
(package private) static long |
ANY_SEQUENCE_NUMBER |
private int |
appVersion |
private static java.lang.String |
CLEAN |
private java.lang.Runnable |
cleanupRunnable |
(package private) boolean |
closed |
(package private) java.io.File |
directory |
private static java.lang.String |
DIRTY |
private java.util.concurrent.Executor |
executor
Used to run 'cleanupRunnable' for journal rebuilds.
|
(package private) FileSystem |
fileSystem |
(package private) boolean |
hasJournalErrors |
(package private) boolean |
initialized |
(package private) static java.lang.String |
JOURNAL_FILE |
(package private) static java.lang.String |
JOURNAL_FILE_BACKUP |
(package private) static java.lang.String |
JOURNAL_FILE_TEMP |
private java.io.File |
journalFile |
private java.io.File |
journalFileBackup |
private java.io.File |
journalFileTmp |
(package private) okio.BufferedSink |
journalWriter |
(package private) static java.util.regex.Pattern |
LEGAL_KEY_PATTERN |
(package private) java.util.LinkedHashMap<java.lang.String,DiskLruCache.Entry> |
lruEntries |
(package private) static java.lang.String |
MAGIC |
private long |
maxSize |
(package private) boolean |
mostRecentRebuildFailed |
(package private) boolean |
mostRecentTrimFailed |
private long |
nextSequenceNumber
To differentiate between old and current snapshots, each entry is given a sequence number each
time an edit is committed.
|
private static java.lang.String |
READ |
(package private) int |
redundantOpCount |
private static java.lang.String |
REMOVE |
private long |
size |
(package private) int |
valueCount |
(package private) static java.lang.String |
VERSION_1 |
Constructor and Description |
---|
DiskLruCache(FileSystem fileSystem,
java.io.File directory,
int appVersion,
int valueCount,
long maxSize,
java.util.concurrent.Executor executor) |
Modifier and Type | Method and Description |
---|---|
private void |
checkNotClosed() |
void |
close()
Closes this cache.
|
(package private) void |
completeEdit(DiskLruCache.Editor editor,
boolean success) |
static DiskLruCache |
create(FileSystem fileSystem,
java.io.File directory,
int appVersion,
int valueCount,
long maxSize)
Create a cache which will reside in
directory . |
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. |
(package private) DiskLruCache.Editor |
edit(java.lang.String key,
long expectedSequenceNumber) |
void |
evictAll()
Deletes all stored values from the cache.
|
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. |
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.
|
void |
initialize() |
boolean |
isClosed()
Returns true if this cache has been closed.
|
(package private) boolean |
journalRebuildRequired()
We only rebuild the journal when it will halve the size of the journal and eliminate at least
2000 ops.
|
private okio.BufferedSink |
newJournalWriter() |
private void |
processJournal()
Computes the initial size and collects garbage as a part of opening the cache.
|
private void |
readJournal() |
private void |
readJournalLine(java.lang.String line) |
(package private) void |
rebuildJournal()
Creates a new journal that omits redundant information.
|
boolean |
remove(java.lang.String key)
Drops the entry for
key if it exists and can be removed. |
(package private) boolean |
removeEntry(DiskLruCache.Entry entry) |
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.
|
java.util.Iterator<DiskLruCache.Snapshot> |
snapshots()
Returns an iterator over the cache's current entries.
|
(package private) void |
trimToSize() |
private void |
validateKey(java.lang.String key) |
static final java.lang.String JOURNAL_FILE
static final java.lang.String JOURNAL_FILE_TEMP
static final java.lang.String JOURNAL_FILE_BACKUP
static final java.lang.String MAGIC
static final java.lang.String VERSION_1
static final long ANY_SEQUENCE_NUMBER
static final java.util.regex.Pattern LEGAL_KEY_PATTERN
private static final java.lang.String CLEAN
private static final java.lang.String DIRTY
private static final java.lang.String REMOVE
private static final java.lang.String READ
final FileSystem fileSystem
final java.io.File directory
private final java.io.File journalFile
private final java.io.File journalFileTmp
private final java.io.File journalFileBackup
private final int appVersion
private long maxSize
final int valueCount
private long size
okio.BufferedSink journalWriter
final java.util.LinkedHashMap<java.lang.String,DiskLruCache.Entry> lruEntries
int redundantOpCount
boolean hasJournalErrors
boolean initialized
boolean closed
boolean mostRecentTrimFailed
boolean mostRecentRebuildFailed
private long nextSequenceNumber
private final java.util.concurrent.Executor executor
private final java.lang.Runnable cleanupRunnable
DiskLruCache(FileSystem fileSystem, java.io.File directory, int appVersion, int valueCount, long maxSize, java.util.concurrent.Executor executor)
public void initialize() throws java.io.IOException
java.io.IOException
public static DiskLruCache create(FileSystem fileSystem, java.io.File directory, int appVersion, int valueCount, long maxSize)
directory
. This cache is lazily initialized on
first access and will be created if it does not exist.directory
- a writable directoryvalueCount
- the number of values per cache entry. Must be positive.maxSize
- the maximum number of bytes this cache should use to storeprivate void readJournal() throws java.io.IOException
java.io.IOException
private okio.BufferedSink newJournalWriter() throws java.io.FileNotFoundException
java.io.FileNotFoundException
private void readJournalLine(java.lang.String line) throws java.io.IOException
java.io.IOException
private void processJournal() throws java.io.IOException
java.io.IOException
void rebuildJournal() throws java.io.IOException
java.io.IOException
public DiskLruCache.Snapshot get(java.lang.String key) throws java.io.IOException
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.java.io.IOException
@Nullable public DiskLruCache.Editor edit(java.lang.String key) throws java.io.IOException
key
, or null if another edit is in progress.java.io.IOException
DiskLruCache.Editor edit(java.lang.String key, long expectedSequenceNumber) throws java.io.IOException
java.io.IOException
public java.io.File getDirectory()
public long getMaxSize()
public void setMaxSize(long maxSize)
public long size() throws java.io.IOException
java.io.IOException
void completeEdit(DiskLruCache.Editor editor, boolean success) throws java.io.IOException
java.io.IOException
boolean journalRebuildRequired()
public boolean remove(java.lang.String key) throws java.io.IOException
key
if it exists and can be removed. If the entry for key
is currently being edited, that edit will complete normally but its value will not be stored.java.io.IOException
boolean removeEntry(DiskLruCache.Entry entry) throws java.io.IOException
java.io.IOException
public boolean isClosed()
private void checkNotClosed()
public void flush() throws java.io.IOException
flush
in interface java.io.Flushable
java.io.IOException
public void close() throws java.io.IOException
close
in interface java.io.Closeable
close
in interface java.lang.AutoCloseable
java.io.IOException
void trimToSize() throws java.io.IOException
java.io.IOException
public void delete() throws java.io.IOException
java.io.IOException
public void evictAll() throws java.io.IOException
java.io.IOException
private void validateKey(java.lang.String key)
public java.util.Iterator<DiskLruCache.Snapshot> snapshots() throws java.io.IOException
ConcurrentModificationException
, but if new entries are added while iterating, those new
entries will not be returned by the iterator. If existing entries are removed during iteration,
they will be absent (unless they were already returned).
If there are I/O problems during iteration, this iterator fails silently. For example, if the hosting filesystem becomes unreachable, the iterator will omit elements rather than throwing exceptions.
The caller must close
each snapshot returned by
Iterator.next()
. Failing to do so leaks open files!
The returned iterator supports Iterator.remove()
.
java.io.IOException