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

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

Constants
static final Loader.LoadErrorAction

Discards the failed Loadable and ignores any errors that have occurred.
static final Loader.LoadErrorAction

Discards the failed Loadable.
static final Loader.LoadErrorAction

Retries the load using the default delay.
static final Loader.LoadErrorAction

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

Cancels the current load.
void

Clears any stored fatal error.
static Loader.LoadErrorAction
createRetryAction(boolean resetErrorCount, long retryDelayMillis)

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

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

Releases the loader.
void

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