Loader

Artifact: androidx.media3:media3-exoplayer

Kotlin |Java

@UnstableApi
class Loader : LoaderErrorThrower

Manages the background loading of Loadables.

Summary

Nested types
`interface Loader.Callback<T : Loader.Loadable?>` A callback to be notified of `Loader` events.
`class Loader.LoadErrorAction` Action that can be taken in response to `onLoadError`.
`interface Loader.Loadable` An object that can be loaded using a `Loader`.
`interface Loader.ReleaseCallback` A callback to be notified when a `Loader` has finished being released.
`class Loader.UnexpectedLoaderException : IOException` Thrown when an unexpected exception or error is encountered during loading.

Constants
`const Loader.LoadErrorAction!`	`DONT_RETRY` Discards the failed `Loadable` and ignores any errors that have occurred.
`const Loader.LoadErrorAction!`	`DONT_RETRY_FATAL` Discards the failed `Loadable`.
`const Loader.LoadErrorAction!`	`RETRY` Retries the load using the default delay.
`const Loader.LoadErrorAction!`	`RETRY_RESET_ERROR_COUNT` Retries the load using the default delay and resets the error count.

Public constructors
`Loader(downloadExecutor: ReleasableExecutor!)` Constructs an instance.
`Loader(threadNameSuffix: String!)` Constructs an instance.

Public functions
`Unit`	`cancelLoading()` Cancels the current load.
`Unit`	`clearFatalError()` Clears any stored fatal error.
`java-static Loader.LoadErrorAction!`	`createRetryAction(resetErrorCount: Boolean, retryDelayMillis: Long)` Creates a `LoadErrorAction` for retrying with the given parameters.
`Boolean`	`hasFatalError()` Whether the last call to `startLoading` resulted in a fatal error.
`Boolean`	`isLoading()` Returns whether the loader is currently loading.
`Unit`	`maybeThrowError()` Throws a fatal error, or a non-fatal error if loading is currently backed off and the current `Loadable` has incurred a number of errors greater than the `Loader`s default minimum number of retries.
`Unit`	`maybeThrowError(minRetryCount: Int)` Throws a fatal error, or a non-fatal error if loading is currently backed off and the current `Loadable` has incurred a number of errors greater than the specified minimum number of retries.
`Unit`	`release()` Releases the loader.
`Unit`	`release(callback: Loader.ReleaseCallback?)` Releases the loader.
`Long`	`<T : Loader.Loadable?> startLoading( loadable: T!, callback: Loader.Callback<T!>!, defaultMinRetryCount: Int )` Starts loading a `Loadable`.

Constants

DONT_RETRY

const val DONT_RETRY: Loader.LoadErrorAction!

Discards the failed Loadable and ignores any errors that have occurred.

DONT_RETRY_FATAL

const val DONT_RETRY_FATAL: Loader.LoadErrorAction!

Discards the failed Loadable. The next call to maybeThrowError will throw the last load error.

RETRY

const val RETRY: Loader.LoadErrorAction!

Retries the load using the default delay.

RETRY_RESET_ERROR_COUNT

const val RETRY_RESET_ERROR_COUNT: Loader.LoadErrorAction!

Retries the load using the default delay and resets the error count.

Public constructors

Loader

Loader(downloadExecutor: ReleasableExecutor!)

Constructs an instance.

Parameters
`downloadExecutor: ReleasableExecutor!`	A `ReleasableExecutor` to run the load task. The `ReleasableExecutor` will be `released` once the loader no longer requires it for new load tasks.

Loader

Loader(threadNameSuffix: String!)

Constructs an instance.

Parameters
`threadNameSuffix: String!`	A name suffix for the loader's thread. This should be the name of the component using the loader.

Public functions

cancelLoading

fun cancelLoading(): Unit

Cancels the current load.

Throws
`java.lang.IllegalStateException`	If the loader is not currently loading.

clearFatalError

fun clearFatalError(): Unit

Clears any stored fatal error.

createRetryAction

java-static fun createRetryAction(resetErrorCount: Boolean, retryDelayMillis: Long): Loader.LoadErrorAction!

Creates a LoadErrorAction for retrying with the given parameters.

Parameters
`resetErrorCount: Boolean`	Whether the previous error count should be set to zero.
`retryDelayMillis: Long`	The number of milliseconds to wait before retrying.

Returns
`Loader.LoadErrorAction!`	A `LoadErrorAction` for retrying with the given parameters.

hasFatalError

fun hasFatalError(): Boolean

Whether the last call to startLoading resulted in a fatal error. Calling maybeThrowError will throw the fatal error.

isLoading

fun isLoading(): Boolean

Returns whether the loader is currently loading.

maybeThrowError

fun maybeThrowError(): Unit

Throws a fatal error, or a non-fatal error if loading is currently backed off and the current Loadable has incurred a number of errors greater than the Loaders default minimum number of retries. Else does nothing.

Throws
`java.io.IOException`	The error.

maybeThrowError

fun maybeThrowError(minRetryCount: Int): Unit

Throws a fatal error, or a non-fatal error if loading is currently backed off and the current Loadable has incurred a number of errors greater than the specified minimum number of retries. Else does nothing.

Parameters
`minRetryCount: Int`	A minimum retry count that must be exceeded for a non-fatal error to be thrown. Should be non-negative.

Throws
`java.io.IOException`	The error.

release

fun release(): Unit

Releases the loader. This method should be called when the loader is no longer required.

release

fun release(callback: Loader.ReleaseCallback?): Unit

Releases the loader. This method should be called when the loader is no longer required.

Parameters
`callback: Loader.ReleaseCallback?`	An optional callback to be called on the loading thread once the loader has been released.

startLoading

fun <T : Loader.Loadable?> startLoading(
    loadable: T!,
    callback: Loader.Callback<T!>!,
    defaultMinRetryCount: Int
): Long

Starts loading a Loadable.

The calling thread must be a Looper thread, which is the thread on which the Callback will be called.

Parameters
`<T : Loader.Loadable?>`	The type of the loadable.
`loadable: T!`	The `Loadable` to load.
`callback: Loader.Callback<T!>!`	A callback to be called when the load ends.
`defaultMinRetryCount: Int`	The minimum number of times the load must be retried before `maybeThrowError` will propagate an error.

Returns
`Long`	`elapsedRealtime` when the load started.

Throws
`java.lang.IllegalStateException`	If the calling thread does not have an associated `Looper`.

Loader

Summary

Nested types

Constants

Public constructors

Public functions

Constants

DONT_RETRY

DONT_RETRY_FATAL

RETRY

RETRY_RESET_ERROR_COUNT

Public constructors

Loader

Loader

Public functions

cancelLoading

clearFatalError

createRetryAction

hasFatalError

isLoading

maybeThrowError

maybeThrowError

release

release

startLoading