core/java/android/content/ContentQueryMap.java

/*
 * Copyright (C) 2007 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.database.Cursor;
import android.os.Handler;

import java.util.HashMap;
import java.util.Map;
import java.util.Observable;

/**
 * Caches the contents of a cursor into a Map of String->ContentValues and optionally
 * keeps the cache fresh by registering for updates on the content backing the cursor. The column of
 * the database that is to be used as the key of the map is user-configurable, and the
 * ContentValues contains all columns other than the one that is designated the key.
 * <p>
 * The cursor data is accessed by row key and column name via getValue().
 */
public class ContentQueryMap extends Observable {
    private volatile Cursor mCursor;
    private String[] mColumnNames;
    private int mKeyColumn;

    private Handler mHandlerForUpdateNotifications = null;
    private boolean mKeepUpdated = false;

    private Map<String, ContentValues> mValues = null;

    private ContentObserver mContentObserver;

    /** Set when a cursor change notification is received and is cleared on a call to requery(). */
    private boolean mDirty = false;

    /**
     * Creates a ContentQueryMap that caches the content backing the cursor
     *
     * @param cursor the cursor whose contents should be cached
     * @param columnNameOfKey the column that is to be used as the key of the values map
     * @param keepUpdated true if the cursor's ContentProvider should be monitored for changes and 
     * the map updated when changes do occur
     * @param handlerForUpdateNotifications the Handler that should be used to receive
     *  notifications of changes (if requested). Normally you pass null here, but if
     *  you know that the thread that is creating this isn't a thread that can receive
     *  messages then you can create your own handler and use that here.
     */
    public ContentQueryMap(Cursor cursor, String columnNameOfKey, boolean keepUpdated,
            Handler handlerForUpdateNotifications) {
        mCursor = cursor;
        mColumnNames = mCursor.getColumnNames();
        mKeyColumn = mCursor.getColumnIndexOrThrow(columnNameOfKey);
        mHandlerForUpdateNotifications = handlerForUpdateNotifications;
        setKeepUpdated(keepUpdated);

        // If we aren't keeping the cache updated with the current state of the cursor's 
        // ContentProvider then read it once into the cache. Otherwise the cache will be filled 
        // automatically.
        if (!keepUpdated) {
            readCursorIntoCache(cursor);
        }
    }

    /**
     * Change whether or not the ContentQueryMap will register with the cursor's ContentProvider 
     * for change notifications. If you use a ContentQueryMap in an activity you should call this
     * with false in onPause(), which means you need to call it with true in onResume()
     * if want it to be kept updated.
     * @param keepUpdated if true the ContentQueryMap should be registered with the cursor's
     * ContentProvider, false otherwise
     */
    public void setKeepUpdated(boolean keepUpdated) {
        if (keepUpdated == mKeepUpdated) return;
        mKeepUpdated = keepUpdated;

        if (!mKeepUpdated) {
            mCursor.unregisterContentObserver(mContentObserver);
            mContentObserver = null;
        } else {
            if (mHandlerForUpdateNotifications == null) {
                mHandlerForUpdateNotifications = new Handler();
            }
            if (mContentObserver == null) {
                mContentObserver = new ContentObserver(mHandlerForUpdateNotifications) {
                    @Override
                    public void onChange(boolean selfChange) {
                        // If anyone is listening, we need to do this now to broadcast
                        // to the observers.  Otherwise, we'll just set mDirty and
                        // let it query lazily when they ask for the values.
                        if (countObservers() != 0) {
                            requery();
                        } else {
                            mDirty = true;
                        }
                    }
                };
            }
            mCursor.registerContentObserver(mContentObserver);
            // mark dirty, since it is possible the cursor's backing data had changed before we 
            // registered for changes
            mDirty = true;
        }
    }

    /**
     * Access the ContentValues for the row specified by rowName
     * @param rowName which row to read
     * @return the ContentValues for the row, or null if the row wasn't present in the cursor
     */
    public synchronized ContentValues getValues(String rowName) {
        if (mDirty) requery();
        return mValues.get(rowName);
    }

    /** Requeries the cursor and reads the contents into the cache */
    public void requery() {
        final Cursor cursor = mCursor;
        if (cursor == null) {
            // If mCursor is null then it means there was a requery() in flight
            // while another thread called close(), which nulls out mCursor.
            // If this happens ignore the requery() since we are closed anyways.
            return;
        }
        mDirty = false;
        if (!cursor.requery()) {
            // again, don't do anything if the cursor is already closed
            return;
        }
        readCursorIntoCache(cursor);
        setChanged();
        notifyObservers();
    }

    private synchronized void readCursorIntoCache(Cursor cursor) {
        // Make a new map so old values returned by getRows() are undisturbed.
        int capacity = mValues != null ? mValues.size() : 0;
        mValues = new HashMap<String, ContentValues>(capacity);
        while (cursor.moveToNext()) {
            ContentValues values = new ContentValues();
            for (int i = 0; i < mColumnNames.length; i++) {
                if (i != mKeyColumn) {
                    values.put(mColumnNames[i], cursor.getString(i));
                }
            }
            mValues.put(cursor.getString(mKeyColumn), values);
        }
    }

    public synchronized Map<String, ContentValues> getRows() {
        if (mDirty) requery();
        return mValues;
    }

    public synchronized void close() {
        if (mContentObserver != null) {
            mCursor.unregisterContentObserver(mContentObserver);
            mContentObserver = null;
        }
        mCursor.close();
        mCursor = null;
    }

    @Override
    protected void finalize() throws Throwable {
        if (mCursor != null) close();
        super.finalize();
    }
}