@UnstableApi
interface Cache

Known direct subclasses
SimpleCache

A Cache implementation that maintains an in-memory representation.


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.

Summary

Nested types

Thrown when an error is encountered when writing data.

interface Cache.Listener

Listener of Cache events.

Constants

const Long

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

Public functions

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

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

Unit

Applies mutations to the ContentMetadata for the given resource.

Unit
@WorkerThread
commitFile(file: File!, length: Long)

Commits a file into the cache.

Long

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

Long
getCachedBytes(key: String!, position: Long, length: Long)

Returns the total number of cached bytes between position (inclusive) and (position + length) (exclusive) of a resource.

Long
getCachedLength(key: String!, position: Long, length: Long)

Returns the length of continuously cached data starting from position, up to a maximum of maxLength, of a resource.

NavigableSet<CacheSpan!>!

Returns the cached spans for a given resource.

ContentMetadata!

Returns a ContentMetadata for the given resource.

(Mutable)Set<String!>!

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

Long

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

Boolean
isCached(key: String!, position: Long, length: Long)

Returns whether the specified range of data in a resource is fully cached.

Unit

Releases the cache.

Unit

Releases a CacheSpan obtained from startReadWrite which corresponded to a hole in the cache.

Unit
removeListener(key: String!, listener: Cache.Listener!)

Unregisters a listener.

Unit

Removes all CacheSpans for a resource, deleting the underlying files.

Unit

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

File!
@WorkerThread
startFile(key: String!, position: Long, length: Long)

Obtains a cache file into which data can be written.

CacheSpan!
@WorkerThread
startReadWrite(key: String!, position: Long, length: Long)

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

CacheSpan?
@WorkerThread
startReadWriteNonBlocking(key: String!, position: Long, length: Long)

Same as startReadWrite.

Constants

UID_UNSET

const val UID_UNSET = -1: Long

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

Public functions

addListener

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

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: String!

The cache key of the resource.

listener: Cache.Listener!

The listener to add.

Returns
NavigableSet<CacheSpan!>!

The current spans for the resource.

applyContentMetadataMutations

@WorkerThread
fun applyContentMetadataMutations(
    key: String!,
    mutations: ContentMetadataMutations!
): Unit

Applies mutations to the ContentMetadata for the given resource. A new 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: String!

The cache key of the resource.

mutations: ContentMetadataMutations!

Contains mutations to be applied to the metadata.

Throws
androidx.media3.datasource.cache.Cache.CacheException

If an error is encountered.

commitFile

@WorkerThread
fun commitFile(file: File!, length: Long): Unit

Commits a file into the cache. Must only be called when holding a corresponding hole obtained from startReadWrite.

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

Parameters
file: File!

A newly written cache file.

length: Long

The length of the newly written cache file in bytes.

Throws
androidx.media3.datasource.cache.Cache.CacheException

If an error is encountered.

getCacheSpace

fun getCacheSpace(): Long

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

getCachedBytes

fun getCachedBytes(key: String!, position: Long, length: Long): Long

Returns the total number of cached bytes between position (inclusive) and (position + length) (exclusive) of a resource.

Parameters
key: String!

The cache key of the resource.

position: Long

The starting position of the data in the resource.

length: Long

The length of the data to check. LENGTH_UNSET is permitted, and is equivalent to passing MAX_VALUE.

Returns
Long

The total number of cached bytes.

getCachedLength

fun getCachedLength(key: String!, position: Long, length: Long): Long

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: String!

The cache key of the resource.

position: Long

The starting position of the data in the resource.

length: Long

The maximum length of the data or hole to be returned. LENGTH_UNSET is permitted, and is equivalent to passing MAX_VALUE.

Returns
Long

The length of the continuously cached data, or -holeLength if position isn't cached.

getCachedSpans

fun getCachedSpans(key: String!): NavigableSet<CacheSpan!>!

Returns the cached spans for a given resource.

Parameters
key: String!

The cache key of the resource.

Returns
NavigableSet<CacheSpan!>!

The spans for the key.

getContentMetadata

fun getContentMetadata(key: String!): ContentMetadata!

Returns a ContentMetadata for the given resource.

Parameters
key: String!

The cache key of the resource.

Returns
ContentMetadata!

The ContentMetadata for the resource.

getKeys

fun getKeys(): (Mutable)Set<String!>!

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

getUid

fun getUid(): Long

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.

isCached

fun isCached(key: String!, position: Long, length: Long): Boolean

Returns whether the specified range of data in a resource is fully cached.

Parameters
key: String!

The cache key of the resource.

position: Long

The starting position of the data in the resource.

length: Long

The length of the data.

Returns
Boolean

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

release

@WorkerThread
fun release(): Unit

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.

releaseHoleSpan

fun releaseHoleSpan(holeSpan: CacheSpan!): Unit

Releases a CacheSpan obtained from startReadWrite which corresponded to a hole in the cache.

Parameters
holeSpan: CacheSpan!

The CacheSpan being released.

removeListener

fun removeListener(key: String!, listener: Cache.Listener!): Unit

Unregisters a listener.

Parameters
key: String!

The cache key of the resource.

listener: Cache.Listener!

The listener to remove.

removeResource

@WorkerThread
fun removeResource(key: String!): Unit

Removes all CacheSpans for a resource, deleting the underlying files.

Parameters
key: String!

The cache key of the resource being removed.

removeSpan

@WorkerThread
fun removeSpan(span: CacheSpan!): Unit

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: CacheSpan!

The CacheSpan to remove.

startFile

@WorkerThread
fun startFile(key: String!, position: Long, length: Long): File!

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

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

Parameters
key: String!

The cache key of the resource being written.

position: Long

The starting position in the resource from which data will be written.

length: Long

The length of the data being written, or LENGTH_UNSET if unknown. Used only to ensure that there is enough space in the cache.

Returns
File!

The file into which data should be written.

Throws
androidx.media3.datasource.cache.Cache.CacheException

If an error is encountered.

startReadWrite

@WorkerThread
fun startReadWrite(key: String!, position: Long, length: Long): CacheSpan!

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. 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. When the caller has finished writing, it must release the lock by calling releaseHoleSpan.

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

Parameters
key: String!

The cache key of the resource.

position: Long

The starting position in the resource from which data is required.

length: Long

The length of the data being requested, or 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 LENGTH_UNSET when possible.

Returns
CacheSpan!

The CacheSpan.

Throws
java.lang.InterruptedException

If the thread was interrupted.

androidx.media3.datasource.cache.Cache.CacheException

If an error is encountered.

startReadWriteNonBlocking

@WorkerThread
fun startReadWriteNonBlocking(key: String!, position: Long, length: Long): CacheSpan?

Same as startReadWrite. 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.

Parameters
key: String!

The cache key of the resource.

position: Long

The starting position in the resource from which data is required.

length: Long

The length of the data being requested, or LENGTH_UNSET if unbounded. The length is ignored if there is a cache entry that overlaps the position. Else, it defines the range of data locked by the returned CacheSpan.

Returns
CacheSpan?

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

Throws
androidx.media3.datasource.cache.Cache.CacheException

If an error is encountered.