# Cache

Artifact: [androidx.media3:media3-datasource](https://developer.android.com/jetpack/androidx/releases/media3) [View Source](https://cs.android.com/search?q=file:androidx/media3/datasource/cache/Cache.java+class:androidx.media3.datasource.cache.Cache)

*** ** * ** ***


```
@UnstableApi
public interface Cache
```

<br />

Known direct subclasses [SimpleCache](https://developer.android.com/reference/androidx/media3/datasource/cache/SimpleCache)

|---|---|
| `https://developer.android.com/reference/androidx/media3/datasource/cache/SimpleCache` | A `https://developer.android.com/reference/androidx/media3/datasource/cache/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 |
|---|
| `public class https://developer.android.com/reference/androidx/media3/datasource/cache/Cache.CacheException extends https://developer.android.com/reference/java/io/IOException.html` Thrown when an error is encountered when writing data. |
| `public interface https://developer.android.com/reference/androidx/media3/datasource/cache/Cache.Listener` Listener of `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache` events. |

| ### Constants |
|---|---|
| `default static final long` | `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#UID_UNSET() = -1` Returned by `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#getUid()` if initialization failed before the unique identifier was read or generated. |

| ### Public methods |
|---|---|
| `abstract https://developer.android.com/reference/java/util/NavigableSet.html<https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan>` | `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#addListener(java.lang.String,androidx.media3.datasource.cache.Cache.Listener)(https://developer.android.com/reference/java/lang/String.html key, https://developer.android.com/reference/androidx/media3/datasource/cache/Cache.Listener listener)` Registers a listener to listen for changes to a given resource. |
| `abstract void` | `@https://developer.android.com/reference/androidx/annotation/WorkerThread https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#applyContentMetadataMutations(java.lang.String,androidx.media3.datasource.cache.ContentMetadataMutations)( https://developer.android.com/reference/java/lang/String.html key, https://developer.android.com/reference/androidx/media3/datasource/cache/ContentMetadataMutations mutations )` Applies `mutations` to the `https://developer.android.com/reference/androidx/media3/datasource/cache/ContentMetadata` for the given resource. |
| `abstract void` | `@https://developer.android.com/reference/androidx/annotation/WorkerThread https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#commitFile(java.io.File,long)(https://developer.android.com/reference/java/io/File.html file, long length)` Commits a file into the cache. |
| `abstract long` | `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#getCacheSpace()()` Returns the total disk space in bytes used by the cache. |
| `abstract long` | `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#getCachedBytes(java.lang.String,long,long)(https://developer.android.com/reference/java/lang/String.html key, long position, long length)` Returns the total number of cached bytes between `position` (inclusive) and ` (position + length)` (exclusive) of a resource. |
| `abstract long` | `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#getCachedLength(java.lang.String,long,long)(https://developer.android.com/reference/java/lang/String.html key, long position, long length)` Returns the length of continuously cached data starting from `position`, up to a maximum of `maxLength`, of a resource. |
| `abstract https://developer.android.com/reference/java/util/NavigableSet.html<https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan>` | `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#getCachedSpans(java.lang.String)(https://developer.android.com/reference/java/lang/String.html key)` Returns the cached spans for a given resource. |
| `abstract https://developer.android.com/reference/androidx/media3/datasource/cache/ContentMetadata` | `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#getContentMetadata(java.lang.String)(https://developer.android.com/reference/java/lang/String.html key)` Returns a `https://developer.android.com/reference/androidx/media3/datasource/cache/ContentMetadata` for the given resource. |
| `abstract https://developer.android.com/reference/java/util/Set.html<https://developer.android.com/reference/java/lang/String.html>` | `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#getKeys()()` Returns the cache keys of all of the resources that are at least partially cached. |
| `abstract long` | `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#getUid()()` Returns a non-negative unique identifier for the cache, or `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#UID_UNSET()` if initialization failed before the unique identifier was determined. |
| `abstract boolean` | `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#isCached(java.lang.String,long,long)(https://developer.android.com/reference/java/lang/String.html key, long position, long length)` Returns whether the specified range of data in a resource is fully cached. |
| `abstract void` | `@https://developer.android.com/reference/androidx/annotation/WorkerThread https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#release()()` Releases the cache. |
| `abstract void` | `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#releaseHoleSpan(androidx.media3.datasource.cache.CacheSpan)(https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan holeSpan)` Releases a `https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan` obtained from `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#startReadWrite(java.lang.String,long,long)` which corresponded to a hole in the cache. |
| `abstract void` | `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#removeListener(java.lang.String,androidx.media3.datasource.cache.Cache.Listener)(https://developer.android.com/reference/java/lang/String.html key, https://developer.android.com/reference/androidx/media3/datasource/cache/Cache.Listener listener)` Unregisters a listener. |
| `abstract void` | `@https://developer.android.com/reference/androidx/annotation/WorkerThread https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#removeResource(java.lang.String)(https://developer.android.com/reference/java/lang/String.html key)` Removes all `https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan` for a resource, deleting the underlying files. |
| `abstract void` | `@https://developer.android.com/reference/androidx/annotation/WorkerThread https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#removeSpan(androidx.media3.datasource.cache.CacheSpan)(https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan span)` Removes a cached `https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan` from the cache, deleting the underlying file. |
| `abstract https://developer.android.com/reference/java/io/File.html` | `@https://developer.android.com/reference/androidx/annotation/WorkerThread https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#startFile(java.lang.String,long,long)(https://developer.android.com/reference/java/lang/String.html key, long position, long length)` Obtains a cache file into which data can be written. |
| `abstract https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan` | `@https://developer.android.com/reference/androidx/annotation/WorkerThread https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#startReadWrite(java.lang.String,long,long)(https://developer.android.com/reference/java/lang/String.html key, long position, long length)` A caller should invoke this method when they require data starting from a given position in a given resource. |
| `abstract @https://developer.android.com/reference/androidx/annotation/Nullable https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan` | `@https://developer.android.com/reference/androidx/annotation/WorkerThread https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#startReadWriteNonBlocking(java.lang.String,long,long)(https://developer.android.com/reference/java/lang/String.html key, long position, long length)` Same as `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#startReadWrite(java.lang.String,long,long)`. |

## Constants

### UID_UNSET

```
default static final long UID_UNSET = -1
```

Returned by `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#getUid()` if initialization failed before the unique identifier was read or generated.

## Public methods

### addListener

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

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 |
|---|---|
| `https://developer.android.com/reference/java/lang/String.html key` | The cache key of the resource. |
| `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache.Listener listener` | The listener to add. |

| Returns |
|---|---|
| `https://developer.android.com/reference/java/util/NavigableSet.html<https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan>` | The current spans for the resource. |

### applyContentMetadataMutations

```
@WorkerThread
abstract void applyContentMetadataMutations(
    String key,
    ContentMetadataMutations mutations
)
```

Applies `mutations` to the `https://developer.android.com/reference/androidx/media3/datasource/cache/ContentMetadata` for the given resource. A new `https://developer.android.com/reference/androidx/media3/datasource/cache/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 |
|---|---|
| `https://developer.android.com/reference/java/lang/String.html key` | The cache key of the resource. |
| `https://developer.android.com/reference/androidx/media3/datasource/cache/ContentMetadataMutations mutations` | Contains mutations to be applied to the metadata. |

| Throws |
|---|---|
| `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache.CacheException` | If an error is encountered. |

### commitFile

```
@WorkerThread
abstract void commitFile(File file, long length)
```

Commits a file into the cache. Must only be called when holding a corresponding hole `https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan` obtained from `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#startReadWrite(java.lang.String,long,long)`.

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

| Parameters |
|---|---|
| `https://developer.android.com/reference/java/io/File.html file` | A newly written cache file. |
| `long length` | The length of the newly written cache file in bytes. |

| Throws |
|---|---|
| `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache.CacheException` | If an error is encountered. |

### getCacheSpace

```
abstract long getCacheSpace()
```

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

### getCachedBytes

```
abstract long getCachedBytes(String key, long position, long length)
```

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

| Parameters |
|---|---|
| `https://developer.android.com/reference/java/lang/String.html key` | The cache key of the resource. |
| `long position` | The starting position of the data in the resource. |
| `long length` | The length of the data to check. `https://developer.android.com/reference/androidx/media3/common/C#LENGTH_UNSET()` is permitted, and is equivalent to passing `https://developer.android.com/reference/java/lang/Long.html#MAX_VALUE`. |

| Returns |
|---|---|
| `long` | The total number of cached bytes. |

### getCachedLength

```
abstract long getCachedLength(String key, long position, long length)
```

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 |
|---|---|
| `https://developer.android.com/reference/java/lang/String.html key` | The cache key of the resource. |
| `long position` | The starting position of the data in the resource. |
| `long length` | The maximum length of the data or hole to be returned. `https://developer.android.com/reference/androidx/media3/common/C#LENGTH_UNSET()` is permitted, and is equivalent to passing `https://developer.android.com/reference/java/lang/Long.html#MAX_VALUE`. |

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

### getCachedSpans

```
abstract NavigableSet<CacheSpan> getCachedSpans(String key)
```

Returns the cached spans for a given resource.

| Parameters |
|---|---|
| `https://developer.android.com/reference/java/lang/String.html key` | The cache key of the resource. |

| Returns |
|---|---|
| `https://developer.android.com/reference/java/util/NavigableSet.html<https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan>` | The spans for the key. |

### getContentMetadata

```
abstract ContentMetadata getContentMetadata(String key)
```

Returns a `https://developer.android.com/reference/androidx/media3/datasource/cache/ContentMetadata` for the given resource.

| Parameters |
|---|---|
| `https://developer.android.com/reference/java/lang/String.html key` | The cache key of the resource. |

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/media3/datasource/cache/ContentMetadata` | The `https://developer.android.com/reference/androidx/media3/datasource/cache/ContentMetadata` for the resource. |

### getKeys

```
abstract Set<String> getKeys()
```

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

### getUid

```
abstract long getUid()
```

Returns a non-negative unique identifier for the cache, or `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#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

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

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

| Parameters |
|---|---|
| `https://developer.android.com/reference/java/lang/String.html key` | The cache key of the resource. |
| `long position` | The starting position of the data in the resource. |
| `long length` | The length of the data. |

| Returns |
|---|---|
| `boolean` | true if the data is available in the Cache otherwise false; |

### release

```
@WorkerThread
abstract void release()
```

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

```
abstract void releaseHoleSpan(CacheSpan holeSpan)
```

Releases a `https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan` obtained from `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#startReadWrite(java.lang.String,long,long)` which corresponded to a hole in the cache.

| Parameters |
|---|---|
| `https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan holeSpan` | The `https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan` being released. |

### removeListener

```
abstract void removeListener(String key, Cache.Listener listener)
```

Unregisters a listener.

| Parameters |
|---|---|
| `https://developer.android.com/reference/java/lang/String.html key` | The cache key of the resource. |
| `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache.Listener listener` | The listener to remove. |

### removeResource

```
@WorkerThread
abstract void removeResource(String key)
```

Removes all `https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan` for a resource, deleting the underlying files.

| Parameters |
|---|---|
| `https://developer.android.com/reference/java/lang/String.html key` | The cache key of the resource being removed. |

### removeSpan

```
@WorkerThread
abstract void removeSpan(CacheSpan span)
```

Removes a cached `https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan` from the cache, deleting the underlying file.

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

| Parameters |
|---|---|
| `https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan span` | The `https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan` to remove. |

### startFile

```
@WorkerThread
abstract File startFile(String key, long position, long length)
```

Obtains a cache file into which data can be written. Must only be called when holding a corresponding hole `https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan` obtained from `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#startReadWrite(java.lang.String,long,long)`.

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

| Parameters |
|---|---|
| `https://developer.android.com/reference/java/lang/String.html key` | The cache key of the resource being written. |
| `long position` | The starting position in the resource from which data will be written. |
| `long length` | The length of the data being written, or `https://developer.android.com/reference/androidx/media3/common/C#LENGTH_UNSET()` if unknown. Used only to ensure that there is enough space in the cache. |

| Returns |
|---|---|
| `https://developer.android.com/reference/java/io/File.html` | The file into which data should be written. |

| Throws |
|---|---|
| `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache.CacheException` | If an error is encountered. |

### startReadWrite

```
@WorkerThread
abstract CacheSpan startReadWrite(String key, long position, long length)
```

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 `https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan` defines the file in which the data is stored. `https://developer.android.com/reference/androidx/media3/datasource/cache/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 `https://developer.android.com/reference/androidx/media3/datasource/cache/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 `https://developer.android.com/reference/androidx/media3/datasource/cache/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 `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#commitFile(java.io.File,long)`. When the caller has finished writing, it must release the lock by calling `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#releaseHoleSpan(androidx.media3.datasource.cache.CacheSpan)`.

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

| Parameters |
|---|---|
| `https://developer.android.com/reference/java/lang/String.html key` | The cache key of the resource. |
| `long position` | The starting position in the resource from which data is required. |
| `long length` | The length of the data being requested, or `https://developer.android.com/reference/androidx/media3/common/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 `https://developer.android.com/reference/androidx/media3/datasource/cache/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 `https://developer.android.com/reference/androidx/media3/common/C#LENGTH_UNSET()` when possible. |

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan` | The `https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan`. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/InterruptedException.html` | If the thread was interrupted. |
| `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache.CacheException` | If an error is encountered. |

### startReadWriteNonBlocking

```
@WorkerThread
abstract @Nullable CacheSpan startReadWriteNonBlocking(String key, long position, long length)
```

Same as `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache#startReadWrite(java.lang.String,long,long)`. However, if the cache entry is locked, then instead of blocking, this method will return null as the `https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan`.

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

| Parameters |
|---|---|
| `https://developer.android.com/reference/java/lang/String.html key` | The cache key of the resource. |
| `long position` | The starting position in the resource from which data is required. |
| `long length` | The length of the data being requested, or `https://developer.android.com/reference/androidx/media3/common/C#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 `https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan`. |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/Nullable https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan` | The `https://developer.android.com/reference/androidx/media3/datasource/cache/CacheSpan`. Or null if the cache entry is locked. |

| Throws |
|---|---|
| `https://developer.android.com/reference/androidx/media3/datasource/cache/Cache.CacheException` | If an error is encountered. |