com.google.android.exoplayer2.upstream.cache

Class SimpleCache

java.lang.Object

com.google.android.exoplayer2.upstream.cache.SimpleCache

All Implemented Interfaces:

Cache

public final class SimpleCache
extends java.lang.Object
implements Cache

A Cache implementation that maintains an in-memory representation. Note, only one instance of SimpleCache is allowed for a given directory at a given time.

Nested Class Summary

Nested classes/interfaces inherited from interface com.google.android.exoplayer2.upstream.cache.Cache

Cache.CacheException, Cache.Listener

Constructor Summary

Constructors

Constructor and Description
SimpleCache(java.io.File cacheDir, CacheEvictor evictor) Constructs the cache.
SimpleCache(java.io.File cacheDir, CacheEvictor evictor, byte[] secretKey) Constructs the cache.
SimpleCache(java.io.File cacheDir, CacheEvictor evictor, byte[] secretKey, boolean encrypt) Constructs the cache.

Method Summary

Modifier and Type	Method and Description
java.util.NavigableSet<CacheSpan>	addListener(java.lang.String key, Cache.Listener listener) Registers a listener to listen for changes to a given key.
void	applyContentMetadataMutations(java.lang.String key, ContentMetadataMutations mutations) Applies mutations to the ContentMetadata for the given key.
void	commitFile(java.io.File file) Commits a file into the cache.
static void	disableCacheFolderLocking() Deprecated. Don't create multiple SimpleCache instances for the same cache folder. If you need to create another instance, make sure you call release() on the previous instance.
long	getCachedLength(java.lang.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.
java.util.NavigableSet<CacheSpan>	getCachedSpans(java.lang.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(java.lang.String key) Returns the content length for the given key if one set, or C.LENGTH_UNSET otherwise.
ContentMetadata	getContentMetadata(java.lang.String key) Returns a ContentMetadata for the given key.
java.util.Set<java.lang.String>	getKeys() Returns all keys in the cache.
boolean	isCached(java.lang.String key, long position, long length) Queries if a range is entirely available in the cache.
static boolean	isCacheFolderLocked(java.io.File cacheFolder) Returns whether cacheFolder is locked by a SimpleCache instance.
void	release() Releases the cache.
void	releaseHoleSpan(CacheSpan holeSpan) Releases a CacheSpan obtained from Cache.startReadWrite(String, long) which corresponded to a hole in the cache.
void	removeListener(java.lang.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(java.lang.String key, long length) Sets the content length for the given key.
java.io.File	startFile(java.lang.String key, long position, long maxLength) Obtains a cache file into which data can be written.
com.google.android.exoplayer2.upstream.cache.SimpleCacheSpan	startReadWrite(java.lang.String key, long position) A caller should invoke this method when they require data from a given position for a given key.
com.google.android.exoplayer2.upstream.cache.SimpleCacheSpan	startReadWriteNonBlocking(java.lang.String key, long position) Same as Cache.startReadWrite(String, long).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SimpleCache

public SimpleCache(java.io.File cacheDir,
                   CacheEvictor evictor)

Constructs the cache. The cache will delete any unrecognized files from the directory. Hence the directory cannot be used to store other files.

Parameters:

cacheDir - A dedicated cache directory.

evictor - The evictor to be used.

SimpleCache

public SimpleCache(java.io.File cacheDir,
                   CacheEvictor evictor,
                   byte[] secretKey)

Constructs the cache. The cache will delete any unrecognized files from the directory. Hence the directory cannot be used to store other files.

Parameters:

cacheDir - A dedicated cache directory.

evictor - The evictor to be used.

secretKey - If not null, cache keys will be stored encrypted on filesystem using AES/CBC. The key must be 16 bytes long.

SimpleCache

public SimpleCache(java.io.File cacheDir,
                   CacheEvictor evictor,
                   byte[] secretKey,
                   boolean encrypt)

Constructs the cache. The cache will delete any unrecognized files from the directory. Hence the directory cannot be used to store other files.

Parameters:

cacheDir - A dedicated cache directory.

evictor - The evictor to be used.

secretKey - If not null, cache keys will be stored encrypted on filesystem using AES/CBC. The key must be 16 bytes long.

encrypt - Whether the index will be encrypted when written. Must be false if secretKey is null.

Method Detail

isCacheFolderLocked

public static boolean isCacheFolderLocked(java.io.File cacheFolder)

Returns whether cacheFolder is locked by a SimpleCache instance. To unlock the folder the SimpleCache instance should be released.

disableCacheFolderLocking

@Deprecated
public static void disableCacheFolderLocking()

Deprecated. Don't create multiple SimpleCache instances for the same cache folder. If you need to create another instance, make sure you call release() on the previous instance.

Disables locking the cache folders which SimpleCache instances are using and releases any previous lock.

The locking prevents multiple SimpleCache instances from being created for the same folder. Disabling it may cause the cache data to be corrupted. Use at your own risk.

release

public void release()
             throws Cache.CacheException

Description copied from interface: Cache

Releases the cache. This method must be called when the cache is no longer required. The cache must not be used after calling this method.

Specified by:

release in interface Cache

Throws:

Cache.CacheException

addListener

public java.util.NavigableSet<CacheSpan> addListener(java.lang.String key,
                                                     Cache.Listener listener)

Description copied from interface: Cache

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.

Specified by:

addListener in interface Cache

Parameters:

key - The key to listen to.

listener - The listener to add.

Returns:

The current spans for the key.

removeListener

public void removeListener(java.lang.String key,
                           Cache.Listener listener)

Description copied from interface: Cache

Unregisters a listener.

Specified by:

removeListener in interface Cache

Parameters:

key - The key to stop listening to.

listener - The listener to remove.

getCachedSpans

@NonNull
public java.util.NavigableSet<CacheSpan> getCachedSpans(java.lang.String key)

Description copied from interface: Cache

Returns the cached spans for a given cache key.

Specified by:

getCachedSpans in interface Cache

Parameters:

key - The key for which spans should be returned.

Returns:

The spans for the key.

getKeys

public java.util.Set<java.lang.String> getKeys()

Description copied from interface: Cache

Returns all keys in the cache.

Specified by:

getKeys in interface Cache

Returns:

All the keys in the cache.

getCacheSpace

public long getCacheSpace()

Description copied from interface: Cache

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

Specified by:

getCacheSpace in interface Cache

Returns:

The total disk space in bytes.

startReadWrite

public com.google.android.exoplayer2.upstream.cache.SimpleCacheSpan startReadWrite(java.lang.String key,
                                                                                   long position)
                                                                            throws java.lang.InterruptedException,
                                                                                   Cache.CacheException

Description copied from interface: Cache

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 Cache.commitFile(File). When the caller has finished writing, it must release the lock by calling Cache.releaseHoleSpan(com.google.android.exoplayer2.upstream.cache.CacheSpan).

Specified by:

startReadWrite in interface Cache

Parameters:

key - The key of the data being requested.

position - The position of the data being requested.

Returns:

The CacheSpan.

Throws:

java.lang.InterruptedException - If the thread was interrupted.

Cache.CacheException - If an error is encountered.

startReadWriteNonBlocking

public com.google.android.exoplayer2.upstream.cache.SimpleCacheSpan startReadWriteNonBlocking(java.lang.String key,
                                                                                              long position)
                                                                                       throws Cache.CacheException

Description copied from interface: Cache

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

Specified by:

startReadWriteNonBlocking in interface Cache

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 - If an error is encountered.

startFile

public java.io.File startFile(java.lang.String key,
                              long position,
                              long maxLength)
                       throws Cache.CacheException

Description copied from interface: Cache

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

Specified by:

startFile in interface Cache

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 - If an error is encountered.

commitFile

public void commitFile(java.io.File file)
                throws Cache.CacheException

Description copied from interface: Cache

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

Specified by:

commitFile in interface Cache

Parameters:

file - A newly written cache file.

Throws:

Cache.CacheException - If an error is encountered.

releaseHoleSpan

public void releaseHoleSpan(CacheSpan holeSpan)

Description copied from interface: Cache

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

Specified by:

releaseHoleSpan in interface Cache

Parameters:

holeSpan - The CacheSpan being released.

removeSpan

public void removeSpan(CacheSpan span)
                throws Cache.CacheException

Description copied from interface: Cache

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

Specified by:

removeSpan in interface Cache

Parameters:

span - The CacheSpan to remove.

Throws:

Cache.CacheException - If an error is encountered.

isCached

public boolean isCached(java.lang.String key,
                        long position,
                        long length)

Description copied from interface: Cache

Queries if a range is entirely available in the cache.

Specified by:

isCached in interface 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;

getCachedLength

public long getCachedLength(java.lang.String key,
                            long position,
                            long length)

Description copied from interface: Cache

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.

Specified by:

getCachedLength in interface Cache

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

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

Description copied from interface: Cache

Sets the content length for the given key.

Specified by:

setContentLength in interface Cache

Parameters:

key - The cache key for the data.

length - The length of the data.

Throws:

Cache.CacheException - If an error is encountered.

getContentLength

public long getContentLength(java.lang.String key)

Description copied from interface: Cache

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

Specified by:

getContentLength in interface Cache

Parameters:

key - The cache key for the data.

Returns:

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

applyContentMetadataMutations

public void applyContentMetadataMutations(java.lang.String key,
                                          ContentMetadataMutations mutations)
                                   throws Cache.CacheException

Description copied from interface: Cache

Applies mutations to the ContentMetadata for the given key. A new CachedContent is added if there isn't one already with the given key.

Specified by:

applyContentMetadataMutations in interface Cache

Parameters:

key - The cache key for the data.

mutations - Contains mutations to be applied to the metadata.

Throws:

Cache.CacheException - If an error is encountered.

getContentMetadata

public ContentMetadata getContentMetadata(java.lang.String key)

Description copied from interface: Cache

Returns a ContentMetadata for the given key.

Specified by:

getContentMetadata in interface Cache

Parameters:

key - The cache key for the data.

Returns:

A ContentMetadata for the given key.