CursorLoader.java revision bef9c7a59dc020c5cdcbd555b5212ae5a10e8045 
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
17package android.content;
18
19import android.database.Cursor;
20import android.net.Uri;
21
22/**
23 * A loader that queries the {@link ContentResolver} and returns a {@link Cursor}.
24 */
25public class CursorLoader extends AsyncTaskLoader<Cursor> {
26    Cursor mCursor;
27    ForceLoadContentObserver mObserver;
28    boolean mStopped;
29    Uri mUri;
30    String[] mProjection;
31    String mSelection;
32    String[] mSelectionArgs;
33    String mSortOrder;
34
35    /* Runs on a worker thread */
36    @Override
37    public Cursor loadInBackground() {
38        Cursor cursor = getContext().getContentResolver().query(mUri, mProjection, mSelection,
39                mSelectionArgs, mSortOrder);
40        // Ensure the cursor window is filled
41        if (cursor != null) {
42            cursor.getCount();
43            cursor.registerContentObserver(mObserver);
44        }
45        return cursor;
46    }
47
48    /* Runs on the UI thread */
49    @Override
50    public void deliverResult(Cursor cursor) {
51        if (mStopped) {
52            // An async query came in while the loader is stopped
53            cursor.close();
54            return;
55        }
56        mCursor = cursor;
57        super.deliverResult(cursor);
58    }
59
60    public CursorLoader(Context context, Uri uri, String[] projection, String selection,
61            String[] selectionArgs, String sortOrder) {
62        super(context);
63        mObserver = new ForceLoadContentObserver();
64        mUri = uri;
65        mProjection = projection;
66        mSelection = selection;
67        mSelectionArgs = selectionArgs;
68        mSortOrder = sortOrder;
69    }
70
71    /**
72     * Starts an asynchronous load of the contacts list data. When the result is ready the callbacks
73     * will be called on the UI thread. If a previous load has been completed and is still valid
74     * the result may be passed to the callbacks immediately.
75     *
76     * Must be called from the UI thread
77     */
78    @Override
79    public void startLoading() {
80        mStopped = false;
81
82        if (mCursor != null) {
83            deliverResult(mCursor);
84        } else {
85            forceLoad();
86        }
87    }
88
89    /**
90     * Must be called from the UI thread
91     */
92    @Override
93    public void stopLoading() {
94        if (mCursor != null && !mCursor.isClosed()) {
95            mCursor.close();
96            mCursor = null;
97        }
98
99        // Attempt to cancel the current load task if possible.
100        cancelLoad();
101
102        // Make sure that any outstanding loads clean themselves up properly
103        mStopped = true;
104    }
105
106    @Override
107    public void onCancelled(Cursor cursor) {
108        if (cursor != null && !cursor.isClosed()) {
109            cursor.close();
110        }
111    }
112
113    @Override
114    public void destroy() {
115        // Ensure the loader is stopped
116        stopLoading();
117    }
118
119    public Uri getUri() {
120        return mUri;
121    }
122
123    public void setUri(Uri uri) {
124        mUri = uri;
125    }
126
127    public String[] getProjection() {
128        return mProjection;
129    }
130
131    public void setProjection(String[] projection) {
132        mProjection = projection;
133    }
134
135    public String getSelection() {
136        return mSelection;
137    }
138
139    public void setSelection(String selection) {
140        mSelection = selection;
141    }
142
143    public String[] getSelectionArgs() {
144        return mSelectionArgs;
145    }
146
147    public void setSelectionArgs(String[] selectionArgs) {
148        mSelectionArgs = selectionArgs;
149    }
150
151    public String getSortOrder() {
152        return mSortOrder;
153    }
154
155    public void setSortOrder(String sortOrder) {
156        mSortOrder = sortOrder;
157    }
158}
159