Any Uri in Android that begins with the content://scheme represents a resource served up by a content provider. Content providers offer data encapsulation using Uri instances as handles — you neither know nor care where the data represented by the Uri comes from, so long as it is available to you when needed. The data could be stored in a SQLite database, or in flat files, or retrieved off a device, or be stored on some far-off server accessed over the Internet.
Given a Uri, you can perform basic CRUD (create, read, update, delete) operations using a content provider. Uri instances can represent either collections or individual pieces of content. Given a collection Uri, you can create new pieces of content via insert operations. Given an instance Uri, you can read data represented by the Uri, update that data, or delete the instance outright.
Android lets you use existing content providers or create your own. This chapter covers using content providers; Chapter 28 will explain how you can serve up your own data using the content provider framework.
Pieces of Me
The simplified model of the construction of a content Uri is the scheme, the namespace of data, and, optionally, the instance identifier, all separated by slashes in URL-style notation. The scheme of a content Uri is always content://.
So, a content Uri of content://constants/5 represents the constants instance with an identifier of 5.
The combination of the scheme and the namespace is known as the “base Uri” of a content provider, or a set of data supported by a content provider. In the previous example, content://constants is the base Uri for a content provider that serves up information about “constants” (in this case, physical constants).
The base Uri can be more complicated. For example, the base Uri for contacts is content://contacts/people, as the contacts content provider may serve up other data using other base Uri values.
The base Uri represents a collection of instances. The base Uri combined with an instance identifier (e.g., 5) represents a single instance.
Most of the Android APIs expect these to be Uri objects, though in common discussion, it is simpler to think of them as strings. The Uri.parse() static method creates a Uri out of the string representation.
Getting a Handle
Where do these Uri instances come from?
The most popular starting point, if you know the type of data you want to work with, is to get the base Uri from the content provider itself in code. For example, CONTENT_URI is the base Uri for contacts represented as people — this maps to content://contacts/people. If you just need the collection, this Uri works as is; if you need an instance and know its identifier, you can call addId() on the Uri to inject it, so you have a Uri for the instance.
You might also get Uri instances handed to you from other sources, such as getting Uri handles for contacts via sub-activities responding to ACTION_PICK intents. In this case, the Uri is truly an opaque handle… unless you decide to pick it apart using the various getters on the Uri class.
You can also hard-wire literal String objects and convert them into Uri instances via Uri.parse(). For example, in Chapter 25, the sample code used an EditText with content://contacts/people pre-filled in. This isn’t an ideal solution, as the base Uri values could conceivably change over time.
Making Queries
Given a base Uri, you can run a query to return data out of the content provider related to that Uri. This has much of the feel of SQL: you specify the “columns” to return, the constraints to determine which “rows” to return, a sort order, etc. The difference is that this request is being made of a content provider, not directly of some database (e.g., SQLite).
The nexus of this is the managedQuery() method available to your activity. This method takes five parameters:
1. The base Uri of the content provider to query, or the instance Uri of a specific object to query
2. An array of properties of instances from that content provider that you want returned by the query
3. A constraint statement, functioning like a SQL WHERE clause
4. An optional set of parameters to bind into the constraint clause, replacing any ?s that appear there
5. An optional sort statement, functioning like a SQL ORDER BY clause
This method returns a Cursor object, which you can use to retrieve the data returned by the query.
“Properties” is to content providers as columns are to databases. In other words, each instance (row) returned by a query consists of a set of properties (columns), each representing some piece of data.
This will hopefully make more sense given an example.
Our content provider examples come from the ContentProvider/Constants sample application, specifically the ConstantsBrowser class:
constantsCursor = managedQuery (Provider.Constants.CONTENT_URI,
PROJECTION, null, null, null);
In the call to managedQuery(), we provide:
• The Uri passed into the activity by the caller (CONTENT_URI), in this case representing the collection of physical constants managed by the content provider
• A list of properties to retrieve (see the following code)
• Three null values, indicating that we do not need a constraint clause (the Uri represents the instance we need), nor parameters for the constraint, nor a sort order (we should only get one entry back)
private static final String[] PROJECTION = new String[] {
Provider.Constants._ID, Provider.Constants.TITLE,
Provider.Constants.VALUE};
The biggest “magic” here is the list of properties. The lineup of what properties are possible for a given content provider should be provided by the documentation (or source code) for the content provider itself. In this case, we define logical values on the Provider content provider implementation class that represent
