Cache (ExoPlayer library) - Exoplayer

Package com.google.android.exoplayer2.upstream.cache

Interface Cache

All Known Implementing Classes:SimpleCache

[@Deprecated](https://developer.android.com/reference/java/lang/Deprecated.html "class or interface in java.lang")public interfaceCache

Deprecated. com.google.android.exoplayer2 is deprecated. Please migrate to androidx.media3 (which contains the same ExoPlayer code). See the migration guide for more details, including a script to help with the migration.

A cache that supports partial caching of resources.

Terminology

A resource is a complete piece of logical data, for example a complete media file.
A cache key uniquely identifies a resource. URIs are often suitable for use as cache keys, however this is not always the case. URIs are not suitable when caching resources obtained from a service that generates multiple URIs for the same underlying resource, for example because the service uses expiring URIs as a form of access control.
A cache span is a byte range within a resource, which may or may not be cached. A cache span that's not cached is called a hole span. A cache span that is cached corresponds to a single underlying file in the cache.

Nested Class Summary

Nested Classes | Modifier and Type | Interface | Description | | --- | --- | --- | | static class | Cache.CacheException | Deprecated.

Thrown when an error is encountered when writing data. | | static interface | Cache.Listener | Deprecated.

Listener of Cache events. |

Field Summary

Fields | Modifier and Type | Field | Description | | --- | --- | --- | | static long | UID_UNSET | Deprecated.

Returned by getUid() if initialization failed before the unique identifier was read or generated. |

Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods | Modifier and Type | Method | Description | | --- | --- | --- | | NavigableSet<CacheSpan> | addListener(String key, Cache.Listener listener) | Deprecated.

Registers a listener to listen for changes to a given resource. | | void | applyContentMetadataMutations(String key, ContentMetadataMutations mutations) | Deprecated.

Applies mutations to the ContentMetadata for the given resource. | | void | commitFile(File file, long length) | Deprecated.

Commits a file into the cache. | | long | getCachedBytes(String key, long position, long length) | Deprecated.

Returns the total number of cached bytes between position (inclusive) and (position + length) (exclusive) of a resource. | | long | getCachedLength(String key, long position, long length) | Deprecated.

Returns the length of continuously cached data starting from position, up to a maximum of maxLength, of a resource. | | NavigableSet<CacheSpan> | getCachedSpans(String key) | Deprecated.

Returns the cached spans for a given resource. | | long | getCacheSpace() | Deprecated.

Returns the total disk space in bytes used by the cache. | | ContentMetadata | getContentMetadata(String key) | Deprecated.

Returns a ContentMetadata for the given resource. | | Set<String> | getKeys() | Deprecated.

Returns the cache keys of all of the resources that are at least partially cached. | | long | getUid() | Deprecated.

Returns a non-negative unique identifier for the cache, or UID_UNSET if initialization failed before the unique identifier was determined. | | boolean | isCached(String key, long position, long length) | Deprecated.

Returns whether the specified range of data in a resource is fully cached. | | void | release() | Deprecated.

Releases the cache. | | void | releaseHoleSpan(CacheSpan holeSpan) | Deprecated.

Releases a CacheSpan obtained from startReadWrite(String, long, long) which corresponded to a hole in the cache. | | void | removeListener(String key, Cache.Listener listener) | Deprecated.

Unregisters a listener. | | void | removeResource(String key) | Deprecated.

Removes all CacheSpans for a resource, deleting the underlying files. | | void | removeSpan(CacheSpan span) | Deprecated.

Removes a cached CacheSpan from the cache, deleting the underlying file. | | File | startFile(String key, long position, long length) | Deprecated.

Obtains a cache file into which data can be written. | | CacheSpan | startReadWrite(String key, long position, long length) | Deprecated.

A caller should invoke this method when they require data starting from a given position in a given resource. | | CacheSpan | startReadWriteNonBlocking(String key, long position, long length) | Deprecated.

Same as startReadWrite(String, long, long). |

Field Detail

UID_UNSET

static final long UID_UNSET

Deprecated.

Returned by getUid() if initialization failed before the unique identifier was read or generated. See Also:Constant Field Values

Method Detail

getUid

long getUid()

Deprecated.

Returns a non-negative unique identifier for the cache, or UID_UNSET if initialization failed before the unique identifier was determined.

Implementations are expected to generate and store the unique identifier alongside the cached content. If the location of the cache is deleted or swapped, it is expected that a new unique identifier will be generated when the cache is recreated.

release

@WorkerThread
void release()

Deprecated.

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.

This method may be slow and shouldn't normally be called on the main thread.

addListener

[NavigableSet](https://developer.android.com/reference/java/util/NavigableSet.html "class or interface in java.util")<[CacheSpan](CacheSpan.html "class in com.google.android.exoplayer2.upstream.cache")> addListener([String](https://developer.android.com/reference/java/lang/String.html?is-external=true "class or interface in java.lang")key,[Cache.Listener](Cache.Listener.html "interface in com.google.android.exoplayer2.upstream.cache")listener)

Deprecated.

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

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 cache key of the resource.listener - The listener to add.Returns:The current spans for the resource.

removeListener

void removeListener([String](https://developer.android.com/reference/java/lang/String.html "class or interface in java.lang")key,[Cache.Listener](Cache.Listener.html "interface in com.google.android.exoplayer2.upstream.cache")listener)

Deprecated.

Unregisters a listener. Parameters:key - The cache key of the resource.listener - The listener to remove.

getCachedSpans

[NavigableSet](https://developer.android.com/reference/java/util/NavigableSet.html "class or interface in java.util")<[CacheSpan](CacheSpan.html "class in com.google.android.exoplayer2.upstream.cache")> getCachedSpans([String](https://developer.android.com/reference/java/lang/String.html?is-external=true "class or interface in java.lang")key)

Deprecated.

Returns the cached spans for a given resource. Parameters:key - The cache key of the resource.Returns:The spans for the key.

getKeys

[Set](https://developer.android.com/reference/java/util/Set.html "class or interface in java.util")<[String](https://developer.android.com/reference/java/lang/String.html?is-external=true "class or interface in java.lang")> getKeys()

Deprecated.

Returns the cache keys of all of the resources that are at least partially cached.

getCacheSpace

long getCacheSpace()

Deprecated.

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

startReadWrite

@WorkerThread[CacheSpan](CacheSpan.html "class in com.google.android.exoplayer2.upstream.cache")startReadWrite([String](https://developer.android.com/reference/java/lang/String.html "class or interface in java.lang")key,
                         long position,
                         long length)
                  throws[InterruptedException](https://developer.android.com/reference/java/lang/InterruptedException.html "class or interface in java.lang"),[Cache.CacheException](Cache.CacheException.html "class in com.google.android.exoplayer2.upstream.cache")

Deprecated.

A caller should invoke this method when they require data starting from a given position in a given resource.

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

This method may be slow and shouldn't normally be called on the main thread.

Parameters:key - The cache key of the resource.position - The starting position in the resource from which data is required.length - The length of the data being requested, or C.LENGTH_UNSET if unbounded. The length is ignored if there is a cache entry that overlaps the position. Else, it defines the maximum length of the hole CacheSpan that's returned. Cache implementations may support parallel writes into non-overlapping holes, and so passing the actual required length should be preferred to passing C.LENGTH_UNSET when possible.Returns:The CacheSpan.Throws:InterruptedException - If the thread was interrupted.Cache.CacheException - If an error is encountered.

startReadWriteNonBlocking

@WorkerThread
@Nullable[CacheSpan](CacheSpan.html "class in com.google.android.exoplayer2.upstream.cache")startReadWriteNonBlocking([String](https://developer.android.com/reference/java/lang/String.html "class or interface in java.lang")key,
                                    long position,
                                    long length)
                             throws[Cache.CacheException](Cache.CacheException.html "class in com.google.android.exoplayer2.upstream.cache")

Deprecated.

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

This method may be slow and shouldn't normally be called on the main thread.

startFile

@WorkerThread[File](https://developer.android.com/reference/java/io/File.html "class or interface in java.io")startFile([String](https://developer.android.com/reference/java/lang/String.html?is-external=true "class or interface in java.lang")key,
               long position,
               long length)
        throws[Cache.CacheException](Cache.CacheException.html "class in com.google.android.exoplayer2.upstream.cache")

Deprecated.

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

This method may be slow and shouldn't normally be called on the main thread.

Parameters:key - The cache key of the resource being written.position - The starting position in the resource from which data will be written.length - The length of the data being written, or C.LENGTH_UNSET if unknown. 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

@WorkerThread
void commitFile([File](https://developer.android.com/reference/java/io/File.html "class or interface in java.io")file,
                long length)
         throws[Cache.CacheException](Cache.CacheException.html "class in com.google.android.exoplayer2.upstream.cache")

Deprecated.

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

This method may be slow and shouldn't normally be called on the main thread.

Parameters:file - A newly written cache file.length - The length of the newly written cache file in bytes.Throws:Cache.CacheException - If an error is encountered.

releaseHoleSpan

void releaseHoleSpan([CacheSpan](CacheSpan.html "class in com.google.android.exoplayer2.upstream.cache")holeSpan)

Deprecated.

Releases a CacheSpan obtained from startReadWrite(String, long, long) which corresponded to a hole in the cache. Parameters:holeSpan - The CacheSpan being released.

removeResource

@WorkerThread
void removeResource([String](https://developer.android.com/reference/java/lang/String.html "class or interface in java.lang")key)

Deprecated.

Removes all CacheSpans for a resource, deleting the underlying files. Parameters:key - The cache key of the resource being removed.

removeSpan

@WorkerThread
void removeSpan([CacheSpan](CacheSpan.html "class in com.google.android.exoplayer2.upstream.cache")span)

Deprecated.

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

This method may be slow and shouldn't normally be called on the main thread.

Parameters:span - The CacheSpan to remove.

isCached

boolean isCached([String](https://developer.android.com/reference/java/lang/String.html "class or interface in java.lang")key,
                 long position,
                 long length)

Deprecated.

Returns whether the specified range of data in a resource is fully cached. Parameters:key - The cache key of the resource.position - The starting position of the data in the resource.length - The length of the data.Returns:true if the data is available in the Cache otherwise false;

getCachedLength

long getCachedLength([String](https://developer.android.com/reference/java/lang/String.html "class or interface in java.lang")key,
                     long position,
                     long length)

Deprecated.

Returns the length of continuously cached data starting from position, up to a maximum of maxLength, of a resource. If position isn't cached then -holeLength is returned, where holeLength is the length of continuously uncached data starting from position, up to a maximum of maxLength. Parameters:key - The cache key of the resource.position - The starting position of the data in the resource.length - The maximum length of the data or hole to be returned. C.LENGTH_UNSET is permitted, and is equivalent to passing Long.MAX_VALUE.Returns:The length of the continuously cached data, or -holeLength if position isn't cached.

getCachedBytes

long getCachedBytes([String](https://developer.android.com/reference/java/lang/String.html "class or interface in java.lang")key,
                    long position,
                    long length)

Deprecated.

Returns the total number of cached bytes between position (inclusive) and (position + length) (exclusive) of a resource. Parameters:key - The cache key of the resource.position - The starting position of the data in the resource.length - The length of the data to check. C.LENGTH_UNSET is permitted, and is equivalent to passing Long.MAX_VALUE.Returns:The total number of cached bytes.

applyContentMetadataMutations

@WorkerThread
void applyContentMetadataMutations([String](https://developer.android.com/reference/java/lang/String.html "class or interface in java.lang")key,[ContentMetadataMutations](ContentMetadataMutations.html "class in com.google.android.exoplayer2.upstream.cache")mutations)
                            throws[Cache.CacheException](Cache.CacheException.html "class in com.google.android.exoplayer2.upstream.cache")

Deprecated.

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

This method may be slow and shouldn't normally be called on the main thread.

Parameters:key - The cache key of the resource.mutations - Contains mutations to be applied to the metadata.Throws:Cache.CacheException - If an error is encountered.

getContentMetadata

[ContentMetadata](ContentMetadata.html "interface in com.google.android.exoplayer2.upstream.cache")getContentMetadata([String](https://developer.android.com/reference/java/lang/String.html "class or interface in java.lang")key)

Deprecated.

Returns a ContentMetadata for the given resource. Parameters:key - The cache key of the resource.Returns:The ContentMetadata for the resource.