CWAC LoaderEx: Taking Loaders to the Next Level

Android 3.0 introduced the Loader framework, and the Android Compatibility Library allows you to use that framework going back to Android 1.6. However, the only supplied concrete implementation of a Loader is CursorLoader, and that is only for use with a ContentProvider. Moreover, while the Loader framework handles database queries in the background, it does not help with the rest of your CRUD operations.

This LoaderEx project is designed to help fill some of those gaps. Presently, it provides a SQLiteCursorLoader, offering the same basic concept as CursorLoader, but for use with a SQLiteDatabase instead of a ContentProvider. It also supplies some boilerplate AsyncTasks to handle database inserts and deletes in the background. It also supplies:

SharedPreferencesLoader, for retrieving the default SharedPreferences object without tying up the main application thread.

This is packaged as an Android library project, though a simple JAR is also available from the Downloads section of this GitHub repository. If you are working on a native Honeycomb application (i.e., not using the Android Compatibility Library), please use the JAR — put it in your project's libs/ directory and, if you are using Eclipse, add it to your build path.

Usage: SQLiteCursorLoader

Generally speaking, you use SQLiteCursorLoader in the same fashion as you would use CursorLoader — by having your activity implement LoaderManager.LoaderCallbacks<Cursor> and calling initLoader() on the LoaderManager. Then, in your onCreateLoader() callback method, you can return a properly-constructed SQLiteCursorLoader. Everything else behaves as CursorLoader does.

Constructors

There is only one at this time, taking a SQLiteDatabase object, plus the same parameters as is used by rawQuery() on SQLiteOpenHelper — a String with your SQL query and a String[] of positional parameter values (to replace any ? you have in your query).

NOTE: Version 0.4 and previous of this component took a SQLiteDatabase as a parameter instead of a SQLiteOpenHelper. The change was made so that database creation and upgrades can occur on the background thread. Apologies for the API change.

Packages

There are two implementations of SQLiteCursorLoader, in two separate packages.

The one in com.commonsware.cwac.loaderex works using the native API Level 11+ implementation of the Loader framework.

The one in com.commonsware.cwac.loaderex.acl works using the implementation of the Loader framework from the Android Compatibility Library (ACL). You will need to have the ACL as part of your build path in addition to having the JAR or library project of LoaderEx.

In your code, you will choose the one you wish to use based upon whether you are using the ACL or not.

Database Modifications

If you use the insert(), update(), delete(), and execSQL() methods on SQLiteCursorLoader, the loader framework will automatically update you to reflect a new Cursor with the changed data. These four methods take the same parameters as they do on SQLiteDatabase.

AbstractCursorLoader

SQLiteCursorLoader itself extends an AbstractCursorLoader. AbstractCursorLoader is much of the logic from the ACL's CursorLoader, but with the actual query code abstracted out. You are welcome to make your own subclasses of AbstractCursorLoader if you are creating Cursors from other sources. Just override buildCursor() and have it return the Cursor — this method is called on a background thread and therefore is not time-limited.

Usage: SQLite*Task

THESE CLASSES ARE DEPRECATED

SQLiteInsertTask and SQLiteDeleteTask are also supplied in this library. These simply perform insert() and delete() calls on a SQLiteDatabase inside an AsyncTask, to get that work off the main application thread. These classes are designed to work on API Level 5 or higher and as such are not Loader-aware.

However, you can arrange to do post-CRUD work by extending these classes and overriding onPostExecute(Exception):

new SQLiteInsertTask(db.getWritableDatabase(),
                     "constants", DatabaseHelper.TITLE,
                     values) {
  @Override
  public void onPostExecute(Exception e) {
    getLoaderManager().restartLoader(0, null,
                                     ConstantsBrowser.this);
  }
}.execute();

The Exception will be null if everything succeeded in the background work; otherwise, it will be whatever Exception was raised by the insert() call, etc.

Notes on Threading

SQLiteDatabase itself is thread-safe, in that it manages a lock to ensure that two operations do not occur in parallel. However, that assumes you are using a single instance of SQLiteDatabase. Hence, if you are using SQLiteCursorLoader and the other classes in this project you will want to make sure that you are using a single instance of your SQLiteDatabase object. If you have more than one component using the database, that SQLiteDatabase effectively will have to be global in scope, such as by holding onto it (or its containing SQLiteOpenHelper) in a static data member.

Usage: SharedPreferencesLoader

SharedPreferencesLoader largely mirrors SQLiteCursorLoader:

There are two implementations, one for native API Level 11+ development (in the base com.commonsware.cwac.loaderex package) and one for use with the Android Support package (in the com.commonsware.cwac.loaderex.acl package).
Your activity should implement the LoaderManager.LoaderCallbacks<SharedPreferences> interface.
In your onCreateLoader() method, return an instance of SharedPreferencesLoader, which has a one-parameter constructor taking your Activity (or other Context) as the parameter.
In your onLoadFinished() method, make use of the SharedPreferences object delivered unto you.

In addition, there is a static persist() method that takes a SharedPreferences.Editor object and arranges to save those edits on a background thread, regardless of Android API level.

Dependencies

This project sometimes depends on the Android Support package (formerly the Android Compatibility Library, or ACL). If you are using it in source form as an Android library project, you will need the Android Support package. If you are using the JAR, you only need the Android Support package if you are using the .acl editions of the classes.

Version

This is version v0.5.0 of this module, meaning that it is slowly becoming more respectable.

Demo

In the demo/ sub-project you will find a sample activity that demonstrates the use of SQLiteCursorLoader. There are two implementations of this sample, one for the Android Support package and one for native API Level 11 work. There are also sample activities demonstrating the use of SharedPreferencesLoader.

Note that when you build the JAR via ant jar, the sample activity is not included, nor any resources -- only the compiled classes for the actual library are put into the JAR.

Future

Future editions of this project will add things like:

Support for query() in addition to rawQuery()-style queries
Support for synchronization on the SQLiteDatabase

License

The code in this project is licensed under the Apache Software License 2.0, per the terms of the included LICENSE file.

Questions

If you have questions regarding the use of this code, please post a question on StackOverflow tagged with commonsware and android. Be sure to indicate what CWAC module you are having issues with, and be sure to include source code and stack traces if you are encountering crashes.

If you have encountered what is clearly a bug, please post an issue. Be certain to include complete steps for reproducing the issue.

Do not ask for help via Twitter.

Release Notes

v0.5.0: switched to taking a SQLiteOpenHelper instead of a SQLiteDatabase
v0.4.0: added insert(), update(), delete(), and execSQL(); better on-change support
v0.3.0: added SharedPreferencesLoader
v0.2.0: added SQLiteInsertTask and SQLiteDeleteTask
v0.1.0: initial release

kmajeed/cwac-loaderex