android.support.v4.content
Class Loader<D>

java.lang.Object
  android.support.v4.content.Loader<D>

Direct Known Subclasses:

AsyncTaskLoader

public class Loader<D>
extends Object

Static library support version of the framework's Loader. Used to write apps that run on platforms prior to Android 3.0. When running on Android 3.0 or above, this implementation is still used; it does not try to switch to the framework's implementation. See the framework SDK documentation for a class overview.

Nested Class Summary

class	Loader.ForceLoadContentObserver An implementation of a ContentObserver that takes care of connecting it to the Loader to have the loader re-load its data when the observer is told it has changed.
static interface	Loader.OnLoadCompleteListener<D> Interface that is implemented to discover when a Loader has finished loading its data.

Constructor Summary

Loader(android.content.Context context)
Stores away the application context associated with context.

Method Summary

void	abandon() Tell the Loader that it is being abandoned.
String	dataToString(D data) For debugging, converts an instance of the Loader's data class to a string that can be printed.
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.
android.content.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.
protected void	onAbandon() Subclasses implement this to take care of being abandoned.
void	onContentChanged() Called when Loader.ForceLoadContentObserver detects a change.
protected void	onForceLoad() Subclasses must implement this to take care of requests to forceLoad().
protected void	onReset() Subclasses must implement this to take care of resetting their loader, as per reset().
protected void	onStartLoading() Subclasses must implement this to take care of loading their data, as per startLoading().
protected void	onStopLoading() Subclasses must implement this to take care of stopping their loader, as per stopLoading().
void	registerListener(int id, Loader.OnLoadCompleteListener<D> listener) Registers a class that will receive callbacks when a load is complete.
void	reset() Resets the state of the Loader.
void	startLoading() Starts an asynchronous load of the Loader's data.
void	stopLoading() Stops delivery of updates until the next time startLoading() is called.
boolean	takeContentChanged() Take the current flag indicating whether the loader's content had changed while it was stopped.
String	toString()
void	unregisterListener(Loader.OnLoadCompleteListener<D> listener) Remove a listener that was previously added with registerListener(int, android.support.v4.content.Loader.OnLoadCompleteListener).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Loader

public Loader(android.content.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.

Parameters:

context - used to retrieve the application context.

Method Detail

deliverResult

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 - the result of the load

getContext

public android.content.Context getContext()

Returns:

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

getId

public int getId()

Returns:

the ID of this loader

registerListener

public void registerListener(int id,
                             Loader.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.

unregisterListener

public void unregisterListener(Loader.OnLoadCompleteListener<D> listener)

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

isStarted

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.

isAbandoned

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.

isReset

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.

startLoading

public final void startLoading()

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.

onStartLoading

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

forceLoad

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.

onForceLoad

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.

stopLoading

public void stopLoading()

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.

onStopLoading

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.

abandon

public void abandon()

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.

onAbandon

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

reset

public void reset()

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.

onReset

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.

takeContentChanged

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.

onContentChanged

public void onContentChanged()

Called when Loader.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.

dataToString

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.

toString

public String toString()

Overrides:

toString in class Object

dump

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

Print the Loader's state into the given stream.

Parameters:

prefix - Text to print at the front of each line.

fd - The raw file descriptor that the dump is being sent to.

writer - A PrintWriter to which the dump is to be set.

args - Additional arguments to the dump request.