FileDocCategorySizeDatePackage
AsyncQueryHandler.javaAPI DocAndroid 1.5 API13050Wed May 06 22:41:54 BST 2009android.content

AsyncQueryHandler

public abstract class AsyncQueryHandler extends android.os.Handler
A helper class to help make handling asynchronous {@link ContentResolver} queries easier.

Fields Summary
private static final String
TAG
private static final boolean
localLOGV
private static final int
EVENT_ARG_QUERY
private static final int
EVENT_ARG_INSERT
private static final int
EVENT_ARG_UPDATE
private static final int
EVENT_ARG_DELETE
final WeakReference
mResolver
private static android.os.Looper
sLooper
private android.os.Handler
mWorkerThreadHandler
Constructors Summary
public AsyncQueryHandler(ContentResolver cr)

        super();
        mResolver = new WeakReference<ContentResolver>(cr);
        synchronized (AsyncQueryHandler.class) {
            if (sLooper == null) {
                HandlerThread thread = new HandlerThread("AsyncQueryWorker");
                thread.start();
                
                sLooper = thread.getLooper();
            }
        }
        mWorkerThreadHandler = createHandler(sLooper);
Methods Summary
public final voidcancelOperation(int token)
Attempts to cancel operation that has not already started. Note that there is no guarantee that the operation will be canceled. They still may result in a call to on[Query/Insert/Update/Delete]Complete after this call has completed.

param
token The token representing the operation to be canceled. If multiple operations have the same token they will all be canceled.

        mWorkerThreadHandler.removeMessages(token);
protected android.os.HandlercreateHandler(android.os.Looper looper)

        return new WorkerHandler(looper);
public voidhandleMessage(android.os.Message msg)

        WorkerArgs args = (WorkerArgs) msg.obj;

        if (localLOGV) {
            Log.d(TAG, "AsyncQueryHandler.handleMessage: msg.what=" + msg.what
                    + ", msg.arg1=" + msg.arg1);
        }

        int token = msg.what;
        int event = msg.arg1;
        
        // pass token back to caller on each callback.
        switch (event) {
            case EVENT_ARG_QUERY:
                onQueryComplete(token, args.cookie, (Cursor) args.result);
                break;

            case EVENT_ARG_INSERT:
                onInsertComplete(token, args.cookie, (Uri) args.result);
                break;

            case EVENT_ARG_UPDATE:
                onUpdateComplete(token, args.cookie, (Integer) args.result);
                break;

            case EVENT_ARG_DELETE:
                onDeleteComplete(token, args.cookie, (Integer) args.result);
                break;
        }
protected voidonDeleteComplete(int token, java.lang.Object cookie, int result)
Called when an asynchronous delete is completed.

param
token the token to identify the query, passed in from {@link #startDelete}.
param
cookie the cookie object that's passed in from {@link #startDelete}.
param
result the result returned from the delete operation

        // Empty
protected voidonInsertComplete(int token, java.lang.Object cookie, android.net.Uri uri)
Called when an asynchronous insert is completed.

param
token the token to identify the query, passed in from {@link #startInsert}.
param
cookie the cookie object that's passed in from {@link #startInsert}.
param
uri the uri returned from the insert operation.

        // Empty
protected voidonQueryComplete(int token, java.lang.Object cookie, android.database.Cursor cursor)
Called when an asynchronous query is completed.

param
token the token to identify the query, passed in from {@link #startQuery}.
param
cookie the cookie object that's passed in from {@link #startQuery}.
param
cursor The cursor holding the results from the query.

        // Empty
protected voidonUpdateComplete(int token, java.lang.Object cookie, int result)
Called when an asynchronous update is completed.

param
token the token to identify the query, passed in from {@link #startUpdate}.
param
cookie the cookie object that's passed in from {@link #startUpdate}.
param
result the result returned from the update operation

        // Empty
public final voidstartDelete(int token, java.lang.Object cookie, android.net.Uri uri, java.lang.String selection, java.lang.String[] selectionArgs)
This method begins an asynchronous delete. When the delete operation is done {@link #onDeleteComplete} is called.

param
token A token passed into {@link #onDeleteComplete} to identify the delete operation.
param
cookie An object that gets passed into {@link #onDeleteComplete}
param
uri the Uri passed to the delete operation.
param
selection the where clause.

        // Use the token as what so cancelOperations works properly
        Message msg = mWorkerThreadHandler.obtainMessage(token);
        msg.arg1 = EVENT_ARG_DELETE;

        WorkerArgs args = new WorkerArgs();
        args.handler = this;
        args.uri = uri;
        args.cookie = cookie;
        args.selection = selection;
        args.selectionArgs = selectionArgs;
        msg.obj = args;

        mWorkerThreadHandler.sendMessage(msg);
public final voidstartInsert(int token, java.lang.Object cookie, android.net.Uri uri, ContentValues initialValues)
This method begins an asynchronous insert. When the insert operation is done {@link #onInsertComplete} is called.

param
token A token passed into {@link #onInsertComplete} to identify the insert operation.
param
cookie An object that gets passed into {@link #onInsertComplete}
param
uri the Uri passed to the insert operation.
param
initialValues the ContentValues parameter passed to the insert operation.

        // Use the token as what so cancelOperations works properly
        Message msg = mWorkerThreadHandler.obtainMessage(token);
        msg.arg1 = EVENT_ARG_INSERT;

        WorkerArgs args = new WorkerArgs();
        args.handler = this;
        args.uri = uri;
        args.cookie = cookie;
        args.values = initialValues;
        msg.obj = args;

        mWorkerThreadHandler.sendMessage(msg);
public voidstartQuery(int token, java.lang.Object cookie, android.net.Uri uri, java.lang.String[] projection, java.lang.String selection, java.lang.String[] selectionArgs, java.lang.String orderBy)
This method begins an asynchronous query. When the query is done {@link #onQueryComplete} is called.

param
token A token passed into {@link #onQueryComplete} to identify the query.
param
cookie An object that gets passed into {@link #onQueryComplete}
param
uri The URI, using the content:// scheme, for the content to retrieve.
param
projection A list of which columns to return. Passing null will return all columns, which is discouraged to prevent reading data from storage that isn't going to be used.
param
selection A filter declaring which rows to return, formatted as an SQL WHERE clause (excluding the WHERE itself). Passing null will return all rows for the given URI.
param
selectionArgs You may include ?s in selection, which will be replaced by the values from selectionArgs, in the order that they appear in the selection. The values will be bound as Strings.
param
orderBy How to order the rows, formatted as an SQL ORDER BY clause (excluding the ORDER BY itself). Passing null will use the default sort order, which may be unordered.

        // Use the token as what so cancelOperations works properly
        Message msg = mWorkerThreadHandler.obtainMessage(token);
        msg.arg1 = EVENT_ARG_QUERY;

        WorkerArgs args = new WorkerArgs();
        args.handler = this;
        args.uri = uri;
        args.projection = projection;
        args.selection = selection;
        args.selectionArgs = selectionArgs;
        args.orderBy = orderBy;
        args.cookie = cookie;
        msg.obj = args;

        mWorkerThreadHandler.sendMessage(msg);
public final voidstartUpdate(int token, java.lang.Object cookie, android.net.Uri uri, ContentValues values, java.lang.String selection, java.lang.String[] selectionArgs)
This method begins an asynchronous update. When the update operation is done {@link #onUpdateComplete} is called.

param
token A token passed into {@link #onUpdateComplete} to identify the update operation.
param
cookie An object that gets passed into {@link #onUpdateComplete}
param
uri the Uri passed to the update operation.
param
values the ContentValues parameter passed to the update operation.

        // Use the token as what so cancelOperations works properly
        Message msg = mWorkerThreadHandler.obtainMessage(token);
        msg.arg1 = EVENT_ARG_UPDATE;

        WorkerArgs args = new WorkerArgs();
        args.handler = this;
        args.uri = uri;
        args.cookie = cookie;
        args.values = values;
        args.selection = selection;
        args.selectionArgs = selectionArgs;
        msg.obj = args;

        mWorkerThreadHandler.sendMessage(msg);