Added in API level 11
Deprecated in API level 28

Summary: Nested Classes | Ctors | Methods | Protected Methods | Inherited Methods

Loader

---

Kotlin |Java

public class Loader
extends Object

java.lang.Object
↳	android.content.Loader<D>

Known direct subclasses AsyncTaskLoader<D> AsyncTaskLoader<D> This class was deprecated in API level 28. Use the Support Library AsyncTaskLoader

Known indirect subclasses CursorLoader CursorLoader This class was deprecated in API level 28. Use the Support Library CursorLoader

---

This class was deprecated in API level 28.
Use the Support Library Loader

A class that performs asynchronous loading of data. While Loaders are active they should monitor the source of their data and deliver new results when the contents change. See LoaderManager for more detail.

Note on threading: Clients of loaders should as a rule perform any calls on to a Loader from the main thread of their process (that is, the thread the Activity callbacks and other things occur on). Subclasses of Loader (such as AsyncTaskLoader) will often perform their work in a separate thread, but when delivering their results this too should be done on the main thread.

Subclasses generally must implement at least onStartLoading(), onStopLoading(), onForceLoad(), and onReset().

Most implementations should not derive directly from this class, but instead inherit from AsyncTaskLoader.

Developer Guides

For more information about using loaders, read the Loaders developer guide.

Summary

Nested classes
class	Loader.ForceLoadContentObserver This class was deprecated in API level 28. Use Loader.ForceLoadContentObserver
interface	Loader.OnLoadCanceledListener<D> This interface was deprecated in API level 28. Use Loader.OnLoadCanceledListener
interface	Loader.OnLoadCompleteListener<D> This interface was deprecated in API level 28. Use Loader.OnLoadCompleteListener

Public constructors
Loader(Context context) Stores away the application context associated with context.

Public methods
void	abandon() This function will normally be called for you automatically by LoaderManager when restarting a Loader.
boolean	cancelLoad() Attempt to cancel the current load task.
void	commitContentChanged() Commit that you have actually fully processed a content change that was returned by takeContentChanged().
String	dataToString(D data) For debugging, converts an instance of the Loader's data class to a string that can be printed.
void	deliverCancellation() Informs the registered OnLoadCanceledListener that the load has been canceled.
void	deliverResult(D data) Sends the result of the load to the registered listener.
void	dump(String prefix, FileDescriptor fd, PrintWriter writer, String[] args) Print the Loader's state into the given stream.
void	forceLoad() Force an asynchronous load.
Context	getContext()
int	getId()
boolean	isAbandoned() Return whether this loader has been abandoned.
boolean	isReset() Return whether this load has been reset.
boolean	isStarted() Return whether this load has been started.
void	onContentChanged() Called when ForceLoadContentObserver detects a change.
void	registerListener(int id, OnLoadCompleteListener<D> listener) Registers a class that will receive callbacks when a load is complete.
void	registerOnLoadCanceledListener(OnLoadCanceledListener<D> listener) Registers a listener that will receive callbacks when a load is canceled.
void	reset() This function will normally be called for you automatically by LoaderManager when destroying a Loader.
void	rollbackContentChanged() Report that you have abandoned the processing of a content change that was returned by takeContentChanged() and would like to rollback to the state where there is again a pending content change.
final void	startLoading() This function will normally be called for you automatically by LoaderManager when the associated fragment/activity is being started.
void	stopLoading() This function will normally be called for you automatically by LoaderManager when the associated fragment/activity is being stopped.
boolean	takeContentChanged() Take the current flag indicating whether the loader's content had changed while it was stopped.
String	toString() Returns a string representation of the object.
void	unregisterListener(OnLoadCompleteListener<D> listener) Remove a listener that was previously added with registerListener(int, OnLoadCompleteListener).
void	unregisterOnLoadCanceledListener(OnLoadCanceledListener<D> listener) Unregisters a listener that was previously added with registerOnLoadCanceledListener(OnLoadCanceledListener).

Protected methods
void	onAbandon() Subclasses implement this to take care of being abandoned.
boolean	onCancelLoad() Subclasses must implement this to take care of requests to cancelLoad().
void	onForceLoad() Subclasses must implement this to take care of requests to forceLoad().
void	onReset() Subclasses must implement this to take care of resetting their loader, as per reset().
void	onStartLoading() Subclasses must implement this to take care of loading their data, as per startLoading().
void	onStopLoading() Subclasses must implement this to take care of stopping their loader, as per stopLoading().

Inherited methods

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Public constructors

Loader

Added in API level 11

public Loader (Context context)

Stores away the application context associated with context. Since Loaders can be used across multiple activities it's dangerous to store the context directly; always use getContext() to retrieve the Loader's Context, don't use the constructor argument directly. The Context returned by getContext() is safe to use across Activity instances.

Parameters
context	Context: used to retrieve the application context.

Public methods

abandon

Added in API level 11

public void abandon ()

This function will normally be called for you automatically by LoaderManager when restarting a Loader. When using a Loader with LoaderManager, you must not call this method yourself, or you will conflict with its management of the Loader. Tell the Loader that it is being abandoned. This is called prior to reset() to have it retain its current data but not report any new data.

cancelLoad

Added in API level 16
Deprecated in API level 28

public boolean cancelLoad ()

Attempt to cancel the current load task. Must be called on the main thread of the process.

Cancellation is not an immediate operation, since the load is performed in a background thread. If there is currently a load in progress, this method requests that the load be canceled, and notes this is the case; once the background thread has completed its work its remaining state will be cleared. If another load request comes in during this time, it will be held until the canceled load is complete.

Returns
boolean	Returns false if the task could not be canceled, typically because it has already completed normally, or because startLoading() hasn't been called; returns true otherwise. When true is returned, the task is still running and the OnLoadCanceledListener will be called when the task completes.

commitContentChanged

Added in API level 18
Deprecated in API level 28

public void commitContentChanged ()

Commit that you have actually fully processed a content change that was returned by takeContentChanged(). This is for use with rollbackContentChanged() to handle situations where a load is cancelled. Call this when you have completely processed a load without it being cancelled.

dataToString

Added in API level 11

public String dataToString (D data)

For debugging, converts an instance of the Loader's data class to a string that can be printed. Must handle a null data.

Parameters
data	D

Returns
String

deliverCancellation

Added in API level 16
Deprecated in API level 28

public void deliverCancellation ()

Informs the registered OnLoadCanceledListener that the load has been canceled. Should only be called by subclasses. Must be called from the process's main thread.

deliverResult

Added in API level 11

public void deliverResult (D data)

Sends the result of the load to the registered listener. Should only be called by subclasses. Must be called from the process's main thread.

Parameters
data	D: the result of the load

dump

Added in API level 11

public void dump (String prefix, 
                FileDescriptor fd, 
                PrintWriter writer, 
                String[] args)

Print the Loader's state into the given stream.

Parameters
prefix	String: Text to print at the front of each line.
fd	FileDescriptor: The raw file descriptor that the dump is being sent to.
writer	PrintWriter: A PrintWriter to which the dump is to be set.
args	String: Additional arguments to the dump request.

forceLoad

Added in API level 11

public void forceLoad ()

Force an asynchronous load. Unlike startLoading() this will ignore a previously loaded data set and load a new one. This simply calls through to the implementation's onForceLoad(). You generally should only call this when the loader is started -- that is, isStarted() returns true.

Must be called from the process's main thread.

getContext

Added in API level 11

public Context getContext ()

Returns
Context	an application context retrieved from the Context passed to the constructor.

getId

Added in API level 11

public int getId ()

Returns
int	the ID of this loader

isAbandoned

Added in API level 11

public boolean isAbandoned ()

Return whether this loader has been abandoned. In this state, the loader must not report any new data, and must keep its last reported data valid until it is finally reset.

Returns
boolean

isReset

Added in API level 11

public boolean isReset ()

Return whether this load has been reset. That is, either the loader has not yet been started for the first time, or its reset() has been called.

Returns
boolean

isStarted

Added in API level 11

public boolean isStarted ()

Return whether this load has been started. That is, its startLoading() has been called and no calls to stopLoading() or reset() have yet been made.

Returns
boolean

onContentChanged

Added in API level 11

public void onContentChanged ()

Called when ForceLoadContentObserver detects a change. The default implementation checks to see if the loader is currently started; if so, it simply calls forceLoad(); otherwise, it sets a flag so that takeContentChanged() returns true.

Must be called from the process's main thread.

registerListener

Added in API level 11

public void registerListener (int id, 
                OnLoadCompleteListener<D> listener)

Registers a class that will receive callbacks when a load is complete. The callback will be called on the process's main thread so it's safe to pass the results to widgets.

Must be called from the process's main thread.

Parameters
id	int
listener	OnLoadCompleteListener

registerOnLoadCanceledListener

Added in API level 16
Deprecated in API level 28

public void registerOnLoadCanceledListener (OnLoadCanceledListener<D> listener)

Registers a listener that will receive callbacks when a load is canceled. The callback will be called on the process's main thread so it's safe to pass the results to widgets. Must be called from the process's main thread.

Parameters
listener	OnLoadCanceledListener: The listener to register.

reset

Added in API level 11

public void reset ()

This function will normally be called for you automatically by LoaderManager when destroying a Loader. When using a Loader with LoaderManager, you must not call this method yourself, or you will conflict with its management of the Loader. Resets the state of the Loader. The Loader should at this point free all of its resources, since it may never be called again; however, its startLoading() may later be called at which point it must be able to start running again.

This updates the Loader's internal state so that isStarted() and isReset() will return the correct values, and then calls the implementation's onReset().

Must be called from the process's main thread.

rollbackContentChanged

Added in API level 18
Deprecated in API level 28

public void rollbackContentChanged ()

Report that you have abandoned the processing of a content change that was returned by takeContentChanged() and would like to rollback to the state where there is again a pending content change. This is to handle the case where a data load due to a content change has been canceled before its data was delivered back to the loader.

startLoading

Added in API level 11

public final void startLoading ()

This function will normally be called for you automatically by LoaderManager when the associated fragment/activity is being started. When using a Loader with LoaderManager, you must not call this method yourself, or you will conflict with its management of the Loader. Starts an asynchronous load of the Loader's data. When the result is ready the callbacks will be called on the process's main thread. If a previous load has been completed and is still valid the result may be passed to the callbacks immediately. The loader will monitor the source of the data set and may deliver future callbacks if the source changes. Calling stopLoading() will stop the delivery of callbacks.

This updates the Loader's internal state so that isStarted() and isReset() will return the correct values, and then calls the implementation's onStartLoading().

Must be called from the process's main thread.

stopLoading

Added in API level 11

public void stopLoading ()

This function will normally be called for you automatically by LoaderManager when the associated fragment/activity is being stopped. When using a Loader with LoaderManager, you must not call this method yourself, or you will conflict with its management of the Loader.

Stops delivery of updates until the next time startLoading() is called. Implementations should not invalidate their data at this point -- clients are still free to use the last data the loader reported. They will, however, typically stop reporting new data if the data changes; they can still monitor for changes, but must not report them to the client until and if startLoading() is later called.

This updates the Loader's internal state so that isStarted() will return the correct value, and then calls the implementation's onStopLoading().

Must be called from the process's main thread.

takeContentChanged

Added in API level 11

public boolean takeContentChanged ()

Take the current flag indicating whether the loader's content had changed while it was stopped. If it had, true is returned and the flag is cleared.

Returns
boolean

toString

Added in API level 11

public String toString ()

Returns a string representation of the object.

Returns
String	a string representation of the object.

unregisterListener

Added in API level 11

public void unregisterListener (OnLoadCompleteListener<D> listener)

Remove a listener that was previously added with registerListener(int, OnLoadCompleteListener). Must be called from the process's main thread.

Parameters
listener	OnLoadCompleteListener

unregisterOnLoadCanceledListener

Added in API level 16
Deprecated in API level 28

public void unregisterOnLoadCanceledListener (OnLoadCanceledListener<D> listener)

Unregisters a listener that was previously added with registerOnLoadCanceledListener(OnLoadCanceledListener). Must be called from the process's main thread.

Parameters
listener	OnLoadCanceledListener: The listener to unregister.

Protected methods

onAbandon

Added in API level 11

protected void onAbandon ()

Subclasses implement this to take care of being abandoned. This is an optional intermediate state prior to onReset() -- it means that the client is no longer interested in any new data from the loader, so the loader must not report any further updates. However, the loader must keep its last reported data valid until the final onReset() happens. You can retrieve the current abandoned state with isAbandoned().

onCancelLoad

Added in API level 16
Deprecated in API level 28

protected boolean onCancelLoad ()

Subclasses must implement this to take care of requests to cancelLoad(). This will always be called from the process's main thread.

Returns
boolean	Returns false if the task could not be canceled, typically because it has already completed normally, or because startLoading() hasn't been called; returns true otherwise. When true is returned, the task is still running and the OnLoadCanceledListener will be called when the task completes.

onForceLoad

Added in API level 11

protected void onForceLoad ()

Subclasses must implement this to take care of requests to forceLoad(). This will always be called from the process's main thread.

onReset

Added in API level 11

protected void onReset ()

Subclasses must implement this to take care of resetting their loader, as per reset(). This is not called by clients directly, but as a result of a call to reset(). This will always be called from the process's main thread.

onStartLoading

Added in API level 11

protected void onStartLoading ()

Subclasses must implement this to take care of loading their data, as per startLoading(). This is not called by clients directly, but as a result of a call to startLoading().

onStopLoading

Added in API level 11

protected void onStopLoading ()

Subclasses must implement this to take care of stopping their loader, as per stopLoading(). This is not called by clients directly, but as a result of a call to stopLoading(). This will always be called from the process's main thread.