com.google.android.exoplayer2.upstream.cache

Interface Cache

All Known Implementing Classes:

SimpleCache

public interface Cache

An interface for cache.

Nested Class Summary

Nested Classes

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.

Method Summary

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	commitFile(File file) Commits a file into the cache.
long	getCachedBytes(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.
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	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).

Method Detail

addListener

NavigableSet<CacheSpan> addListener(String key,
                                    Cache.Listener listener)

Registers a listener to listen for changes to a given key.

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.

Parameters:

key - The key to listen to.

listener - The listener to add.

Returns:

The current spans for the key.

removeListener

void removeListener(String key,
                    Cache.Listener listener)

Unregisters a listener.

Parameters:

key - The key to stop listening to.

listener - The listener to remove.

getCachedSpans

NavigableSet<CacheSpan> getCachedSpans(String key)

Returns the cached spans for a given cache key.

Parameters:

key - The key for which spans should be returned.

Returns:

The spans for the key. May be null if there are no such spans.

getKeys

Set<String> getKeys()

Returns all keys in the cache.

Returns:

All the keys in the cache.

getCacheSpace

long getCacheSpace()

Returns the total disk space in bytes used by the cache.

Returns:

The total disk space in bytes.

startReadWrite

CacheSpan startReadWrite(String key,
                         long position)
                  throws InterruptedException,
                         Cache.CacheException

A caller should invoke this method when they require data from a given position for a given key.

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).

Parameters:

key - The key of the data being requested.

position - The position of the data being requested.

Returns:

The CacheSpan.

Throws:

InterruptedException

Cache.CacheException

startReadWriteNonBlocking

CacheSpan startReadWriteNonBlocking(String key,
                                    long position)
                             throws Cache.CacheException

Same as startReadWrite(String, long). However, if the cache entry is locked, then instead of blocking, this method will return null as the CacheSpan.

Parameters:

key - The key of the data being requested.

position - The position of the data being requested.

Returns:

The CacheSpan. Or null if the cache entry is locked.

Throws:

Cache.CacheException

startFile

File startFile(String key,
               long position,
               long maxLength)
        throws Cache.CacheException

Obtains a cache file into which data can be written. Must only be called when holding a corresponding hole CacheSpan obtained from startReadWrite(String, long).

Parameters:

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.

Returns:

The file into which data should be written.

Throws:

Cache.CacheException

commitFile

void commitFile(File file)
         throws Cache.CacheException

Commits a file into the cache. Must only be called when holding a corresponding hole CacheSpan obtained from startReadWrite(String, long)

Parameters:

file - A newly written cache file.

Throws:

Cache.CacheException

releaseHoleSpan

void releaseHoleSpan(CacheSpan holeSpan)

Releases a CacheSpan obtained from startReadWrite(String, long) which corresponded to a hole in the cache.

Parameters:

holeSpan - The CacheSpan being released.

removeSpan

void removeSpan(CacheSpan span)
         throws Cache.CacheException

Removes a cached CacheSpan from the cache, deleting the underlying file.

Parameters:

span - The CacheSpan to remove.

Throws:

Cache.CacheException

isCached

boolean isCached(String key,
                 long position,
                 long length)

Queries if a range is entirely available in the cache.

Parameters:

key - The cache key for the data.

position - The starting position of the data.

length - The length of the data.

Returns:

true if the data is available in the Cache otherwise false;

getCachedBytes

long getCachedBytes(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. If the position isn't cached then -(the length of the gap to the next cached data up to length bytes) is returned.

Parameters:

key - The cache key for the data.

position - The starting position of the data.

length - The maximum length of the data to be returned.

Returns:

the length of the cached or not cached data block length.

setContentLength

void setContentLength(String key,
                      long length)
               throws Cache.CacheException

Sets the content length for the given key.

Parameters:

key - The cache key for the data.

length - The length of the data.

Throws:

Cache.CacheException

getContentLength

long getContentLength(String key)

Returns the content length for the given key if one set, or C.LENGTH_UNSET otherwise.

Parameters:

key - The cache key for the data.