A Pattern for Creating Custom Android Content Providers

ContentProvider Overview

The Example

How to Do It

Define the Data Model

public class ContentDescriptor {
	public static final String AUTHORITY = "demo.contentprovider.restaurant";
	private static final Uri BASE_URI = Uri.parse("content://" + AUTHORITY);
	public static final UriMatcher URI_MATCHER = buildUriMatcher();

	private ContentDescriptor(){};

	private static  UriMatcher buildUriMatcher() {
        final UriMatcher matcher = new UriMatcher(UriMatcher.NO_MATCH);
        final String authority = AUTHORITY;

        matcher.addURI(authority, Restaurant.PATH, Restaurant.PATH_TOKEN);
		matcher.addURI(authority, Restaurant.PATH_FOR_ID, Restaurant.PATH_FOR_ID_TOKEN);

        return matcher;
	}

	public static class Restaurant {
		public static final String NAME = "restaurant";

		public static final String PATH = "restaurants";
		public static final int PATH_TOKEN = 100;
		public static final String PATH_FOR_ID = "restaurants/*";
		public static final int PATH_FOR_ID_TOKEN = 200;

		public static final Uri CONTENT_URI = BASE_URI.buildUpon().appendPath(PATH).build();

		public static final String CONTENT_TYPE_DIR = "vnd.android.cursor.dir/vnd.favrestaurant.app";
		public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/vnd.favrestaurant.app";

		public static class Cols {
			public static final String ID = BaseColumns._ID; // convention
			public static final String NAME = "restaurant_name";
			public static final String ADDRESS  = "restaurant_addr";
			public static final String CITY = "restaurant_city";
			public static final String STATE = "restaurant_state";
			public static final String ZIP = "restaurant_zip";
		}

	}
}

The Database Class (SQLiteOpenHelper)

public class RestaurantDatabase extends SQLiteOpenHelper {
	private static final String DATABASE_NAME = "fav_restaurnt.db";
	private static final int DATABASE_VERSION = 2;

	public RestaurantDatabase(Context ctx){
		super(ctx, DATABASE_NAME, null, DATABASE_VERSION);
	}

	@Override
	public void onCreate(SQLiteDatabase db) {
		db.execSQL("CREATE TABLE " + ContentDescriptor.Restaurant.NAME+ " ( " +
				ContentDescriptor.Restaurant.Cols.ID + " INTEGER PRIMARY KEY AUTOINCREMENT, " +
				ContentDescriptor.Restaurant.Cols.NAME + " TEXT NOT NULL, " +
				ContentDescriptor.Restaurant.Cols.ADDRESS 	+ " TEXT , " +
				ContentDescriptor.Restaurant.Cols.CITY + " TEXT, " +
				ContentDescriptor.Restaurant.Cols.STATE + " TEXT, " +
				ContentDescriptor.Restaurant.Cols.ZIP + " TEXT, " +
				"UNIQUE (" +
					ContentDescriptor.Restaurant.Cols.ID +
				") ON CONFLICT REPLACE)"
			);
	}

	@Override
	public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
        if(oldVersion < newVersion){
        	db.execSQL("DROP TABLE IF EXISTS " + ContentDescriptor.Restaurant.NAME);
        	onCreate(db);
        }
	}

}

public class RestaurantContentProvider extends ContentProvider {
	private RestaurantDatabase restaurantDb;

	@Override
	public boolean onCreate() {
		Context ctx = getContext();
		restaurantDb = new RestaurantDatabase(ctx);
		return true;
	}

	@Override
	public String getType(Uri uri) {
		final int match = ContentDescriptor.URI_MATCHER.match(uri);
		switch(match){
		case ContentDescriptor.Restaurant.PATH_TOKEN:
			return ContentDescriptor.Restaurant.CONTENT_TYPE_DIR;
		case ContentDescriptor.Restaurant.PATH_FOR_ID_TOKEN:
			return ContentDescriptor.Restaurant.CONTENT_ITEM_TYPE;
        default:
            throw new UnsupportedOperationException ("URI " + uri + " is not supported.");
		}
	}

	@Override
	public Uri insert(Uri uri, ContentValues values) {
		SQLiteDatabase db = restaurantDb.getWritableDatabase();
		int token = ContentDescriptor.URI_MATCHER.match(uri);
		switch(token){
			case ContentDescriptor.Restaurant.PATH_TOKEN:{
				long id = db.insert(ContentDescriptor.Restaurant.NAME, null, values);
				getContext().getContentResolver().notifyChange(uri, null);
				return ContentDescriptor.Restaurant.CONTENT_URI.buildUpon().appendPath(String.valueOf(id)).build();
			}
            default: {
                throw new UnsupportedOperationException("URI: " + uri + " not supported.");
            }
		}
	}

	@Override
	public Cursor query(Uri uri, String[] projection, String selection,
			String[] selectionArgs, String sortOrder) {
		SQLiteDatabase db = restaurantDb.getReadableDatabase();
		final int match = ContentDescriptor.URI_MATCHER.match(uri);
		switch(match){
			// retrieve restaurant list
			case ContentDescriptor.Restaurant.PATH_TOKEN:{
				SQLiteQueryBuilder builder = new SQLiteQueryBuilder();
				builder.setTables(ContentDescriptor.Restaurant.NAME);
				return builder.query(db, null, null, null, null, null, null);
			}
			default: return null;
		}
	}

	@Override
	public int update(Uri uri, ContentValues values, String selection,
			String[] selectionArgs) {
		return 0;
	}

	@Override
	public int delete(Uri uri, String selection, String[] selectionArgs) {
		return 0;
	}
}

What’s going on…

• The onCreate() method is called when the provider is instantiated (by the ContentResolver class). It is, in turn, used to bootstrap the database via the RestaurantDatabase class (see above) instance db.
• The getType() method uses the ContentDescriptor.URI_MATCHER (see ContentDescriptor above) to lookup the MIME type for a given URI.
• All of the data access & update methods (including query(), insert(), update(), and delete()) take a URI parameter. The URI provides hints such as the entity (and cardinality) being queried or updated. For instance, in our example, if the URI to passed to the query() method looks like content://com.favrestaurant.contentprovider/restaurants/* the method will return all restaurant rows in the database. This is accomplished by using the ContentDescriptor.URI_MATCHER to determine how to process the URI.

Once you have all of your pieces in place, you can access the data exposed by the content provider using the ContentResolver. There are certainly more robust ways to use to access data from a ContentProvier. This write up shows the simplest (non-production ready) way of doing it. You should investigate which way works best for your use (see http://developer.android.com/guide/topics/providers/content-providers.html).

public class FavRestaurantActivity extends Activity {
	TextView txtName;
	TextView txtAddr;
	TextView txtState;
	TextView txtCity;
	TextView txtZip;

    ContentResolver contentResolver;
    Cursor cur;
    SimpleCursorAdapter adapter;

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
        ...
        contentResolver = this.getContentResolver();
    }

    @Override
    public void onStop() {
    	super.onStop();
    	if(cur != null) cur.close();
    }

    private void loadContent() {
        cur = this.getContentResolver().query(ContentDescriptor.Restaurant.CONTENT_URI, null, null, null, null);
    	...
    }

    private void saveContent(){
    	ContentValues val = new ContentValues();
    	val.put(ContentDescriptor.Restaurant.Cols.NAME, (this.txtName.getText() != null) ? this.txtName.getText().toString() : null);
    	val.put(ContentDescriptor.Restaurant.Cols.ADDRESS, (this.txtAddr.getText() != null) ? this.txtAddr.getText().toString() : null);
    	val.put(ContentDescriptor.Restaurant.Cols.CITY, (this.txtCity.getText() != null) ? this.txtCity.getText().toString() : null);
    	val.put(ContentDescriptor.Restaurant.Cols.STATE, (this.txtState.getText() != null) ? this.txtState.getText().toString() : null);
    	val.put(ContentDescriptor.Restaurant.Cols.ZIP, (this.txtZip.getText() != null) ? this.txtZip.getText().toString() : null);
    	contentResolver.insert(ContentDescriptor.Restaurant.CONTENT_URI, val);
    	loadContent();
    }
}

What is going on…

• First, let me point out that the code used above to access data from the Activity class is not optimal for production. You should optimize any io-bound code that has propensity to hang the UI by using an asynchronous task. Nevertheless, the code presented above uses an instance of ContentResolver to access data managed by the backing ContentProvider. The ContentResolver uses the URI value passed in to select the proper ContentProvider registered in the AndroidManifest.xml file (not shown).
• The saveContent() shows how you can use the Descriptor class to create an instance of ContentValues (from the ContentProvider API) to save data. Each column is mapped to its value using the ContentProvider to provide the column name.

Conclusion

This write up provides a guide for those of you, brave enough, to use the ContentProvider API directly. I have introduced the Descriptor class as a container to register meta data to describe the data element captured by the ContentProvier. The hope is to make using the ContentProvider API more organized and provide some structure when putting your own data access code together.