Loader

Artifact: androidx.media3:media3-exoplayer

Kotlin |Java

@UnstableApi
public final class Loader implements LoaderErrorThrower

Manages the background loading of Loadables.

Summary

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

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

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

Public methods
`void`	`cancelLoading()` Cancels the current load.
`void`	`clearFatalError()` Clears any stored fatal error.
`static Loader.LoadErrorAction`	`createRetryAction(boolean resetErrorCount, long retryDelayMillis)` 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.
`void`	`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.
`void`	`maybeThrowError(int minRetryCount)` 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.
`void`	`release()` Releases the loader.
`void`	`release(@Nullable Loader.ReleaseCallback callback)` Releases the loader.
`long`	`<T extends Loader.Loadable> startLoading( T loadable, Loader.Callback<T> callback, int defaultMinRetryCount )` Starts loading a `Loadable`.

Constants

DONT_RETRY

public static final Loader.LoadErrorAction DONT_RETRY

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

DONT_RETRY_FATAL

public static final Loader.LoadErrorAction DONT_RETRY_FATAL

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

RETRY

public static final Loader.LoadErrorAction RETRY

Retries the load using the default delay.

RETRY_RESET_ERROR_COUNT

public static final Loader.LoadErrorAction RETRY_RESET_ERROR_COUNT

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

Public constructors

Loader

public Loader(ReleasableExecutor downloadExecutor)

Constructs an instance.

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

Loader

public Loader(String threadNameSuffix)

Constructs an instance.

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

Public methods

cancelLoading

public void cancelLoading()

Cancels the current load.

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

clearFatalError

public void clearFatalError()

Clears any stored fatal error.

createRetryAction

public static Loader.LoadErrorAction createRetryAction(boolean resetErrorCount, long retryDelayMillis)

Creates a LoadErrorAction for retrying with the given parameters.

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

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

hasFatalError

public boolean hasFatalError()

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

isLoading

public boolean isLoading()

Returns whether the loader is currently loading.

maybeThrowError

public void 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 Loaders default minimum number of retries. Else does nothing.

Throws
`java.io.IOException`	The error.

maybeThrowError

public void maybeThrowError(int minRetryCount)

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
`int minRetryCount`	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

public void release()

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

release

public void release(@Nullable Loader.ReleaseCallback callback)

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

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

startLoading

public long <T extends Loader.Loadable> startLoading(
    T loadable,
    Loader.Callback<T> callback,
    int defaultMinRetryCount
)

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 extends Loader.Loadable>`	The type of the loadable.
`T loadable`	The `Loadable` to load.
`Loader.Callback<T> callback`	A callback to be called when the load ends.
`int defaultMinRetryCount`	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 methods

Constants

DONT_RETRY

DONT_RETRY_FATAL

RETRY

RETRY_RESET_ERROR_COUNT

Public constructors

Loader

Loader

Public methods

cancelLoading

clearFatalError

createRetryAction

hasFatalError

isLoading

maybeThrowError

maybeThrowError

release

release

startLoading