Loader
open classLoader<D : Any!>
kotlin.Any | |
↳ | android.content.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 android.app.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
.
Summary
Nested classes | |
---|---|
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. |
|
abstract |
Interface that is implemented to discover when a Loader has been canceled before it finished loading its data. |
abstract |
Interface that is implemented to discover when a Loader has finished loading its data. |
Public constructors | |
---|---|
Stores away the application context associated with context. |
Public methods | |
---|---|
open Unit |
abandon() This function will normally be called for you automatically by |
open Boolean |
Attempt to cancel the current load task. |
open Unit |
Commit that you have actually fully processed a content change that was returned by |
open String! |
dataToString(data: D) For debugging, converts an instance of the Loader's data class to a string that can be printed. |
open Unit |
Informs the registered |
open Unit |
deliverResult(data: D) Sends the result of the load to the registered listener. |
open Unit |
dump(prefix: String!, fd: FileDescriptor!, writer: PrintWriter!, args: Array<String!>!) Print the Loader's state into the given stream. |
open Unit |
Force an asynchronous load. |
open Context! | |
open Int |
getId() |
open Boolean |
Return whether this loader has been abandoned. |
open Boolean |
isReset() Return whether this load has been reset. |
open Boolean |
Return whether this load has been started. |
open Unit |
Called when |
open Unit |
registerListener(id: Int, listener: Loader.OnLoadCompleteListener<D>!) Registers a class that will receive callbacks when a load is complete. |
open Unit |
registerOnLoadCanceledListener(listener: Loader.OnLoadCanceledListener<D>!) Registers a listener that will receive callbacks when a load is canceled. |
open Unit |
reset() This function will normally be called for you automatically by |
open Unit |
Report that you have abandoned the processing of a content change that was returned by |
Unit |
This function will normally be called for you automatically by |
open Unit |
This function will normally be called for you automatically by |
open Boolean |
Take the current flag indicating whether the loader's content had changed while it was stopped. |
open String |
toString() |
open Unit |
unregisterListener(listener: Loader.OnLoadCompleteListener<D>!) Remove a listener that was previously added with |
open Unit |
unregisterOnLoadCanceledListener(listener: Loader.OnLoadCanceledListener<D>!) Unregisters a listener that was previously added with |
Protected methods | |
---|---|
open Unit |
Subclasses implement this to take care of being abandoned. |
open Boolean |
Subclasses must implement this to take care of requests to |
open Unit |
Subclasses must implement this to take care of requests to |
open Unit |
onReset() Subclasses must implement this to take care of resetting their loader, as per |
open Unit |
Subclasses must implement this to take care of loading their data, as per |
open Unit |
Subclasses must implement this to take care of stopping their loader, as per |
Public constructors
Loader
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
open funabandon(): Unit
Deprecated: Deprecated in Java.
This function will normally be called for you automatically by android.app.LoaderManager
when restarting a Loader. When using a Loader with android.app.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
open funcancelLoad(): Boolean
Deprecated: Deprecated in Java.
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.
Return | |
---|---|
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
open funcommitContentChanged(): Unit
Deprecated: Deprecated in Java.
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
open fundataToString(data: D): String!
Deprecated: Deprecated in Java.
For debugging, converts an instance of the Loader's data class to a string that can be printed. Must handle a null data.
deliverCancellation
open fundeliverCancellation(): Unit
Deprecated: Deprecated in Java.
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
open fundeliverResult(data: D): Unit
Deprecated: Deprecated in Java.
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
open fundump(
prefix: String!,
fd: FileDescriptor!,
writer: PrintWriter!,
args: Array<String!>!
): Unit
Deprecated: Deprecated in Java.
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 |
Array<String!>!: Additional arguments to the dump request. |
forceLoad
open funforceLoad(): Unit
Deprecated: Deprecated in Java.
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
open fungetContext(): Context!
Deprecated: Deprecated in Java.
Return | |
---|---|
Context! |
an application context retrieved from the Context passed to the constructor. |
getId
open fungetId(): Int
Deprecated: Deprecated in Java.
Return | |
---|---|
Int |
the ID of this loader |
isAbandoned
open funisAbandoned(): Boolean
Deprecated: Deprecated in Java.
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
open funisReset(): Boolean
Deprecated: Deprecated in Java.
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.
isStarted
open funisStarted(): Boolean
Deprecated: Deprecated in Java.
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.
onContentChanged
open funonContentChanged(): Unit
Deprecated: Deprecated in Java.
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
open funregisterListener(
id: Int,
listener: Loader.OnLoadCompleteListener<D>!
): Unit
Deprecated: Deprecated in Java.
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.
registerOnLoadCanceledListener
open funregisterOnLoadCanceledListener(listener: Loader.OnLoadCanceledListener<D>!): Unit
Deprecated: Deprecated in Java.
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 |
Loader.OnLoadCanceledListener<D>!: The listener to register. |
reset
open funreset(): Unit
Deprecated: Deprecated in Java.
This function will normally be called for you automatically by android.app.LoaderManager
when destroying a Loader. When using a Loader with android.app.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
open funrollbackContentChanged(): Unit
Deprecated: Deprecated in Java.
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
funstartLoading(): Unit
Deprecated: Deprecated in Java.
This function will normally be called for you automatically by android.app.LoaderManager
when the associated fragment/activity is being started. When using a Loader with android.app.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
open funstopLoading(): Unit
Deprecated: Deprecated in Java.
This function will normally be called for you automatically by android.app.LoaderManager
when the associated fragment/activity is being stopped. When using a Loader with android.app.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
open funtakeContentChanged(): Boolean
Deprecated: Deprecated in Java.
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.
toString
open funtoString(): String
Deprecated: Deprecated in Java.
Return | |
---|---|
String |
a string representation of the object. |
unregisterListener
open fununregisterListener(listener: Loader.OnLoadCompleteListener<D>!): Unit
Deprecated: Deprecated in Java.
Remove a listener that was previously added with registerListener
. Must be called from the process's main thread.
unregisterOnLoadCanceledListener
open fununregisterOnLoadCanceledListener(listener: Loader.OnLoadCanceledListener<D>!): Unit
Deprecated: Deprecated in Java.
Unregisters a listener that was previously added with registerOnLoadCanceledListener
. Must be called from the process's main thread.
Parameters | |
---|---|
listener |
Loader.OnLoadCanceledListener<D>!: The listener to unregister. |
Protected methods
onAbandon
protected open funonAbandon(): Unit
Deprecated: Deprecated in Java.
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
protected open funonCancelLoad(): Boolean
Deprecated: Deprecated in Java.
Subclasses must implement this to take care of requests to cancelLoad()
. This will always be called from the process's main thread.
Return | |
---|---|
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
protected open funonForceLoad(): Unit
Deprecated: Deprecated in Java.
Subclasses must implement this to take care of requests to forceLoad()
. This will always be called from the process's main thread.
onReset
protected open funonReset(): Unit
Deprecated: Deprecated in Java.
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
protected open funonStartLoading(): Unit
Deprecated: Deprecated in Java.
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
protected open funonStopLoading(): Unit
Deprecated: Deprecated in Java.
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.