Android—DiskLruCache基本用法与源码解析
DiskLruCache与LruCache都实现了Lru缓存功能，两者都用于图片的三重缓存中。
LruCache将图片保存在内存，存取速度较快，退出APP后缓存会失效；而DiskLruCache将图片保存在磁盘中，下次进入应用后缓存依旧存在，它的存取速度相比LruCache会慢上一些。
DiskLruCache最大的特点就是持久化存储，所有的缓存以文件的形式存在。在用户进入APP时，它根据日志文件将DiskLruCache恢复到用户上次退出时的情况，日志文件journal保存每个文件的下载、访问和移除的信息，在恢复缓存时逐行读取日志并检查文件来恢复缓存。
一、基本介绍
1.1 官方介绍
DiskLruCache是一种存在于文件系统上的缓存，用户可以为它的存储空间设定一个最大值。每个缓存实体被称为Entry，它有一个String类型的Key，一个Key对应特定数量的Values，每个Key必须满足[a-z0-9_-]{1,64}这个正则表达式。缓存的Value是字节流，可以通过Stream或者文件访问，每个文件的字节大小需要在(0, Integer.MAX_VALUE)之间。
缓存被保存在文件系统的一个文件夹内，该文件夹必须是当前DiskLruCache专用的，DiskLruCache可能会对该文件夹内的文件删除或重写。多进程同时使用相同的缓存文件夹会引发错误。
DiskLruCache对保存在文件系统中的总字节大小设定了最大值，当大小超过最大值时会在后台移除部分缓存实体直到缓存大小达标。该最大值不是严格的，当DiskLruCache在删除Entry时，缓存的整体大小可能会临时超过预设的最大值。该最大值不包括文件系统开销和journal日志文件，因此空间敏感型应用可以设置一个保守的最大值。
用户调用edit()方法来创建或者更改一个Entry的Value，一个Entry在同一时刻只能拥有一个Editor，如果一个Value无法被修改，那么edit()方法会返回null。当一个Entry被创建时，需要为该Entry提供完整的Value集合，如有必要，应该使用空的Value作为占位符。当一个Entry被修改的时候，没有必要对所有的Value都设置新的值，Value默认使用原先的值。
每一个edit()方法调用都与一个commit()或者abort()调用配对，commit操作是原子的，一个Read操作会观察commit前后的完整Value集合。用户通过get()方法读取一个Entry的快照，此时读取到的是get()方法被调用时的值，之后的更新操作并不会影响正在进行中的Read操作。
DiskLruCache可以容忍IO错误，如果某些缓存文件消失，对应的Entry会被删除。如果在写一个缓存Value时出现了一个错误，edit会静默失败。对于其他错误，调用方需要捕获IOException并处理。
1.2 关于日志文件journal
来看一个官方提供的日志文件示例。
libcore.io.DiskLruCache
1
100
2
CLEAN 3400330d1dfc7f3f7f4b8d4d803dfcf6 832 21054
DIRTY 335c4c6028171cfddfbaae1a9c313c52
CLEAN 335c4c6028171cfddfbaae1a9c313c52 3934 2342
REMOVE 335c4c6028171cfddfbaae1a9c313c52
DIRTY 1ab96a171faeeee38496d8b330771a7a
CLEAN 1ab96a171faeeee38496d8b330771a7a 1600 234
READ 335c4c6028171cfddfbaae1a9c313c52
READ 3400330d1dfc7f3f7f4b8d4d803dfcf6
日志文件第一行是固定字符串，表示使用的是DiskLruCache；第二行表示当前缓存的版本号，恒定为1；第三行表示应用的版本号；第四行为valueCount，这里为2，表示一个Entry中有两个文件。
接下来的每一行都代表一个Entry的记录，每一行包括：状态、Key以及缓存文件的大小。下面来看各个状态的含义：
① DIRTY: 该状态表示一个Entry正在被创建或正在被更新，任意一个成功的DIRTY操作后面都会有一个CLEAN或REMOVE操作。如果一个DIRTY操作后面没有CLEAN或者REMOVE操作，那就表示这是一个临时文件，应该将其删除。
② CLEAN: 该状态表示一个缓存Entry已经被成功发布了并且可以读取，该行后面会有每个Value的大小。
③ READ: 在LRU缓存中被读取了。
④ REMOVE: 表示被删除的缓存Entry。
在对缓存进行操作时，DiskLruCache会在journal日志后面追加记录，日志文件会偶尔删除多余的行数进行压缩，在压缩时会使用一个临时的日志文件"journal.tmp"，如果打开缓存时该临时文件存在，那么应该将其删除。
二、基本用法
DiskLruCache通过静态方法open(File directory, int appVersion, int valueCount, long maxSize)创建实例。directory表示文件的目录，开发人员在调用open(...)方法前应该确保directory目录存在；appVersion表示应用的版本号，如果版本号更新，DiskLruCache会清除之前的缓存；valueCount表示一个key最多可以对应多少个文件；maxSize表示缓存的最大大小。
private void initDiskLruCache() {
try {
String dir = getExternalCacheDir() + File.separator + "disk_lru";
File file = new File(dir);
if (!file.exists()) {
file.mkdirs();
}
mDiskLruCache = DiskLruCache.open(file, 1, 1, 10 * 1024 * 1024);
} catch (IOException e) {
e.printStackTrace();
}
}
DiskLruCache的读取都是通过流进行操作的，保存数据时通过Editor得到Entry对应index文件的输出流，通过该输出流写入文件。downloadFile(...)方法就是读取url的InputStream输出到OutputStream中，该方法不再赘述。
private void saveFile(String key, String url) {
try {
DiskLruCache.Editor editor = mDiskLruCache.edit(key);
if (editor != null) {
OutputStream outputStream = editor.newOutputStream(0);
if (downloadFile(url, outputStream)) {
editor.commit();
} else {
editor.abort();
}
}
mDiskLruCache.flush();
} catch (IOException e) {
e.printStackTrace();
}
}
读取文件时得到该Key对应的缓存快照，然后得到输入流即可。
private void getInputStream(String key) {
InputStream in = null;
try {
DiskLruCache.Snapshot snapShot = mDiskLruCache.get(key);
if (snapShot != null) {
in= snapShot.getInputStream(0);
}
} catch (IOException e) {
e.printStackTrace();
}
return in;
}
三、源码解析
3.1 初始化
DiskLruCache通过open()方法新建一个实例，大概流程为：首先处理日志文件，判断是否存在可用的日志文件，如果存在就读取日志到内存，如果不存在就新建一个日志文件。
public static DiskLruCache open(File directory, int appVersion, int valueCount, long maxSize)
throws IOException {
// 如果存在备份日志文件，则使用它
File backupFile = new File(directory, JOURNAL_FILE_BACKUP);
if (backupFile.exists()) {
File journalFile = new File(directory, JOURNAL_FILE);
// 如果存在正式的日志文件，则将备份日志文件删除
if (journalFile.exists()) {
backupFile.delete();
} else {
renameTo(backupFile, journalFile, false);
}
}
// 首先尝试读取日志文件
DiskLruCache cache = new DiskLruCache(directory, appVersion, valueCount, maxSize);
if (cache.journalFile.exists()) {
try {
cache.readJournal();
cache.processJournal();
cache.journalWriter = new BufferedWriter(
new OutputStreamWriter(new FileOutputStream(cache.journalFile, true), Util.US_ASCII));
return cache;
} catch (IOException journalIsCorrupt) {
cache.delete();
}
}
// 此时日志文件不存在或读取出错，新建一个DiskLruCache实例
directory.mkdirs();
cache = new DiskLruCache(directory, appVersion, valueCount, maxSize);
cache.rebuildJournal();
return cache;
}
DiskLruCache的关键就是日志文件，这里主要关注日志文件的读取过程，来看readJournal()和processJournal()这两个方法。
readJournal()方法其实就是通过readJournalLine(reader.readLine())方法读取日志文件中的每一行，最终会读取到lruEntries中，lruEntries是DiskLruCache在内存中的表现形式。
private void readJournal() throws IOException {
StrictLineReader reader = new StrictLineReader(new FileInputStream(journalFile), Util.US_ASCII);
try {
// ......
int lineCount = 0;
while (true) {
try {
readJournalLine(reader.readLine());
lineCount++;
} catch (EOFException endOfJournal) {
break;
}
}
redundantOpCount = lineCount - lruEntries.size();
} finally {
Util.closeQuietly(reader);
}
}
先来看readJournalLine(String line)方法，该方法用于读取每一行日志。上面提到，日志文件的每一行都是DIRTY、CLEAN、READ或REMOVE四种行为之一，那么该方法就需要对这4中情况分别处理。
private void readJournalLine(String line) throws IOException {
int firstSpace = line.indexOf(' ');
if (firstSpace == -1) {
throw new IOException("unexpected journal line: " + line);
}
int keyBegin = firstSpace + 1;
int secondSpace = line.indexOf(' ', keyBegin);
final String key;
if (secondSpace == -1) {
key = line.substring(keyBegin);
// 如果是REMOVE，则将该key代表的缓存从lruEntries中移除
if (firstSpace == REMOVE.length() && line.startsWith(REMOVE)) {
lruEntries.remove(key);
return;
}
} else {
key = line.substring(keyBegin, secondSpace);
}
Entry entry = lruEntries.get(key);
if (entry == null) {
entry = new Entry(key);
lruEntries.put(key, entry);
}
// 如果是CLEAN、DIRTY或READ
if (secondSpace != -1 && firstSpace == CLEAN.length() && line.startsWith(CLEAN)) {
String[] parts = line.substring(secondSpace + 1).split(" ");
entry.readable = true;
entry.currentEditor = null;
entry.setLengths(parts);
} else if (secondSpace == -1 && firstSpace == DIRTY.length() && line.startsWith(DIRTY)) {
entry.currentEditor = new Editor(entry);
} else if (secondSpace == -1 && firstSpace == READ.length() && line.startsWith(READ)) {
// This work was already done by calling lruEntries.get().
} else {
throw new IOException("unexpected journal line: " + line);
}
}
阅读代码发现，readJournalLine(String line)首先取出该行记录的key，然后根据该记录是否为REMOVE进行不同的操作，如果是REMOVE，则将该key的缓存从lruEntries中移除。
如果不是REMOVE，说明该key存在一个对应的缓存实体Entry，则先新建一个Entry并添加到lruEntries中。之后再判断日志的类型，如果日志是CLEAN，代表该文件已经保存完毕了，将currentEditor设置为null；如果日志是DIRTY，代表文件没有保存完毕，为其currentEditor新建一个Editor。
为什么要这么做呢？之前提到，保存一个文件时会先写入DIRTY日志，保存成功后再写入CLEAN日志，一般来说这两条日志会成对出现。这里的currentEditor相当于一个标志位，如果为空，表示文件完整，如果不为空，表示该文件是临时文件。
再来看processJournal()方法，该方法主要用于统计缓存文件的总体大小，并删除脏文件。
private void processJournal() throws IOException {
deleteIfExists(journalFileTmp);
for (Iterator<Entry> i = lruEntries.values().iterator(); i.hasNext(); ) {
Entry entry = i.next();
if (entry.currentEditor == null) {
for (int t = 0; t < valueCount; t++) {
size += entry.lengths[t];
}
} else {·
entry.currentEditor = null;
for (int t = 0; t < valueCount; t++) {
deleteIfExists(entry.getCleanFile(t));
deleteIfExists(entry.getDirtyFile(t));
}
i.remove();
}
}
}
private static void deleteIfExists(File file) throws IOException {
if (file.exists() && !file.delete()) {
throw new IOException();
}
}
3.2 写缓存
写缓存的时候需要先通过edit(String key)方法新建一个Editor，然后将数据写入Editor的输出流中，最后成功则调用Editor.commit()，失败则调用Editor.abort()。
先从edit(String key)方法开始，方法取出当前key对应的缓存Entry，如果Entry不存在则新建并添加到lruEntries中，如果存在且entry.currentEditor不为空，表示Entry正在进行缓存编辑。随后新建一个Editor，并在日志文件中输出一行DIRTY日志表示开始编辑缓存文件。
public Editor edit(String key) throws IOException {
return edit(key, ANY_SEQUENCE_NUMBER);
}
private synchronized Editor edit(String key, long expectedSequenceNumber) throws IOException {
checkNotClosed();
validateKey(key);
Entry entry = lruEntries.get(key);
if (expectedSequenceNumber != ANY_SEQUENCE_NUMBER && (entry == null
|| entry.sequenceNumber != expectedSequenceNumber)) {
return null; // Snapshot已经过期
}
if (entry == null) {
entry = new Entry(key);
lruEntries.put(key, entry);
} else if (entry.currentEditor != null) {
return null; // Another edit is in progress.
}
Editor editor = new Editor(entry);
entry.currentEditor = editor;
// 为了防止文件泄露，在创建文件前，将日志立即写入journal中
journalWriter.write(DIRTY + ' ' + key + '\n');
journalWriter.flush();
return editor;
}
随后通过Editor新建一个输出流，该方法返回一个没有buffer的输出流，参数的index表示该key的第几个缓存文件。如果该输出流在写入时发生错误，这次编辑会在commit()方法被调用的时候终止。该方法返回的输出流是FaultHidingOutputStream，该输出流不抛出IO异常，但是通过标志位标记本次IO操作出错。
public OutputStream newOutputStream(int index) throws IOException {
synchronized (DiskLruCache.this) {
if (entry.currentEditor != this) {
throw new IllegalStateException();
}
if (!entry.readable) {
written[index] = true;
}
// dirtyFile是后缀名为.tmp的临时文件
File dirtyFile = entry.getDirtyFile(index);
FileOutputStream outputStream;
try {
outputStream = new FileOutputStream(dirtyFile);
} catch (FileNotFoundException e) {
// Attempt to recreate the cache directory.
directory.mkdirs();
try {
outputStream = new FileOutputStream(dirtyFile);
} catch (FileNotFoundException e2) {
// We are unable to recover. Silently eat the writes.
return NULL_OUTPUT_STREAM;
}
}
return new FaultHidingOutputStream(outputStream);
}
}
得到OutputStream后通过它来保存文件，成功后调用Editor.commit()，失败后调用Editor.abort()方法，代码如下。
之前提到newOutputStream(int index)返回的输出流是FaultHidingOutputStream，它捕获所有的IO异常而不是抛出，如果它捕获到IO异常就会将hasErrors设置为true。不管保存文件成功或失败，最终调用的都是completeEdit(Editor editor, boolean success)方法。
public void commit() throws IOException {
if (hasErrors) {
completeEdit(this, false);
remove(entry.key);
} else {
completeEdit(this, true);
}
committed = true;
}
public void abort() throws IOException {
completeEdit(this, false);
}
来看completeEdit(Editor editor, boolean success)方法，该方法首先根据文件写入是否成功来重命名或者删除tmp文件，随后向journal写入日志，最后判断是否需要清理磁盘空间。
private synchronized void completeEdit(Editor editor, boolean success) throws IOException {
Entry entry = editor.entry;
if (entry.currentEditor != editor) {
throw new IllegalStateException();
}
// 如果当前编辑是第一次创建Entry，那么每个索引上都应该有值
// valueCount表示一个Entry中的value数量
if (success && !entry.readable) {
for (int i = 0; i < valueCount; i++) {
if (!editor.written[i]) {
editor.abort();
throw new IllegalStateException("Newly created entry didn't create value for index " + i);
}
if (!entry.getDirtyFile(i).exists()) {
editor.abort();
return;
}
}
}
// 遍历Entry上的每个文件
// 如果编辑成功就将临时文件改名, 如果失败则删除临时文件
for (int i = 0; i < valueCount; i++) {
File dirty = entry.getDirtyFile(i);
if (success) {
if (dirty.exists()) {
File clean = entry.getCleanFile(i);
dirty.renameTo(clean);
long oldLength = entry.lengths[i];
long newLength = clean.length();
entry.lengths[i] = newLength;
size = size - oldLength + newLength;
}
} else {
deleteIfExists(dirty);
}
}
redundantOpCount++;
entry.currentEditor = null;
if (entry.readable | success) {
entry.readable = true;
journalWriter.write(CLEAN + ' ' + entry.key + entry.getLengths() + '\n');
if (success) {
// 给Entry的sequenceNumber赋值, 用于标记snapshot是否过期
// 如果Entry和snapshot的sequenceNumber不同, 则表示数据已经过期了
entry.sequenceNumber = nextSequenceNumber++;
}
} else {
lruEntries.remove(entry.key);
journalWriter.write(REMOVE + ' ' + entry.key + '\n');
}
journalWriter.flush();
// 判断是否需要清理磁盘空间
if (size > maxSize || journalRebuildRequired()) {
executorService.submit(cleanupCallable);
}
}
3.3 读缓存
读缓存时返回的是一个Snapshot快照，该方法会一次性地打开所有的输入流，即使之后文件被删除，该输入流依旧可用。
public synchronized Snapshot get(String key) throws IOException {
checkNotClosed();
validateKey(key);
Entry entry = lruEntries.get(key);
if (entry == null) {
return null;
}
if (!entry.readable) {
return null;
}
// Open all streams eagerly to guarantee that we see a single published
// snapshot. If we opened streams lazily then the streams could come
// from different edits.
InputStream[] ins = new InputStream[valueCount];
try {
for (int i = 0; i < valueCount; i++) {
ins[i] = new FileInputStream(entry.getCleanFile(i));
}
} catch (FileNotFoundException e) {
// 除非用户手动删了文件, 否则不会执行到这里...
return null;
}
redundantOpCount++;
journalWriter.append(READ + ' ' + key + '\n');
if (journalRebuildRequired()) {
executorService.submit(cleanupCallable);
}
return new Snapshot(key, entry.sequenceNumber, ins, entry.lengths);
}
3.4 移除缓存
移除缓存的逻辑比较简单，删除文件并添加日志即可，如果当前Entry正在被编辑就直接返回。
public synchronized boolean remove(String key) throws IOException {
checkNotClosed();
validateKey(key);
Entry entry = lruEntries.get(key);
if (entry == null || entry.currentEditor != null) {
return false;
}
for (int i = 0; i < valueCount; i++) {
File file = entry.getCleanFile(i);
if (file.exists() && !file.delete()) {
throw new IOException("failed to delete " + file);
}
size -= entry.lengths[i];
entry.lengths[i] = 0;
}
redundantOpCount++;
journalWriter.append(REMOVE + ' ' + key + '\n');
lruEntries.remove(key);
if (journalRebuildRequired()) {
executorService.submit(cleanupCallable);
}
return true;
}
