README.md
1Disk LRU Cache
2==============
3
4A cache that uses a bounded amount of space on a filesystem. Each cache entry
5has a string key and a fixed number of values. Each key must match the regex
6`[a-z0-9_-]{1,64}`. Values are byte sequences, accessible as streams or files.
7Each value must be between `0` and `Integer.MAX_VALUE` bytes in length.
8
9The cache stores its data in a directory on the filesystem. This directory must
10be exclusive to the cache; the cache may delete or overwrite files from its
11directory. It is an error for multiple processes to use the same cache
12directory at the same time.
13
14This cache limits the number of bytes that it will store on the filesystem.
15When the number of stored bytes exceeds the limit, the cache will remove
16entries in the background until the limit is satisfied. The limit is not
17strict: the cache may temporarily exceed it while waiting for files to be
18deleted. The limit does not include filesystem overhead or the cache journal so
19space-sensitive applications should set a conservative limit.
20
21Clients call `edit` to create or update the values of an entry. An entry may
22have only one editor at one time; if a value is not available to be edited then
23`edit` will return null.
24
25 * When an entry is being **created** it is necessary to supply a full set of
26 values; the empty value should be used as a placeholder if necessary.
27 * When an entry is being **edited**, it is not necessary to supply data for
28 every value; values default to their previous value.
29
30Every `edit` call must be matched by a call to `Editor.commit` or
31`Editor.abort`. Committing is atomic: a read observes the full set of values as
32they were before or after the commit, but never a mix of values.
33
34Clients call `get` to read a snapshot of an entry. The read will observe the
35value at the time that `get` was called. Updates and removals after the call do
36not impact ongoing reads.
37
38This class is tolerant of some I/O errors. If files are missing from the
39filesystem, the corresponding entries will be dropped from the cache. If an
40error occurs while writing a cache value, the edit will fail silently. Callers
41should handle other problems by catching `IOException` and responding
42appropriately.
43
44*Note: This implementation specifically targets Android compatibility.*
45
46License
47=======
48
49 Copyright 2012 Jake Wharton
50 Copyright 2011 The Android Open Source Project
51
52 Licensed under the Apache License, Version 2.0 (the "License");
53 you may not use this file except in compliance with the License.
54 You may obtain a copy of the License at
55
56 http://www.apache.org/licenses/LICENSE-2.0
57
58 Unless required by applicable law or agreed to in writing, software
59 distributed under the License is distributed on an "AS IS" BASIS,
60 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
61 See the License for the specific language governing permissions and
62 limitations under the License.
63
64
README.third_party