Java tutorial
/* * Copyright (C) 2010 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.content; import android.database.ContentObserver; import android.os.Handler; import android.util.DebugUtils; import java.io.FileDescriptor; import java.io.PrintWriter; /** * 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 {@link android.app.LoaderManager} for more detail. * * <p><b>Note on threading:</b> 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 {@link AsyncTaskLoader}) will often perform their work * in a separate thread, but when delivering their results this too should * be done on the main thread.</p> * * <p>Subclasses generally must implement at least {@link #onStartLoading()}, * {@link #onStopLoading()}, {@link #onForceLoad()}, and {@link #onReset()}.</p> * * <p>Most implementations should not derive directly from this class, but * instead inherit from {@link AsyncTaskLoader}.</p> * * <div class="special reference"> * <h3>Developer Guides</h3> * <p>For more information about using loaders, read the * <a href="{@docRoot}guide/components/loaders.html">Loaders</a> developer guide.</p> * </div> * * @param <D> The result returned when the load is complete * * @deprecated Use the <a href="{@docRoot}tools/extras/support-library.html">Support Library</a> * {@link android.support.v4.content.Loader} */ @Deprecated public class Loader<D> { int mId; OnLoadCompleteListener<D> mListener; OnLoadCanceledListener<D> mOnLoadCanceledListener; Context mContext; boolean mStarted = false; boolean mAbandoned = false; boolean mReset = true; boolean mContentChanged = false; boolean mProcessingChange = false; /** * 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. You do not normally need to use this yourself; * it is used for you by {@link CursorLoader} to take care of executing * an update when the cursor's backing data changes. * * @deprecated Use {@link android.support.v4.content.Loader.ForceLoadContentObserver} */ @Deprecated public final class ForceLoadContentObserver extends ContentObserver { public ForceLoadContentObserver() { super(new Handler()); } @Override public boolean deliverSelfNotifications() { return true; } @Override public void onChange(boolean selfChange) { onContentChanged(); } } /** * Interface that is implemented to discover when a Loader has finished * loading its data. You do not normally need to implement this yourself; * it is used in the implementation of {@link android.app.LoaderManager} * to find out when a Loader it is managing has completed so that this can * be reported to its client. This interface should only be used if a * Loader is not being used in conjunction with LoaderManager. * * @deprecated Use {@link android.support.v4.content.Loader.OnLoadCompleteListener} */ @Deprecated public interface OnLoadCompleteListener<D> { /** * Called on the thread that created the Loader when the load is complete. * * @param loader the loader that completed the load * @param data the result of the load */ public void onLoadComplete(Loader<D> loader, D data); } /** * Interface that is implemented to discover when a Loader has been canceled * before it finished loading its data. You do not normally need to implement * this yourself; it is used in the implementation of {@link android.app.LoaderManager} * to find out when a Loader it is managing has been canceled so that it * can schedule the next Loader. This interface should only be used if a * Loader is not being used in conjunction with LoaderManager. * * @deprecated Use {@link android.support.v4.content.Loader.OnLoadCanceledListener} */ @Deprecated public interface OnLoadCanceledListener<D> { /** * Called on the thread that created the Loader when the load is canceled. * * @param loader the loader that canceled the load */ public void onLoadCanceled(Loader<D> loader); } /** * 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 {@link #getContext()} to retrieve * the Loader's Context, don't use the constructor argument directly. * The Context returned by {@link #getContext} is safe to use across * Activity instances. * * @param context used to retrieve the application context. */ public Loader(Context context) { mContext = context.getApplicationContext(); } /** * 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. * * @param data the result of the load */ public void deliverResult(D data) { if (mListener != null) { mListener.onLoadComplete(this, data); } } /** * Informs the registered {@link OnLoadCanceledListener} that the load has been canceled. * Should only be called by subclasses. * * Must be called from the process's main thread. */ public void deliverCancellation() { if (mOnLoadCanceledListener != null) { mOnLoadCanceledListener.onLoadCanceled(this); } } /** * @return an application context retrieved from the Context passed to the constructor. */ public Context getContext() { return mContext; } /** * @return the ID of this loader */ public int getId() { return mId; } /** * 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. * * <p>Must be called from the process's main thread. */ public void registerListener(int id, OnLoadCompleteListener<D> listener) { if (mListener != null) { throw new IllegalStateException("There is already a listener registered"); } mListener = listener; mId = id; } /** * Remove a listener that was previously added with {@link #registerListener}. * * Must be called from the process's main thread. */ public void unregisterListener(OnLoadCompleteListener<D> listener) { if (mListener == null) { throw new IllegalStateException("No listener register"); } if (mListener != listener) { throw new IllegalArgumentException("Attempting to unregister the wrong listener"); } mListener = null; } /** * 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. * * @param listener The listener to register. */ public void registerOnLoadCanceledListener(OnLoadCanceledListener<D> listener) { if (mOnLoadCanceledListener != null) { throw new IllegalStateException("There is already a listener registered"); } mOnLoadCanceledListener = listener; } /** * Unregisters a listener that was previously added with * {@link #registerOnLoadCanceledListener}. * * Must be called from the process's main thread. * * @param listener The listener to unregister. */ public void unregisterOnLoadCanceledListener(OnLoadCanceledListener<D> listener) { if (mOnLoadCanceledListener == null) { throw new IllegalStateException("No listener register"); } if (mOnLoadCanceledListener != listener) { throw new IllegalArgumentException("Attempting to unregister the wrong listener"); } mOnLoadCanceledListener = null; } /** * Return whether this load has been started. That is, its {@link #startLoading()} * has been called and no calls to {@link #stopLoading()} or * {@link #reset()} have yet been made. */ public boolean isStarted() { return mStarted; } /** * Return whether this loader has been abandoned. In this state, the * loader <em>must not</em> report any new data, and <em>must</em> keep * its last reported data valid until it is finally reset. */ public boolean isAbandoned() { return mAbandoned; } /** * Return whether this load has been reset. That is, either the loader * has not yet been started for the first time, or its {@link #reset()} * has been called. */ public boolean isReset() { return mReset; } /** * This function will normally be called for you automatically by * {@link android.app.LoaderManager} when the associated fragment/activity * is being started. When using a Loader with {@link android.app.LoaderManager}, * you <em>must not</em> 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 {@link #stopLoading} will stop the delivery of callbacks. * * <p>This updates the Loader's internal state so that * {@link #isStarted()} and {@link #isReset()} will return the correct * values, and then calls the implementation's {@link #onStartLoading()}. * * <p>Must be called from the process's main thread. */ public final void startLoading() { mStarted = true; mReset = false; mAbandoned = false; onStartLoading(); } /** * Subclasses must implement this to take care of loading their data, * as per {@link #startLoading()}. This is not called by clients directly, * but as a result of a call to {@link #startLoading()}. */ protected void onStartLoading() { } /** * Attempt to cancel the current load task. * Must be called on the main thread of the process. * * <p>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 Returns <tt>false</tt> if the task could not be canceled, * typically because it has already completed normally, or * because {@link #startLoading()} hasn't been called; returns * <tt>true</tt> otherwise. When <tt>true</tt> is returned, the task * is still running and the {@link OnLoadCanceledListener} will be called * when the task completes. */ public boolean cancelLoad() { return onCancelLoad(); } /** * Subclasses must implement this to take care of requests to {@link #cancelLoad()}. * This will always be called from the process's main thread. * * @return Returns <tt>false</tt> if the task could not be canceled, * typically because it has already completed normally, or * because {@link #startLoading()} hasn't been called; returns * <tt>true</tt> otherwise. When <tt>true</tt> is returned, the task * is still running and the {@link OnLoadCanceledListener} will be called * when the task completes. */ protected boolean onCancelLoad() { return false; } /** * Force an asynchronous load. Unlike {@link #startLoading()} this will ignore a previously * loaded data set and load a new one. This simply calls through to the * implementation's {@link #onForceLoad()}. You generally should only call this * when the loader is started -- that is, {@link #isStarted()} returns true. * * <p>Must be called from the process's main thread. */ public void forceLoad() { onForceLoad(); } /** * Subclasses must implement this to take care of requests to {@link #forceLoad()}. * This will always be called from the process's main thread. */ protected void onForceLoad() { } /** * This function will normally be called for you automatically by * {@link android.app.LoaderManager} when the associated fragment/activity * is being stopped. When using a Loader with {@link android.app.LoaderManager}, * you <em>must not</em> call this method yourself, or you will conflict * with its management of the Loader. * * <p>Stops delivery of updates until the next time {@link #startLoading()} is called. * Implementations should <em>not</em> 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 {@link #startLoading()} is later called. * * <p>This updates the Loader's internal state so that * {@link #isStarted()} will return the correct * value, and then calls the implementation's {@link #onStopLoading()}. * * <p>Must be called from the process's main thread. */ public void stopLoading() { mStarted = false; onStopLoading(); } /** * Subclasses must implement this to take care of stopping their loader, * as per {@link #stopLoading()}. This is not called by clients directly, * but as a result of a call to {@link #stopLoading()}. * This will always be called from the process's main thread. */ protected void onStopLoading() { } /** * This function will normally be called for you automatically by * {@link android.app.LoaderManager} when restarting a Loader. When using * a Loader with {@link android.app.LoaderManager}, * you <em>must not</em> 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 {@link #reset} to have it retain its current data but not report * any new data. */ public void abandon() { mAbandoned = true; onAbandon(); } /** * Subclasses implement this to take care of being abandoned. This is * an optional intermediate state prior to {@link #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 <em>must</em> keep its last reported data valid until the final * {@link #onReset()} happens. You can retrieve the current abandoned * state with {@link #isAbandoned}. */ protected void onAbandon() { } /** * This function will normally be called for you automatically by * {@link android.app.LoaderManager} when destroying a Loader. When using * a Loader with {@link android.app.LoaderManager}, * you <em>must not</em> 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 * {@link #startLoading()} may later be called at which point it must be * able to start running again. * * <p>This updates the Loader's internal state so that * {@link #isStarted()} and {@link #isReset()} will return the correct * values, and then calls the implementation's {@link #onReset()}. * * <p>Must be called from the process's main thread. */ public void reset() { onReset(); mReset = true; mStarted = false; mAbandoned = false; mContentChanged = false; mProcessingChange = false; } /** * Subclasses must implement this to take care of resetting their loader, * as per {@link #reset()}. This is not called by clients directly, * but as a result of a call to {@link #reset()}. * This will always be called from the process's main thread. */ protected void onReset() { } /** * 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. */ public boolean takeContentChanged() { boolean res = mContentChanged; mContentChanged = false; mProcessingChange |= res; return res; } /** * Commit that you have actually fully processed a content change that * was returned by {@link #takeContentChanged}. This is for use with * {@link #rollbackContentChanged()} to handle situations where a load * is cancelled. Call this when you have completely processed a load * without it being cancelled. */ public void commitContentChanged() { mProcessingChange = false; } /** * Report that you have abandoned the processing of a content change that * was returned by {@link #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 rollbackContentChanged() { if (mProcessingChange) { onContentChanged(); } } /** * Called when {@link ForceLoadContentObserver} detects a change. The * default implementation checks to see if the loader is currently started; * if so, it simply calls {@link #forceLoad()}; otherwise, it sets a flag * so that {@link #takeContentChanged()} returns true. * * <p>Must be called from the process's main thread. */ public void onContentChanged() { if (mStarted) { forceLoad(); } else { // This loader has been stopped, so we don't want to load // new data right now... but keep track of it changing to // refresh later if we start again. mContentChanged = true; } } /** * For debugging, converts an instance of the Loader's data class to * a string that can be printed. Must handle a null data. */ public String dataToString(D data) { StringBuilder sb = new StringBuilder(64); DebugUtils.buildShortClassTag(data, sb); sb.append("}"); return sb.toString(); } @Override public String toString() { StringBuilder sb = new StringBuilder(64); DebugUtils.buildShortClassTag(this, sb); sb.append(" id="); sb.append(mId); sb.append("}"); return sb.toString(); } /** * Print the Loader's state into the given stream. * * @param prefix Text to print at the front of each line. * @param fd The raw file descriptor that the dump is being sent to. * @param writer A PrintWriter to which the dump is to be set. * @param args Additional arguments to the dump request. */ public void dump(String prefix, FileDescriptor fd, PrintWriter writer, String[] args) { writer.print(prefix); writer.print("mId="); writer.print(mId); writer.print(" mListener="); writer.println(mListener); if (mStarted || mContentChanged || mProcessingChange) { writer.print(prefix); writer.print("mStarted="); writer.print(mStarted); writer.print(" mContentChanged="); writer.print(mContentChanged); writer.print(" mProcessingChange="); writer.println(mProcessingChange); } if (mAbandoned || mReset) { writer.print(prefix); writer.print("mAbandoned="); writer.print(mAbandoned); writer.print(" mReset="); writer.println(mReset); } } }