swapCursor vs changeCursor, what’s the difference?

Android, Compatibility, Development, My writings8 Comments

Implementing a ListView is probably one of the first things you do when learning Android development. At In the Pocket, we use them a lot. To make everything work as smooth as possible, all Android developer at In the Pocket agreed to use CursorAdapters as much as possible. You probably wonder why we do this?

Well, in 90% of the cases, the following flow is applicable for us:

  1. start a CursorLoader (pointing to one of our ContentProviders) and bind it to a list adapter
  2. http request to a web service
  3. parse http request response data
  4. bulk insert data into ContentProvider
  5. ContentProvider notifies all observers (in this case, the list adapter)
  6. CursorLoader automagically reloads the Cursor and updates the ListView

There is no need to parse Cursor data to corresponding Java objects. Using this kind of flow, allows you to save a lot of precious CPU time that you else would lose while parsing these objects.

If you want to see a detailed example of this kind of implementation, take a look at the following training on the Android developers website:
http://developer.android.com/guide/topics/ui/layout/listview.html

Now, the important part of this article is about 2 similar methods in the CursorAdapter class: swapCursor and changeCursor. Judging by their name, it looks like the 2 methods are doing the same, but it’s important that you know how they differ from each other.

When you are using a CursorLoader, the Cursor is managed for you. The only thing you have to do is implement the following three methods:

    // Called when a new Loader needs to be created
    public Loader<Cursor> onCreateLoader(int id, Bundle args) {
        // Now create and return a CursorLoader that will take care of
        // creating a Cursor for the data being displayed.
        return new CursorLoader(this, ContactsContract.Data.CONTENT_URI,
                PROJECTION, SELECTION, null, null);
    }

    // Called when a previously created loader has finished loading
    public void onLoadFinished(Loader<Cursor> loader, Cursor data) {
        // Swap the new cursor in.  (The framework will take care of closing the
        // old cursor once we return.)
        mAdapter.swapCursor(data);
    }

    // Called when a previously created loader is reset, making the data unavailable
    public void onLoaderReset(Loader<Cursor> loader) {
        // This is called when the last Cursor provided to onLoadFinished()
        // above is about to be closed.  We need to make sure we are no
        // longer using it.
        mAdapter.swapCursor(null);
    }

You don’t have to open and close the Cursor yourself, the loader will do this for you. This is the most important reason why you have to use swapCursor, it doesn’t close the Cursor when you swap it with another Cursor.

public Cursor swapCursor(Cursor newCursor) {
        if (newCursor == mCursor) {
            return null;
        }
        Cursor oldCursor = mCursor;
        if (oldCursor != null) {
            if (mChangeObserver != null) oldCursor.unregisterContentObserver(mChangeObserver);
            if (mDataSetObserver != null) oldCursor.unregisterDataSetObserver(mDataSetObserver);
        }
        mCursor = newCursor;
        if (newCursor != null) {
            if (mChangeObserver != null) newCursor.registerContentObserver(mChangeObserver);
            if (mDataSetObserver != null) newCursor.registerDataSetObserver(mDataSetObserver);
            mRowIDColumn = newCursor.getColumnIndexOrThrow("_id");
            mDataValid = true;
            // notify the observers about the new cursor
            notifyDataSetChanged();
        } else {
            mRowIDColumn = -1;
            mDataValid = false;
            // notify the observers about the lack of a data set
            notifyDataSetInvalidated();
        }
        return oldCursor;
    }

ChangeCursor on the other hand, first swaps the current Cursor with the new one and then closes it for you. If you use this method with your CursorLoader, your app will crash.

public void changeCursor(Cursor cursor) {
        Cursor old = swapCursor(cursor);
        if (old != null) {
            old.close();
        }
    }