public interface Cache
Modifier and Type | Interface and Description |
---|---|
static class |
Cache.CacheException
Thrown when an error is encountered when writing data.
|
static interface |
Cache.Listener
Listener of
Cache events. |
Modifier and Type | Method and Description |
---|---|
NavigableSet<CacheSpan> |
addListener(String key,
Cache.Listener listener)
Registers a listener to listen for changes to a given key.
|
void |
applyContentMetadataMutations(String key,
ContentMetadataMutations mutations)
Applies
mutations to the ContentMetadata for the given key. |
void |
commitFile(File file)
Commits a file into the cache.
|
long |
getCachedLength(String key,
long position,
long length)
Returns the length of the cached data block starting from the
position to the block end
up to length bytes. |
NavigableSet<CacheSpan> |
getCachedSpans(String key)
Returns the cached spans for a given cache key.
|
long |
getCacheSpace()
Returns the total disk space in bytes used by the cache.
|
long |
getContentLength(String key)
Returns the content length for the given key if one set, or
C.LENGTH_UNSET otherwise. |
ContentMetadata |
getContentMetadata(String key)
Returns a
ContentMetadata for the given key. |
Set<String> |
getKeys()
Returns all keys in the cache.
|
boolean |
isCached(String key,
long position,
long length)
Queries if a range is entirely available in the cache.
|
void |
release()
Releases the cache.
|
void |
releaseHoleSpan(CacheSpan holeSpan)
Releases a
CacheSpan obtained from startReadWrite(String, long) which
corresponded to a hole in the cache. |
void |
removeListener(String key,
Cache.Listener listener)
Unregisters a listener.
|
void |
removeSpan(CacheSpan span)
Removes a cached
CacheSpan from the cache, deleting the underlying file. |
void |
setContentLength(String key,
long length)
Sets the content length for the given key.
|
File |
startFile(String key,
long position,
long maxLength)
Obtains a cache file into which data can be written.
|
CacheSpan |
startReadWrite(String key,
long position)
A caller should invoke this method when they require data from a given position for a given
key.
|
CacheSpan |
startReadWriteNonBlocking(String key,
long position)
Same as
startReadWrite(String, long) . |
void release()
NavigableSet<CacheSpan> addListener(String key, Cache.Listener listener)
No guarantees are made about the thread or threads on which the listener is called, but it is guaranteed that listener methods will be called in a serial fashion (i.e. one at a time) and in the same order as events occurred.
key
- The key to listen to.listener
- The listener to add.void removeListener(String key, Cache.Listener listener)
key
- The key to stop listening to.listener
- The listener to remove.NavigableSet<CacheSpan> getCachedSpans(String key)
key
- The key for which spans should be returned.long getCacheSpace()
CacheSpan startReadWrite(String key, long position) throws InterruptedException, Cache.CacheException
If there is a cache entry that overlaps the position, then the returned CacheSpan
defines the file in which the data is stored. CacheSpan.isCached
is true. The caller
may read from the cache file, but does not acquire any locks.
If there is no cache entry overlapping offset
, then the returned CacheSpan
defines a hole in the cache starting at position
into which the caller may write as it
obtains the data from some other source. The returned CacheSpan
serves as a lock.
Whilst the caller holds the lock it may write data into the hole. It may split data into
multiple files. When the caller has finished writing a file it should commit it to the cache by
calling commitFile(File)
. When the caller has finished writing, it must release the
lock by calling releaseHoleSpan(com.google.android.exoplayer2.upstream.cache.CacheSpan)
.
key
- The key of the data being requested.position
- The position of the data being requested.CacheSpan
.InterruptedException
- If the thread was interrupted.Cache.CacheException
- If an error is encountered.@Nullable CacheSpan startReadWriteNonBlocking(String key, long position) throws Cache.CacheException
startReadWrite(String, long)
. However, if the cache entry is locked, then
instead of blocking, this method will return null as the CacheSpan
.key
- The key of the data being requested.position
- The position of the data being requested.CacheSpan
. Or null if the cache entry is locked.Cache.CacheException
- If an error is encountered.File startFile(String key, long position, long maxLength) throws Cache.CacheException
CacheSpan
obtained from startReadWrite(String, long)
.key
- The cache key for the data.position
- The starting position of the data.maxLength
- The maximum length of the data to be written. Used only to ensure that there
is enough space in the cache.Cache.CacheException
- If an error is encountered.void commitFile(File file) throws Cache.CacheException
CacheSpan
obtained from startReadWrite(String, long)
file
- A newly written cache file.Cache.CacheException
- If an error is encountered.void releaseHoleSpan(CacheSpan holeSpan)
CacheSpan
obtained from startReadWrite(String, long)
which
corresponded to a hole in the cache.holeSpan
- The CacheSpan
being released.void removeSpan(CacheSpan span) throws Cache.CacheException
CacheSpan
from the cache, deleting the underlying file.span
- The CacheSpan
to remove.Cache.CacheException
- If an error is encountered.boolean isCached(String key, long position, long length)
key
- The cache key for the data.position
- The starting position of the data.length
- The length of the data.long getCachedLength(String key, long position, long length)
position
to the block end
up to length
bytes. If the position
isn't cached then -(the length of the gap
to the next cached data up to length
bytes) is returned.key
- The cache key for the data.position
- The starting position of the data.length
- The maximum length of the data to be returned.void setContentLength(String key, long length) throws Cache.CacheException
key
- The cache key for the data.length
- The length of the data.Cache.CacheException
- If an error is encountered.long getContentLength(String key)
C.LENGTH_UNSET
otherwise.key
- The cache key for the data.C.LENGTH_UNSET
otherwise.void applyContentMetadataMutations(String key, ContentMetadataMutations mutations) throws Cache.CacheException
mutations
to the ContentMetadata
for the given key. A new CachedContent
is added if there isn't one already with the given key.key
- The cache key for the data.mutations
- Contains mutations to be applied to the metadata.Cache.CacheException
- If an error is encountered.ContentMetadata getContentMetadata(String key)
ContentMetadata
for the given key.key
- The cache key for the data.ContentMetadata
for the given key.