For example, here is a snippet of code from a content provider using SQLiteQueryBuilder:
@Override
public Cursor query(Uri url, String[] projection, String selection,
String[] selectionArgs, String sort) {
SQLiteQueryBuilder qb = new SQLiteQueryBuilder();
qb.setTables(getTableName());
if (isCollectionUri(url)) {
qb.setProjectionMap(getDefaultProjection());
} else {
qb.appendWhere(getIdColumnName() + "=" + url.getPathSegments().get(1));
}
String orderBy;
if (TextUtils.isEmpty(sort)) {
orderBy = getDefaultSortOrder();
} else {
orderBy = sort;
}
Cursor c = qb.query(db, projection, selection, selectionArgs,
null, null, orderBy);
c.setNotificationUri(getContext().getContentResolver(), url);
return c;
}
Content providers are explained in greater detail in Part 5 of this book, so some of this you will have to take on faith until then. Here, we see the following:
1. A SQLiteQueryBuilder is constructed.
2. It is told the table to use for the query (setTables(getTableName())).
3. It is either told the default set of columns to return (setProjectionMap()), or is given a piece of a WHERE clause to identify a particular row in the table by an identifier extracted from the Uri supplied to the query() call (appendWhere()).
4. Finally, it is told to execute the query, blending the preset values with those supplied on the call to query() (qb.query(db, projection, selection, selectionArgs, null, null, orderBy)).
Instead of having the SQLiteQueryBuilder execute the query directly, we could have called buildQuery() to have it generate and return the SQL SELECT statement we needed, which we could then execute ourselves.
Using Cursors
No matter how you execute the query, you get a Cursor back. This is the Android/SQLite edition of the database cursor, a concept used in many database systems. With the cursor, you can do the following:
• Find out how many rows are in the result set via getCount()
• Iterate over the rows via moveToFirst(), moveToNext(), and isAfterLast()
• Find out the names of the columns via getColumnNames(), convert those into column numbers via getColumnIndex(), and get values for the current row for a given column via methods like getString(), getInt(), etc.
• Re-execute the query that created the cursor, via requery()
• Release the cursor’s resources via close()
For example, here we iterate over the widgets table entries from the previous snippets:
Cursor result =
db.rawQuery("SELECT ID, name, inventory FROM widgets");
result.moveToFirst();
while (!result.isAfterLast()) {
int id = result.getInt(0);
String name = result.getString(1);
int inventory = result.getInt(2);
// do something useful with these
result.moveToNext();
}
result.close();
Making Your Own Cursors
There may be circumstances in which you want to use your own Cursor subclass rather than the stock implementation provided by Android. In those cases, you can use queryWithFactory() and rawQueryWithFactory(), which take a SQLiteDatabase.CursorFactory instance as a parameter. The factory, as one might expect, is responsible for creating new cursors via its newCursor() implementation.
Finding and implementing a valid use for this facility is left as an exercise for the reader. Suffice it to say that you should not need to create your own cursor classes much, if at all, in ordinary Android development.
Data, Data, Everywhere
If you are used to developing for other databases, you are also probably used to having tools to inspect and manipulate the contents of the database, beyond merely the database’s API. With Android’s emulator, you have two main options for this.
First, the emulator is supposed to bundle in the sqlite3 console program and makes it available from the adb shell command. Once you are in the emulator’s shell, just execute sqlite3, providing it the path to your database file. Your database file can be found at the following location:
/data/data/your.app.package/databases/your-db-name
Here your.app.package is the Java package for your application (e.g., com.commonsware.android) and your-db-name is the name of your database, as supplied to createDatabase().
Note, however, that the Android 0.9 SDK appears to be missing the sqlite3 command, though it has returned in Android 1.0.
The sqlite3 program works, and if you are used to poking around your tables using a console interface, you are welcome to use it. If you prefer something a little bit friendlier, you can always copy the SQLite database off the device onto your development machine, then use a SQLite-aware client program to putter around. Note, though, that you are working off a copy of the database; if you want your changes to go back to the device, you will need to transfer the database back over to the device.
To get the database off the device, you can use the adb pull command (or the equivalent in your IDE), which takes the path to the on-device database and the local destination as parameters. To store a modified database on the device, use adb push, which takes the local path to the database and the on-device destination as parameters.
One of the most accessible SQLite clients is the SQLite Manager[23] extension for Firefox (Figure 20-1), as it works across all platforms.