The usual way for content providers to provide data structures for Android applications is via a database management system (DBMS). A DBMS manages a database by providing ways for users to create databases, as well as to populate them with data via reading and writing operations.

There is a complete open source DBMS right inside the Android OS called SQLite. This is a relational DBMS (RDBMS). An RDBMS is based on relationships that can be drawn between data arranged in tables. Later in this chapter, you will see how to write data into these tables in the RDBMS.

The SQL in SQLite stands for Structured Query Language. The "Lite" or "Light" part delineates that this is a "lightweight" version of the DBMS, intended for embedded use in consumer electronics devices, and not a full blown version of SQL, as would be used on a computer system. Later, we will look briefly at how it allows you to access database data records and the data contained within their individual data fields. All you really need to know about SQLite is that it is a part of Android and that you can use it for data storage. Android takes care of the DBMS functions for you!

In a DBMS, the highest level of data storage is the database itself, which contains tables of data in rows and columns. Each table is two-dimensional, where a row is called a record. Within each record are fields, organized into columns, which contain the individual data items that make up the records. Fields can contain different data types, such as numbers, text, or even references to data that is stored somewhere else. However, each field must contain the same data type as the other fields in the same column (see Figure 10-1).

Figure 10.1. MySQL RDBMS database

Note that there can be more than one table in a database (and usually is, for both performance and organizational reasons). As long as there is a key (a unique index) for each record in each table, information for a single data entry can span more than one table. For instance, if your key or ID is 217, your personal information and phone information can be in two different tables stored under that same key value.

The content providers that are provided with the Android OS all use SQLite, because it is compact and open source, so we are going to focus on those in this chapter.

A significant number of SQLite database structures are hard-coded into Android in order to handle things that users expect from their phones and tablets, such as contact address books, camera picture storage, digital video storage, music libraries, and so forth. The most extensive of these SQLite database structures is the Contacts database.

The base-level interfaces of the android.provider package allow us to access those data structures that define the setup and personalization of each user's smartphone. Obviously, the data in each of these structures will be completely different for each user's phone.

Let's set up our Chapter10 project folder in Eclipse right now, so you can learn a little more about the Android manifest editor and how Eclipse can automate the Android manifest XML coding process for us.

Figure 10.2. Creating the Chapter10 Android project

The AndroidManifest.xml file is usually referred to as the manifest for your application, and it tells the Android OS what we intend to do with our application. It is accessed during the initial launch of your application to set up the memory for the application and to boot up any system resources or pointers (addresses to things that we are going to talk with or connect to) that are needed for the application to run successfully.

In this case, that means we will be asking Android for permission to access, and possibly even change (depending on the tags we add), one of the Android databases outlined in the previous tables. We need to get permissions to use certain areas of the OS so that Android can implement a robust level of security within its OS infrastructure.

To define permissions, use the <uses-permission> tag:

<uses-permission android:name="android.permission.READ_CONTACTS" />

This tag allows the application to READ the CONTACTS database. Read-only operations are inherently safe, as we are only looking into these databases and reading from them. A read operation is nondestructive to a database.

If we wish to change (overwrite or update, and append) data in a database, we need to use a different permission tag that tells Android that we are going to write data to an Android OS database. In this case, WRITE_CONTACTS represents the permission and database we will use. As you may have guessed, the WRITE version of the tag looks like this:

<uses-permission android:name="android.permission.WRITE_CONTACTS"/>

Permission for write operations is a bit more serious matter, due to the fact that we are now able to screw up the database. In this case, we are dealing with the smartphone user's contacts data, and we might overwrite data that was there before our app ever accessed it.

Now let's see how easy it easy to use Eclipse to add the necessary permissions. Follow these steps:

That's all there is to adding our read and write permissions. Figure 10-7 shows our AndroidManifest.xml file with the two permission tags at the bottom, before the closing tag:

<uses-permission android:name="android.permission.READ_CONTACTS"></uses-permission>
<uses-permission android:name="android.permission.WRITE_CONTACTS"></uses-permission>

Figure 10.7. The XML output for the permission additions we made in the visual editor

Now that we have permissions to read and write to the Contacts database, we can get started working with databases.

Android SQLite uses a table-based database model, where rows represent each data record and the columns represent the data fields, each with a constant type. In this way, each piece of data in each column is the same exact type or classification, and each row is a unique collection of data of these types spanning across the row.

In this example, we are going to work with the Contacts.People table. After we add some sample data to this table, it will look like Table 10-4.

The column headers are the names that are used by Android to reference the data held in each column. These are what you use in your Java code to access each field of data within each record. For example, in some Java code we will write, we will refer to People.NAME and People.NUMBER.

The column names prefaced by an underscore character (_ID and _COUNT) are data fields assigned and controlled by Android; that is, you cannot WRITE these values, but you can READ them.

Now let's add the four data records shown in Table 10-4 into our Android emulator. (If you like, you can add more than four records.) We'll do this using the utilities that come on the smartphone. Follow these steps:

First, let's add a button to our example app's main.xml file that will trigger our database query via an onClick event (as discussed in Chapter 9 regarding events processing, or, as discussed in the previous chapter).

Let's decipher exactly what is going on in this query method that we have written. Our method is declared private (meaning it operates completely inside the class that contains it) and void, as it returns no values. The first line defines a string array variable called cols and instantiates it with a new string array loaded with the value of two constants from the Contact.People table called NAME and NUMBER. These are the two data fields from which we wish to access data.

private void queryContactPhoneNumber() {
        String[] cols = new String[] {People.NAME, People.NUMBER};

The next line creates a Uri object called myContacts and sets it equal to the People.CONTENT_URI table address that we are going to query.

Uri myContacts = People.CONTENT_URI;

We then need to create a Cursor object called mqCur and assign to it the results of the call to the managedQuery() method. This method uses the myContactsUri object, the cols column references that we are going to pull data from, and three nulls (which represent more complex SQLite operations).

Cursor mqCur = managedQuery(myContacts,cols,null,null,null);

The Cursor object that is now properly populated with our managedQuery() results will be used in our iterative code, a do...while loop inside an if statement, to traverse the records of our table that managedQuery() accesses.

The if part of the statement is true when the mqCur object has been positioned at the first record of the results via the moveToFirst() method. When this happens, the contents of the if statement are executed.

if (mqCur.moveToFirst()) {

The myname and mynumber string variables are cleared by setting them to null before we enter into the do...while loop. The loop is started on the next line with a do construct containing three logical programming statements. It ends with a while() condition that says, "Move mqCur cursor object to the next record."

As long as there is a next record that can be moved to, this will equate to true. When it does not (at the end of the last record in the results), it will equate to false and drop out of the loop, which will cease to function, just as we intended. In other words, as long as there is another record to process, we'll do another run of the code in the loop.

do {
                ...
            } while (mqCur.moveToNext());

Now let's look at the three things done in the do...while loop while there are records to read.

First, we set the myname variable to the value of the data that is found in the current record of the results (on the first loop entry, this is the first record; on the second loop entry, this is the second; and so on).

myname = mqCur.getString(mqCur.getColumnIndex(People.NAME));

We do this via two methods of the mqCurCursor object:

We repeat the process in the next line of code for mynumber using People.NUMBER. It is also held in a string format, so you can use dashes or whatever you like between the numbers.

mynumber = mqCur.getString(mqCur.getColumnIndex(People.NUMBER));

Once our myname and mynumber string variables are loaded with the data values from the database record, we call our familiar Toast widget and display the record on the screen. Notice in this version of the Toast widget we get a little more advanced than just passing a text string in the second argument of the makeText() method. Here, we use our two variables (which contain text strings) and concatenate them (attach them) to a " " space character using the + operator (used for joining strings together):

Toast.makeText(this, myname + " " + mynumber, Toast.LENGTH_SHORT).show();

Note that this could also be written in two lines of code:

Toast.makeText(this, myname + " " + mynumber, Toast.LENGTH_SHORT);
Toast.show();

Now right-click your Chapter10 folder and choose Run As

Figure 10.13. Running a query in the Android 1.5 emulator

Now you'll see how to add new content to a content provider database. Here, we will add a new contact name and phone number to the Contacts database.

We make sure that the addContactPhoneNumber() private method is declared with the correct parameters, as follows:

private void addContactPhoneNumber(String newName, String newPhone) {

This is a bit different from our queryContactPhoneNumber() method, as we are passing the method two string parameters: a name and a phone number. Since the addContactPhoneNumber() method does not return any values, it is still a void method and is declared as such, just like the others.

Now we are ready to write the code that will add a new name and phone number to the Contacts database. The first thing that we need to do is to create a ContentValues object called myContact that defines the table, column, and data values that need to be passed into the content provider. Since this is a new class that we are using in our code, we also need to add a statement to the end of our list of import statements (see Figure 10-16).

import android.content.ContentValues;

After we do that, we can instantiate a new ContentValues object called myContact via the following declaration:

ContentValues myContact = new ContentValues();

Immediately after that, we need to configure that object with a data pair via the put() method. This loads the ContentValues object with the table (People), the column (or field of data to operate on) NAME, and the string variable with the name in it, newName.

myContact.put(People.NAME, newName);

Next, we use the getContentResolver() method to insert the myContactContentValues object into the People table, which is at the location specified by CONTENT_URI constant we discussed earlier in the chapter:

addUri = getContentResolver().insert(People.CONTENT_URI, myContact);

This writes the newName variable that we loaded into our myContactContentValues object into the People.NAME database column that we specified in the same object. So, now our newName variable passed to our method has been taken care of, and we just need to do the same thing for our newNumber data variable. Then we will be finished. After this call, addUri will hold the location of the newly inserted record.

The next line of code declares a Uri object named contentUri that appends the People.Phones.CONTENT_DIRECTORY onto the addUri and creates a new, more detailed URI object for the next query. (We are basically setting the location of where to add the phone number by using the location of the new name record as a reference.) Now all we need to do is change the data in the myContactContentValues object for the final data-insertion operation.

Uri contentUri = Uri.withAppendedPath(addUri, People.Phones.CONTENT_DIRECTORY);

The first thing we want to do to the myContact object is to clear it, or basically turn it into an empty object with a clean slate. Then, in the next two lines, we use the put() method to load the myContactContentValues object with the URI and table and column values for the phone number field that we wish to write, and the newPhone phone number string variable data (415-555-7654), using the following lines of code:

myContact.clear();
myContact.put(People.Phones.TYPE, People.TYPE_MOBILE);
myContact.put(People.NUMBER, newPhone);

Finally, we call our powerhouse getContentResolver() method to go into our content provider and insert the phone number data into the correct table and data column (data field) location. This is done with the following code:

changeUri = getContentResolver().insert(contentUri, myContact);

Once our data record is written by the two getContentResolver() operations, we can send a Toast to our users in the usual way, telling them that the write has been performed.

Toast.makeText(this, "New Contact: " + newName + " " + newPhone, Toast.LENGTH_SHORT);

Figure 10-16 shows the code as it appears in Eclipse with the import statement, two global Uri object variables declared, and our addContactPhoneNumber() method highlighted.

Figure 10.16. Writing the Java code for our AddContactPhoneNumber method

We declared the two addUri and changeUri URI objects at the top of our code outside all of our methods so that they can be used in any of the methods in this class. We will be using them in other methods later in this chapter, so we've made them available for that purpose.

Now right-click your Chapter10 project folder and select Run As

Figure 10.17. Adding a contact in the Android 1.5 emulator

To see the new data for Steve Wozniak, select the Contacts icon, hit the Menu button at the bottom of the screen (on the phone), and choose the Search function. Then scroll down the list until you see the Steve Wozniak entry (highlighted on the right in Figure 10-18).

Figure 10.18. Using the Contacts editor utility in the Android 1.5 emulator

Now that you've seen how to add data to a contact provider, let's look at how to modify the content provider's data.

Changing an existing record is another write operation as far as a database is concerned, because new data is written to a database record field, and that data overwrites the existing data that was there.

Let's dive right into our usual work process to see updating content in action.

The real heavy lifting is done in our modifyPhoneNumber() method, which will update the phone number in the database record we just added. It takes a single string containing the new telephone number to replace the existing one (see Figure 10-21).Also notice in Figure 10-21 that we have collapsed our previous two methods using the "+" feature in Eclipse that allows us to expand and contract blocks of code for easier viewing of what we are working on currently. This is shown with a small red square at the left of the screenshot.

private void modifyPhoneNumber(String replacePhone) {
    if (changeUri == null) {
        Toast.makeText(this, "You need to create a new contact to update!",
                       Toast.LENGTH_LONG).show();
    } else {
        ContentValues newPhoneNumber = new ContentValues();
        newPhoneNumber.put(People.Phones.TYPE, People.TYPE_MOBILE);
        newPhoneNumber.put(People.NUMBER, replacePhone);
        getContentResolver().update(changeUri, newPhoneNumber, null,null);
        Toast.makeText(this, "Updated phone number to: " + replacePhone,
                       Toast.LENGTH_SHORT).show();
    }
}

Figure 10.21. Writing our modifyPhoneNumber() method

The modifyPhoneNumber() method uses an if...then...else programming loop structure. First, let's make sure there is data in the changeUri data object by comparing the changeUri object to null via the if (changeUri == null) construct.

if (changeUri == null) {
        Toast.makeText(this, "You need to create a new contact to update!",
                       Toast.LENGTH_LONG).show();

If this construct equates to true, we print a Toast message, saying that the add operation has not been done yet, and suggesting that the user use the add method (which we just wrote) to create the record that we want to modify.

If the (changeUri == null) equates to false, it means that the changeUri is loaded with the database and column references needed to access and modify the database record. Then we can continue and execute the database modification via four lines of code and a Toast notification that tells us what was done to the database.

getContentResolver().update(changeUri, newPhoneNumber, null,null);
        Toast.makeText(this, "Updated phone number to: " + replacePhone,
                       Toast.LENGTH_SHORT).show();
    }
}

The first line of code is the creation of the newPhoneNumberContentValues object, which will hold our database names and constants that we will use to reference the phone number field in the Contacts database.

} else {
        ContentValues newPhoneNumber = new ContentValues();

First, we load the newPhoneNumberContentValues object with the columns of data we are going to modify. In the second line of code, we state that the People.Phones.TYPE will be People.TYPE_MOBILE (that is, we are updating the mobile number). We then use the People.NUMBER database constant to say we want to update the number with the contents of the replacePhone data variable that we passed into the modifyPhoneNumber() call.

newPhoneNumber.put(People.Phones.TYPE, People.TYPE_MOBILE);
        newPhoneNumber.put(People.NUMBER, replacePhone);

In our fourth line of code inside the else section of our loop, we call the getContentResolver().update() method:

getContentResolver().update(changeUri, newPhoneNumber, null,null);

We pass it the following objects:

Finally, we add in our Toast.makeText() call to display the data we have modified once the getContentResolver().update() is complete.

Toast.makeText(this, "Updated phone number to: " + replacePhone,
                       Toast.LENGTH_SHORT).show();

Compile and run the application in the Android 1.5 emulator, and you will see our new Click to Modify the Contact in the Database button, as shown in Figure 10-22.

Figure 10.22. Modifying a contact in the Android 1.5 emulator

We can now query the database, add a record to the database, and change the phone number in an existing database record. Let's complete this tour of common database operations by adding an option to delete a record from the content provider database.

Our final example of manipulating the database demonstrates how to delete database records. We'll also make a few final changes in our main.xml UI code to make everything look a bit more professional.

This code uses an if loop that is identical to the one we constructed in the modifyPhoneNumber() method earlier.

if (changeUri == null) {
            Toast.makeText(this, "You need to create a new contact to delete!",
                           Toast.LENGTH_LONG).show();

The if statement basically says. "I our changeUri object is not loaded with the data from the add and modify operations, then tell the users that they need to create a new contact first to delete the record; otherwise, perform the following operations."

The meat of our code to delete the database record that we have created is inside the else portion of our if...then...else loop structure. It begins with a call to setContentResolver().delete() to delete the data record whose particulars are referenced in the addUri that we created in the addContactPhoneNumber() routine we coded earlier.

} else {
            getContentResolver().delete(addUri, null, null);

In this method, we are referencing the addUri, which references the Contacts database and contact name, rather than the changeUri, which references the phone number and type data fields. This is because we are deleting the top-level database record, and not just the phone number inside it.

Once we have deleted our database record via the ContentResolver, we can Toast to our users a message that it has been deleted. Finally, we set the URIs to null because we have deleted the record.

Toast.makeText(this, "Deleted contact at: " + addUri.toString(),
                           Toast.LENGTH_SHORT).show();
            addUri = null;
            changeUri = null;
        }

Now let's select Run As

Figure 10.26. Running our final database application in the Android 1.5 emulator

We now have our finished database-access application. This version is spaced out much better on the screen, and it has all four database operations in place and functioning:

We have successfully written code to manipulate one of Android's internal content provider databases.