D
- The result returned when the load is completepublic class Loader<D> extends Object
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
.
For more information about using loaders, read the Loaders developer guide.
Modifier and Type | Class and Description |
---|---|
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.OnLoadCanceledListener<D>
Interface that is implemented to discover when a Loader has been canceled
before it finished loading its data.
|
static interface |
Loader.OnLoadCompleteListener<D>
Interface that is implemented to discover when a Loader has finished
loading its data.
|
Constructor and Description |
---|
Loader(Context context)
Stores away the application context associated with context.
|
Modifier and Type | Method and Description |
---|---|
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
Loader.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.
|
protected void |
onAbandon()
Subclasses implement this to take care of being abandoned.
|
protected boolean |
onCancelLoad()
Subclasses must implement this to take care of requests to
cancelLoad() . |
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 |
registerOnLoadCanceledListener(Loader.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. |
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(Loader.OnLoadCompleteListener<D> listener)
Remove a listener that was previously added with
registerListener(int, android.content.Loader.OnLoadCompleteListener<D>) . |
void |
unregisterOnLoadCanceledListener(Loader.OnLoadCanceledListener<D> listener)
Unregisters a listener that was previously added with
registerOnLoadCanceledListener(android.content.Loader.OnLoadCanceledListener<D>) . |
public Loader(Context context)
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.context
- used to retrieve the application context.public void deliverResult(D data)
data
- the result of the loadpublic void deliverCancellation()
Loader.OnLoadCanceledListener
that the load has been canceled.
Should only be called by subclasses.
Must be called from the process's main thread.public Context getContext()
public int getId()
public void registerListener(int id, Loader.OnLoadCompleteListener<D> listener)
Must be called from the process's main thread.
public void unregisterListener(Loader.OnLoadCompleteListener<D> listener)
registerListener(int, android.content.Loader.OnLoadCompleteListener<D>)
.
Must be called from the process's main thread.public void registerOnLoadCanceledListener(Loader.OnLoadCanceledListener<D> listener)
listener
- The listener to register.public void unregisterOnLoadCanceledListener(Loader.OnLoadCanceledListener<D> listener)
registerOnLoadCanceledListener(android.content.Loader.OnLoadCanceledListener<D>)
.
Must be called from the process's main thread.listener
- The listener to unregister.public boolean isStarted()
startLoading()
has been called and no calls to stopLoading()
or
reset()
have yet been made.public boolean isAbandoned()
public boolean isReset()
reset()
has been called.public final void startLoading()
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.
protected void onStartLoading()
startLoading()
. This is not called by clients directly,
but as a result of a call to startLoading()
.public boolean cancelLoad()
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.
startLoading()
hasn't been called; returns
true otherwise. When true is returned, the task
is still running and the Loader.OnLoadCanceledListener
will be called
when the task completes.protected boolean onCancelLoad()
cancelLoad()
.
This will always be called from the process's main thread.startLoading()
hasn't been called; returns
true otherwise. When true is returned, the task
is still running and the Loader.OnLoadCanceledListener
will be called
when the task completes.public void forceLoad()
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.
protected void onForceLoad()
forceLoad()
.
This will always be called from the process's main thread.public void stopLoading()
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.
protected void onStopLoading()
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.public void abandon()
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.protected void onAbandon()
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()
.public void reset()
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.
protected void onReset()
public boolean takeContentChanged()
public void commitContentChanged()
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.public void rollbackContentChanged()
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.public void onContentChanged()
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.
public String dataToString(D data)
public String toString()
Object
toString
method returns a string that
"textually represents" this object. The result should
be a concise but informative representation that is easy for a
person to read.
It is recommended that all subclasses override this method.
The toString
method for class Object
returns a string consisting of the name of the class of which the
object is an instance, the at-sign character `@
', and
the unsigned hexadecimal representation of the hash code of the
object. In other words, this method returns a string equal to the
value of:
getClass().getName() + '@' + Integer.toHexString(hashCode())
public void dump(String prefix, FileDescriptor fd, PrintWriter writer, String[] args)
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.