1 /*
2  * Copyright (C) 2010 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.content;
18 
19 import android.compat.annotation.UnsupportedAppUsage;
20 import android.database.Cursor;
21 import android.net.Uri;
22 import android.os.Build;
23 import android.os.CancellationSignal;
24 import android.os.OperationCanceledException;
25 
26 import java.io.FileDescriptor;
27 import java.io.PrintWriter;
28 import java.util.Arrays;
29 
30 /**
31  * A loader that queries the {@link ContentResolver} and returns a {@link Cursor}.
32  * This class implements the {@link Loader} protocol in a standard way for
33  * querying cursors, building on {@link AsyncTaskLoader} to perform the cursor
34  * query on a background thread so that it does not block the application's UI.
35  *
36  * <p>A CursorLoader must be built with the full information for the query to
37  * perform, either through the
38  * {@link #CursorLoader(Context, Uri, String[], String, String[], String)} or
39  * creating an empty instance with {@link #CursorLoader(Context)} and filling
40  * in the desired parameters with {@link #setUri(Uri)}, {@link #setSelection(String)},
41  * {@link #setSelectionArgs(String[])}, {@link #setSortOrder(String)},
42  * and {@link #setProjection(String[])}.
43  *
44  * @deprecated Use the <a href="{@docRoot}tools/extras/support-library.html">Support Library</a>
45  *      {@link androidx.loader.content.CursorLoader}
46  */
47 @Deprecated
48 public class CursorLoader extends AsyncTaskLoader<Cursor> {
49     @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
50     final ForceLoadContentObserver mObserver;
51 
52     Uri mUri;
53     String[] mProjection;
54     String mSelection;
55     String[] mSelectionArgs;
56     String mSortOrder;
57 
58     Cursor mCursor;
59     @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
60     CancellationSignal mCancellationSignal;
61 
62     /* Runs on a worker thread */
63     @Override
loadInBackground()64     public Cursor loadInBackground() {
65         synchronized (this) {
66             if (isLoadInBackgroundCanceled()) {
67                 throw new OperationCanceledException();
68             }
69             mCancellationSignal = new CancellationSignal();
70         }
71         try {
72             Cursor cursor = getContext().getContentResolver().query(mUri, mProjection, mSelection,
73                     mSelectionArgs, mSortOrder, mCancellationSignal);
74             if (cursor != null) {
75                 try {
76                     // Ensure the cursor window is filled.
77                     cursor.getCount();
78                     cursor.registerContentObserver(mObserver);
79                 } catch (RuntimeException ex) {
80                     cursor.close();
81                     throw ex;
82                 }
83             }
84             return cursor;
85         } finally {
86             synchronized (this) {
87                 mCancellationSignal = null;
88             }
89         }
90     }
91 
92     @Override
cancelLoadInBackground()93     public void cancelLoadInBackground() {
94         super.cancelLoadInBackground();
95 
96         synchronized (this) {
97             if (mCancellationSignal != null) {
98                 mCancellationSignal.cancel();
99             }
100         }
101     }
102 
103     /* Runs on the UI thread */
104     @Override
deliverResult(Cursor cursor)105     public void deliverResult(Cursor cursor) {
106         if (isReset()) {
107             // An async query came in while the loader is stopped
108             if (cursor != null) {
109                 cursor.close();
110             }
111             return;
112         }
113         Cursor oldCursor = mCursor;
114         mCursor = cursor;
115 
116         if (isStarted()) {
117             super.deliverResult(cursor);
118         }
119 
120         if (oldCursor != null && oldCursor != cursor && !oldCursor.isClosed()) {
121             oldCursor.close();
122         }
123     }
124 
125     /**
126      * Creates an empty unspecified CursorLoader.  You must follow this with
127      * calls to {@link #setUri(Uri)}, {@link #setSelection(String)}, etc
128      * to specify the query to perform.
129      */
CursorLoader(Context context)130     public CursorLoader(Context context) {
131         super(context);
132         mObserver = new ForceLoadContentObserver();
133     }
134 
135     /**
136      * Creates a fully-specified CursorLoader.  See
137      * {@link ContentResolver#query(Uri, String[], String, String[], String)
138      * ContentResolver.query()} for documentation on the meaning of the
139      * parameters.  These will be passed as-is to that call.
140      */
CursorLoader(Context context, Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder)141     public CursorLoader(Context context, Uri uri, String[] projection, String selection,
142             String[] selectionArgs, String sortOrder) {
143         super(context);
144         mObserver = new ForceLoadContentObserver();
145         mUri = uri;
146         mProjection = projection;
147         mSelection = selection;
148         mSelectionArgs = selectionArgs;
149         mSortOrder = sortOrder;
150     }
151 
152     /**
153      * Starts an asynchronous load of the data. When the result is ready the callbacks
154      * will be called on the UI thread. If a previous load has been completed and is still valid
155      * the result may be passed to the callbacks immediately.
156      *
157      * Must be called from the UI thread
158      */
159     @Override
onStartLoading()160     protected void onStartLoading() {
161         if (mCursor != null) {
162             deliverResult(mCursor);
163         }
164         if (takeContentChanged() || mCursor == null) {
165             forceLoad();
166         }
167     }
168 
169     /**
170      * Must be called from the UI thread
171      */
172     @Override
onStopLoading()173     protected void onStopLoading() {
174         // Attempt to cancel the current load task if possible.
175         cancelLoad();
176     }
177 
178     @Override
onCanceled(Cursor cursor)179     public void onCanceled(Cursor cursor) {
180         if (cursor != null && !cursor.isClosed()) {
181             cursor.close();
182         }
183     }
184 
185     @Override
onReset()186     protected void onReset() {
187         super.onReset();
188 
189         // Ensure the loader is stopped
190         onStopLoading();
191 
192         if (mCursor != null && !mCursor.isClosed()) {
193             mCursor.close();
194         }
195         mCursor = null;
196     }
197 
getUri()198     public Uri getUri() {
199         return mUri;
200     }
201 
setUri(Uri uri)202     public void setUri(Uri uri) {
203         mUri = uri;
204     }
205 
getProjection()206     public String[] getProjection() {
207         return mProjection;
208     }
209 
setProjection(String[] projection)210     public void setProjection(String[] projection) {
211         mProjection = projection;
212     }
213 
getSelection()214     public String getSelection() {
215         return mSelection;
216     }
217 
setSelection(String selection)218     public void setSelection(String selection) {
219         mSelection = selection;
220     }
221 
getSelectionArgs()222     public String[] getSelectionArgs() {
223         return mSelectionArgs;
224     }
225 
setSelectionArgs(String[] selectionArgs)226     public void setSelectionArgs(String[] selectionArgs) {
227         mSelectionArgs = selectionArgs;
228     }
229 
getSortOrder()230     public String getSortOrder() {
231         return mSortOrder;
232     }
233 
setSortOrder(String sortOrder)234     public void setSortOrder(String sortOrder) {
235         mSortOrder = sortOrder;
236     }
237 
238     @Override
dump(String prefix, FileDescriptor fd, PrintWriter writer, String[] args)239     public void dump(String prefix, FileDescriptor fd, PrintWriter writer, String[] args) {
240         super.dump(prefix, fd, writer, args);
241         writer.print(prefix); writer.print("mUri="); writer.println(mUri);
242         writer.print(prefix); writer.print("mProjection=");
243                 writer.println(Arrays.toString(mProjection));
244         writer.print(prefix); writer.print("mSelection="); writer.println(mSelection);
245         writer.print(prefix); writer.print("mSelectionArgs=");
246                 writer.println(Arrays.toString(mSelectionArgs));
247         writer.print(prefix); writer.print("mSortOrder="); writer.println(mSortOrder);
248         writer.print(prefix); writer.print("mCursor="); writer.println(mCursor);
249         writer.print(prefix); writer.print("mContentChanged="); writer.println(mContentChanged);
250     }
251 }
252