android/calendar/AsyncQueryService.java

/*
 * 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 com.android.calendar;

import com.android.calendar.AsyncQueryServiceHelper.OperationInfo;

import android.content.ContentProviderOperation;
import android.content.ContentProviderResult;
import android.content.ContentResolver;
import android.content.ContentValues;
import android.content.Context;
import android.database.Cursor;
import android.net.Uri;
import android.os.Handler;
import android.os.Message;
import android.util.Log;

import java.util.ArrayList;
import java.util.concurrent.atomic.AtomicInteger;

/**
 * A helper class that executes {@link ContentResolver} calls in a background
 * {@link android.app.Service}. This minimizes the chance of the call getting
 * lost because the caller ({@link android.app.Activity}) is killed. It is
 * designed for easy migration from {@link android.content.AsyncQueryHandler}
 * which calls the {@link ContentResolver} in a background thread. This supports
 * query/insert/update/delete and also batch mode i.e.
 * {@link ContentProviderOperation}. It also supports delay execution and cancel
 * which allows for time-limited undo. Note that there's one queue per
 * application which serializes all the calls.
 */
public class AsyncQueryService extends Handler {
    private static final String TAG = "AsyncQuery";
    static final boolean localLOGV = false;

    // Used for generating unique tokens for calls to this service
    private static AtomicInteger mUniqueToken = new AtomicInteger(0);

    private Context mContext;
    private Handler mHandler = this; // can be overridden for testing

    /**
     * Data class which holds into info of the queued operation
     */
    public static class Operation {
        static final int EVENT_ARG_QUERY = 1;
        static final int EVENT_ARG_INSERT = 2;
        static final int EVENT_ARG_UPDATE = 3;
        static final int EVENT_ARG_DELETE = 4;
        static final int EVENT_ARG_BATCH = 5;

        /**
         * unique identify for cancellation purpose
         */
        public int token;

        /**
         * One of the EVENT_ARG_ constants in the class describing the operation
         */
        public int op;

        /**
         * {@link SystemClock.elapsedRealtime()} based
         */
        public long scheduledExecutionTime;

        protected static char opToChar(int op) {
            switch (op) {
                case Operation.EVENT_ARG_QUERY:
                    return 'Q';
                case Operation.EVENT_ARG_INSERT:
                    return 'I';
                case Operation.EVENT_ARG_UPDATE:
                    return 'U';
                case Operation.EVENT_ARG_DELETE:
                    return 'D';
                case Operation.EVENT_ARG_BATCH:
                    return 'B';
                default:
                    return '?';
            }
        }

        @Override
        public String toString() {
            StringBuilder builder = new StringBuilder();
            builder.append("Operation [op=");
            builder.append(op);
            builder.append(", token=");
            builder.append(token);
            builder.append(", scheduledExecutionTime=");
            builder.append(scheduledExecutionTime);
            builder.append("]");
            return builder.toString();
        }
    }

    public AsyncQueryService(Context context) {
        mContext = context;
    }

    /**
     * returns a practically unique token for db operations
     */
    public final int getNextToken() {
        return mUniqueToken.getAndIncrement();
    }

    /**
     * Gets the last delayed operation. It is typically used for canceling.
     *
     * @return Operation object which contains of the last cancelable operation
     */
    public final Operation getLastCancelableOperation() {
        return AsyncQueryServiceHelper.getLastCancelableOperation();
    }

    /**
     * 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/Batch]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.
     */
    public final int cancelOperation(int token) {
        return AsyncQueryServiceHelper.cancelOperation(token);
    }

    /**
     * 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.
     */
    public void startQuery(int token, Object cookie, Uri uri, String[] projection,
            String selection, String[] selectionArgs, String orderBy) {
        OperationInfo info = new OperationInfo();
        info.op = Operation.EVENT_ARG_QUERY;
        info.resolver = mContext.getContentResolver();

        info.handler = mHandler;
        info.token = token;
        info.cookie = cookie;
        info.uri = uri;
        info.projection = projection;
        info.selection = selection;
        info.selectionArgs = selectionArgs;
        info.orderBy = orderBy;

        AsyncQueryServiceHelper.queueOperation(mContext, info);
    }

    /**
     * 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.
     * @param delayMillis delay in executing the operation. This operation will
     *            execute before the delayed time when another operation is
     *            added. Useful for implementing single level undo.
     */
    public void startInsert(int token, Object cookie, Uri uri, ContentValues initialValues,
            long delayMillis) {
        OperationInfo info = new OperationInfo();
        info.op = Operation.EVENT_ARG_INSERT;
        info.resolver = mContext.getContentResolver();
        info.handler = mHandler;

        info.token = token;
        info.cookie = cookie;
        info.uri = uri;
        info.values = initialValues;
        info.delayMillis = delayMillis;

        AsyncQueryServiceHelper.queueOperation(mContext, info);
    }

    /**
     * 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.
     * @param selection A filter declaring which rows to update, formatted as an
     *            SQL WHERE clause (excluding the WHERE itself). Passing null
     *            will update 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 delayMillis delay in executing the operation. This operation will
     *            execute before the delayed time when another operation is
     *            added. Useful for implementing single level undo.
     */
    public void startUpdate(int token, Object cookie, Uri uri, ContentValues values,
            String selection, String[] selectionArgs, long delayMillis) {
        OperationInfo info = new OperationInfo();
        info.op = Operation.EVENT_ARG_UPDATE;
        info.resolver = mContext.getContentResolver();
        info.handler = mHandler;

        info.token = token;
        info.cookie = cookie;
        info.uri = uri;
        info.values = values;
        info.selection = selection;
        info.selectionArgs = selectionArgs;
        info.delayMillis = delayMillis;

        AsyncQueryServiceHelper.queueOperation(mContext, info);
    }

    /**
     * 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 A filter declaring which rows to delete, formatted as an
     *            SQL WHERE clause (excluding the WHERE itself). Passing null
     *            will delete 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 delayMillis delay in executing the operation. This operation will
     *            execute before the delayed time when another operation is
     *            added. Useful for implementing single level undo.
     */
    public void startDelete(int token, Object cookie, Uri uri, String selection,
            String[] selectionArgs, long delayMillis) {
        OperationInfo info = new OperationInfo();
        info.op = Operation.EVENT_ARG_DELETE;
        info.resolver = mContext.getContentResolver();
        info.handler = mHandler;

        info.token = token;
        info.cookie = cookie;
        info.uri = uri;
        info.selection = selection;
        info.selectionArgs = selectionArgs;
        info.delayMillis = delayMillis;

        AsyncQueryServiceHelper.queueOperation(mContext, info);
    }

    /**
     * This method begins an asynchronous {@link ContentProviderOperation}. When
     * the operation is done {@link #onBatchComplete} 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 authority the authority used for the
     *            {@link ContentProviderOperation}.
     * @param cpo the {@link ContentProviderOperation} to be executed.
     * @param delayMillis delay in executing the operation. This operation will
     *            execute before the delayed time when another operation is
     *            added. Useful for implementing single level undo.
     */
    public void startBatch(int token, Object cookie, String authority,
            ArrayList<ContentProviderOperation> cpo, long delayMillis) {
        OperationInfo info = new OperationInfo();
        info.op = Operation.EVENT_ARG_BATCH;
        info.resolver = mContext.getContentResolver();
        info.handler = mHandler;

        info.token = token;
        info.cookie = cookie;
        info.authority = authority;
        info.cpo = cpo;
        info.delayMillis = delayMillis;

        AsyncQueryServiceHelper.queueOperation(mContext, info);
    }

    /**
     * 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 passed in from {@link #startQuery}.
     * @param cursor The cursor holding the results from the query.
     */
    protected void onQueryComplete(int token, Object cookie, Cursor cursor) {
        if (localLOGV) {
            Log.d(TAG, "########## default onQueryComplete");
        }
    }

    /**
     * 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.
     */
    protected void onInsertComplete(int token, Object cookie, Uri uri) {
        if (localLOGV) {
            Log.d(TAG, "########## default onInsertComplete");
        }
    }

    /**
     * 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
     */
    protected void onUpdateComplete(int token, Object cookie, int result) {
        if (localLOGV) {
            Log.d(TAG, "########## default onUpdateComplete");
        }
    }

    /**
     * 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
     */
    protected void onDeleteComplete(int token, Object cookie, int result) {
        if (localLOGV) {
            Log.d(TAG, "########## default onDeleteComplete");
        }
    }

    /**
     * Called when an asynchronous {@link ContentProviderOperation} 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 results the result returned from executing the
     *            {@link ContentProviderOperation}
     */
    protected void onBatchComplete(int token, Object cookie, ContentProviderResult[] results) {
        if (localLOGV) {
            Log.d(TAG, "########## default onBatchComplete");
        }
    }

    @Override
    public void handleMessage(Message msg) {
        OperationInfo info = (OperationInfo) msg.obj;

        int token = msg.what;
        int op = msg.arg1;

        if (localLOGV) {
            Log.d(TAG, "AsyncQueryService.handleMessage: token=" + token + ", op=" + op
                    + ", result=" + info.result);
        }

        // pass token back to caller on each callback.
        switch (op) {
            case Operation.EVENT_ARG_QUERY:
                onQueryComplete(token, info.cookie, (Cursor) info.result);
                break;

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

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

            case Operation.EVENT_ARG_DELETE:
                onDeleteComplete(token, info.cookie, (Integer) info.result);
                break;

            case Operation.EVENT_ARG_BATCH:
                onBatchComplete(token, info.cookie, (ContentProviderResult[]) info.result);
                break;
        }
    }

//    @VisibleForTesting
    protected void setTestHandler(Handler handler) {
        mHandler = handler;
    }
}