(and, where provided, the data path).
For example, a content Uri could be as simple as content://sekrits, which would refer to the collection of content held by whatever content provider was tied to the sekrits authority (e.g., SecretsProvider). Or, it could be as complex as content://sekrits/card/pin/17, which would refer to a piece of content (identified as 17) managed by the sekrits content provider that is of the data type card/pin.
Next, Some Typing
Next you need to come up with some MIME types corresponding with the content from your content provider.
Android uses both the content Uri and the MIME type as ways to identify content on the device. A collection content Uri — or, more accurately, the combination authority and data type path — should map to a pair of MIME types. One MIME type will represent the collection; the other will represent an instance. These map to the Uri patterns discussed in the previous section for no-identifier and identifier cases, respectively. As you saw in Chapters 24 and 25, you can fill a MIME type into an Intent to route the Intent to the proper activity (e.g., ACTION_PICK on a collection MIME type to call up a selection activity to pick an instance out of that collection).
The collection MIME type should be of the form vnd.X.cursor.dir/Y, where X is the name of your firm, organization, or project, and Y is a dot-delimited type name. So, for example, you might use vnd.tlagency.cursor.dir/sekrits.card.pin as the MIME type for your collection of secrets.
The instance MIME type should be of the form vnd.X.cursor.item/Y, usually for the same values of X and Y as you used for the collection MIME type (though that is not strictly required).
Step #1: Create a Provider Class
Just as an activity and intent receiver are both Java classes, so is a content provider. So, the big step in creating a content provider is crafting its Java class, with a base class of ContentProvider.
In your subclass of ContentProvider, you are responsible for implementing six methods that, when combined, perform the services that a content provider is supposed to offer to activities wishing to create, read, update, or delete content.
onCreate()
As with an activity, the main entry point to a content provider is onCreate(). Here you can do whatever initialization you want. In particular, here is where you should lazy-initialize your data store. For example, if you plan on storing your data in such-and-so directory on an SD card, with an XML file serving as a “table of contents,” you should check if that directory and XML file are there and, if not, create them so the rest of your content provider knows they are out there and available for use.
Similarly, if you have rewritten your content provider sufficiently to cause the data store to shift structure, you should check to see what structure you have now and adjust it if what you have is out-of-date. You don’t write your own “installer” program and so have no great way of determining if, when onCreate() is called, this is the first time ever for the content provider, the first time for a new release of a content provider that was upgraded in place, or just a normal startup.
If your content provider uses SQLite for storage, you can detect if your tables exist by querying on the sqlite_master table. This is useful for lazy-creating a table your content provider will need.
For example, here is the onCreate() method for Provider, from the ContentProvider/Constants sample application available in the Source Code section of http://apress.com:
@Override
public boolean onCreate() {
db = (new DatabaseHelper(getContext ())).getWritableDatabase();
return(db == null) ? false : true;
}
While that doesn’t seem all that special, the “magic” is in the private DatabaseHelper object, described in the chapter on database access.
query()
As one might expect, the query() method is where your content provider gets details on a query some activity wants to perform. It is up to you to actually process said query.
The query method gets the following as parameters:
• A Uri representing the collection or instance being queried
• A String[] representing the list of properties that should be returned
• A String representing what amounts to a SQL WHERE clause, constraining which instances should be considered for the query results
• A String[] representing values to “pour into” the WHERE clause, replacing any ? found there
• A String representing what amounts to a SQL ORDER BY clause
You are responsible for interpreting these parameters however they make sense and returning a Cursor that can be used to iterate over and access the data.
As you can imagine, these parameters are aimed toward people using a SQLite database for storage. You are welcome to ignore some of these parameters (e.g., you can elect not to try to roll your own SQL WHERE-clause parser), but you need to document that fact so activities attempt to query you only by instance Uri and not using parameters you elect not to handle.
For SQLite-backed storage providers, however, the query() method implementation should be largely boilerplate. Use a SQLiteQueryBuilder to convert the various parameters into a single SQL statement, then use query() on the builder to actually invoke the query and give you a Cursor back. The Cursor is what your query() method then returns.
For example, here is query() from Provider:
@Override
public Cursor query(Uri url, String[] projection, String selection,
String[] selectionArgs, String sort) {
