@UnstableApi
class Loader : LoaderErrorThrower

Manages the background loading of Loadables.

Summary

Nested types

A callback to be notified of Loader events.

Action that can be taken in response to onLoadError.
interface Loader.Loadable

An object that can be loaded using a Loader.

A callback to be notified when a Loader has finished being released.

Thrown when an unexpected exception or error is encountered during loading.

Constants
const Loader.LoadErrorAction!

Discards the failed Loadable and ignores any errors that have occurred.
const Loader.LoadErrorAction!

Discards the failed Loadable.
const Loader.LoadErrorAction!

Retries the load using the default delay.
const Loader.LoadErrorAction!

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

Cancels the current load.
Unit

Clears any stored fatal error.
java-static Loader.LoadErrorAction!
createRetryAction(resetErrorCount: Boolean, retryDelayMillis: Long)

Creates a LoadErrorAction for retrying with the given parameters.
Boolean

Whether the last call to startLoading resulted in a fatal error.
Boolean

Returns whether the loader is currently loading.
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.
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

Releases the loader.
Unit

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 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 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.