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