Databases and Database Management Systems

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. SQL 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 SQLite RDBMS. If you wish to research SQLite a bit more on your own, which would be a good idea if your application needs to use databases; it has its very own website located at: www.SQLite.org.

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 an advanced computer system such as a database server.

Later in this chapter, we will take a look briefly at how Android allows you to access the Android Contacts 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 via classes that are already written for you and that do most of the work. All you have to do is learn how to use them properly, which is not a simple task, due to the database complexity (read: power) that has evolved in Android API Level 16 (also known as Android “Jelly Bean” version 4.1).

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 that same column (see Figure 10-1 ).

Note that there can be more than one table in a database (and there usually is, for both performance and for 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 using that key, called an ID and designated via the constant “_ID” in Android SQLite databases. For instance, if your key or _ID value is 217, your personal information and phone information can be in two different tables stored under that same key value.

The content provider classes that are provided with the Android OS all use SQLite because it is compact and open source, and a part of the Android OS, so we are going to focus on those in this chapter. There is also an Android library of SQLite classes that can access SQLite directly, for more advanced use. If that is of interest, there are several books regarding using SQLite libraries inside of Android that focus only on this topic.

Android Built-In Content Providers

A significant number of SQLite-based database structures are “hard-coded” into the Android OS to handle things that users expect from their phones, iTVs, e-readers, and tablets, such as contact directories, address books, calendars, camera picture storage, digital video storage, music libraries, playlists, and so forth. The most extensive of these SQLite database structures is the Contacts database, which contains many different tables (subdatabases) for contact names, phone numbers, e-mails, preferences, social media settings, and so forth. This structure is very complex, and because this book is focused on programming for Absolute Beginners, and not database theory, we will only be working with the primary contact name database, to keep it more about Java programming and Android Content Providers, rather than about database structure and theory.

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 Android device hardware. Obviously, the data within each of these data structures will be completely different for each user’s smartphone, tablet, e-reader, or iTV set.

Creating the Content Providers Example Project in Eclipse

Let’s set up our ContentProviders 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.

If you still have the EventHandling project folder open from the previous chapter, right-click that folder and select: Close Project.

1. Then select File New Project and choose Android Application Project to open the New Android Application Project series of dialogs.
2. Fill it out as follows (and shown in Figure 10-2 ).

   

   Figure 10-2 .  Creating the ContentProviders Android 4.1 project in Eclipse

   • Project name : Name the project ContentProviders.
   • Build target : Set this to Android 4.1.
   • Application name : Name the application ContentProviders.
   • Package name : Set this to sixth.example.contentproviders.
   • Create custom launcher icon : Check this box and accept the defaults in the follow-on dialogs, as we have been doing in the earlier chapters.
   • Minimum SDK version Enter 8, which matches the recommended minimum SDK version of 8, and thus supports Android 2.2 through 4.1 and thus the more modern (complex or detailed) database structures.

Defining Security Permissions

The AndroidManifest.xml file is usually referred to as the manifest for your application, and it tells the Android OS what you intend to do with your 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 need to be ready in system memory) that are needed for the application to be 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 within the previous tables. The reason that we need to get permissions to use certain areas of the OS is so that Android can implement a robust level of data 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 data from them. A read operation is thus termed to be a “nondestructive operation” to, or on, a database.

If we wish to change (overwrite or update, delete, or append to) 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 to change the Contacts database that we will be using. 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, which is why the industry terms a database Write Operation to be “destructive.” In this case, we are dealing with the Android device 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 is to use Eclipse to add the necessary permissions. Follow these steps:

1. Right-click the AndroidManifest.xml file in the Project Explorer navigation pane under your ContentProviders folder (near the bottom), as shown in Figure 10-3 , and select Open, or just hit the F3 key on the keyboard once the file is selected.

   

   Figure 10-3 .  Adding a permission in the ContentProviders manifest using the Eclipse visual editor

2. In the ContentProviders Manifest tab, click the Permissions tab at the bottom of the window (see Figure 10-3 ).
3. Click the Add … button in the right pane (also shown at left in Figure 10-3 ).
4. Select the Uses Permission entry at the bottom of the list, and then click OK (also shown on right in Figure 10-3 ; I get a lot of mileage out of my screenshots).
5. You’ll now see the uses-permission tag in the Permissions pane (see Figure 10-4 just left of center). From the drop-down menu that lists permissions on the right, select android.permission.READ_CONTACTS (see Figure 10-4 on right side). Next click the Add … button to add another Uses Permission Tag, which once you click on it will add the READ_CONTACTS Android Permission to the left pane list of tags.

   

   Figure 10-4 .  Selecting the READ_CONTACTS Permission entry from the drop-down menu

6. Selecting the Uses Permission type on the right should update the pane at the left, but currently it does not, so we go ahead and proceed to click the Add … button to add another Uses Permission option and then the WRITE_CONTACTS tag (as we did with the READ_CONTACTS just prior), which will force the visual manifest Permissions Editor to update the left pane with the proper uses-permission tag setting.
7. Once you select the WRITE_CONTACTS option from the drop-down menu, then click on the Up button to add the android.permission.WRITE_CONTACTS option (see Figure 10-5 ) to the permissions list pane. Alternately you could click the Add button and then simply not add another permission if you like.

   

   Figure 10-5 .  Selecting the WRITE_CONTACTS permission and UP Button to display

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

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

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

Adding Data to the Contacts Database

Android SQLite uses a table-based database model, where rows represent each data record and the columns represent the data fields, each with a predefined constant type used in Android to access the data. 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 ContactsContract.Contacts 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 ContactsContract.Contacts.DISPLAY_NAME_PRIMARY.

The column names that are prefaced by an underscore character (_ID and _COUNT) are data fields assigned and controlled by Android; that is, you cannot WRITE to these values, you can only READ from 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 with the Android OS. Follow these steps:

1. Run the 4.1 emulator as usual by choosing Run As Android Application.

   Note  Another way to start the emulator is to select Window AVD Manager as shown in Figure 10-7 . Select your 4.1 emulator and press the Start button and then the Launch button. Any contacts you enter should be saved for later, even if you close the 4.1 emulator, unless you specify otherwise within the Launch dialog settings.

   

   Figure 10-7 .  The AVD Manager Start... and Launch buttons used to start the Android 4.1 Emulator

2. Press the Home button. You will see four icons on the bottom of the home screen (shown in Figure 10-8 on the left side) with icons signifying Dialer (Phone), Messaging, Contacts, and Browser (Globe) in that order. The middle icon opens the desktop icon holder view. The icon called Contacts on the left (second one in) is a front-end to our Contacts database, and will allow us to add in the records shown in Table 10-4 .

   

   Figure 10-8 .  Adding new contacts to the Android Contacts database via the Contacts utility

3. Click on the Contacts icon to launch the Contacts database, which is initially empty. The screen tells us that we do not yet have any contacts. Click the “Create a new contact” button to add new contacts to the Contacts database (as shown in the middle of Figure 10-8 ). In the next screen select “Keep local” because we are doing this exercise in the IDE and emulator, and we do not want to influence your real Android account.
4. On the next screen, enter the first contact name (Bill Gates) using the onscreen keypad, and use the “Next” button at the bottom right when you are done, to advance to the Phone Number entry field.
5. Add a Phone Number just to practice adding contact info, and then click the “Done” button at the top right of the screen to see the record you created. Note that you can also use the Add New option to create multiple records at one time, if you like.
6. On the Data Record Display Screen, click the back arrow at the top left of the screen (shown in the middle of Figure 10-9 ) to see all your contact records by alphabetical order.
7. Select the Add New Record Icon (a + next to a new member head icon) to continue adding the other three records (as shown in the right side of Figure 10-9 ). Notice the Toast Notification telling us we are going to create a new entry! Even the Android OS uses Toast!

   

   Figure 10-9 .  Adding a record to the Contact database

8. Repeat Steps 4 through 7 to add the three other names in Table 10-4 , and maybe a few of own if you wish. When you are done, close the 4.1 emulator, there is no need to save or exit, as records are written to the Database as you add them, as long as you left the “Wipe User Data” option unchecked in the Emulator launch dialog shown in Figure 10-7 (if you even used that more complex emulator launch methodology).

Appending to a Content Provider: Adding New Content

Now you’ll see how to add new content to a content provider database. In database terminology adding data records to the end of a database is called “appending” data records, but more important, now we’re going to the next level (albeit a destructive one) and “writing” a new database record into the database. You’ve come a long way, Baby. Next, we will add a new contact name to the ContactsContract.Contacts database.

1. First, copy and paste the first Button tag in our activity_main.xml file or use the Eclipse Graphical Layout Editor to drag a second button onto your current UI, and center it 20dp underneath the first button. The text label of the button should be set to @string/append_data (see Figure 10-14 ).

   <Button
        android:id="@ + id/button2"  
        android:layout_width="wrap_content" 
        android:layout_height="wrap_content" 
        android:layoutBelow="@ + id/button1"  
        android:layout_centerHorizontal="true"  
        android:layout_marginTop="20dp"  

        android:text="@string/append_data"/>

   

   Figure 10-14 .  Adding in our second button tag in activity_main.xml to use to add a new contact

2. Next let’s add in the <string> tag with a name value of append_data and its text value that specifies the text label for our second button that reads: “Click to add to Contacts Database."
3. Next, let’s add in the code to implement the second button for our UI by copying the button1 Button object declaration and the onClick event handling code and pasting it immediately underneath the existing UI code in our MainActivity class to create our database Add button.
4. Change the queryButton variable name to read: addButton, and change the R.id to point to our new button2 ID. Also, set our method call to the new addContact() method that we are going to write (see Figure 10-15 ). Here is the new code:

   Button addButton = (Button)findViewById(R.id.button2);
    
   addButton.setOnClickListener(new OnClickListener() {
      public void onClick(View arg0) {
             addContact("Steve Wozniak");
      }
   });

   Note  This line of code calls our addContact() method and passes it a new database record Primary Name data value, so that a new contact entry will be added to the ContactsContract.Contacts database.

   

   Figure 10-15 .  Adding the Java code to add in the second append data button functionality

5. Next, we are going to add the new method addContact().

       private void addContact(String newName) {
                  ContentValues myContact = new ContentValues();
                  myContact.put(RawContacts.ACCOUNT_NAME, newName);
                  myContact.put(RawContacts.ACCOUNT_TYPE, newName);
                  Uri addUri = getContentResolver().insert(RawContacts.CONTENT_URI, myContact);
                  long rawContactId = contentUris.parseId(addUri);
                  myContact.clear();
                  myContact.put(Data.RAW_CONTACT_ID, rawContactId);
                  myContact.put(Data.MIMETYPE, StructuredName.CONTENT_ITEM_TYPE);
                myContact.put(StructuredName.DISPLAY_NAME, newName);
                getContentResolver().insert(Data.CONTENT_URI, myContact);
                Toast.makeText(this, "New Contact: " + newName, 
                               Toast.LENGTH_SHORT);
       }

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

private void addContact(String newName) {

This is quite different from our queryContact() method, as we are passing the method a string parameter: a name (in this case, Steve Wozniak). Because the addContact() 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 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 needs to be passed into the content provider. Because this is a new class that we are using in our code, we also need to add an import statement to our list of import statements (see Figure 10-16 ) or have Eclipse do that for us once we type in the new ContentValues() line of code that establishes a new ContentValues() object named myContact.

import android.content.ContentValues;

After we add the import statement, 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 ContentValues object with a data pair via the put() method. This loads the ContentValues object with the table (RawContacts), the columns (or fields of data to operate on) ACCOUNT_NAME and ACCOUNT_TYPE, and the string variable with the name in it, newName.

myContact.put(RawContacts.ACCOUNT_NAME, newName); 
myContact.put(RawContacts.ACCOUNT_TYPE, newName); 

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

Uri addUri = getContentResolver().insert(RawContacts.CONTENT_URI, myContact);

This writes (inserts) the newName variable that we loaded (via myContact.put) into our myContact ContentValues object into the RawContacts.ACCOUNT_NAME database column that we specified in the same object. So, now our newName variable passed to our method has been taken care of. After this line of code, addUri will hold the location of the newly inserted record. Notice that we declared the addUri object as a Uri type of object and called getContentResolver.insert() all within a single line of compact code. Good job!

The next line of code takes our Uri object named addUri that appends the RawContacts.CONTENT_URI 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 new name by using the location of the new name record as a reference.) Now all we need to do is parse the data in the myContact ContentValues object via the addUri for the final data-insertion operation. This is done by calling the parseId() method off of the contentUris Class and putting the value into the long variable rawContactId that we will use in our next line of code.

        long rawContactId = contentUris.parseId(addUri);

The next 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 three lines, we use the put() method to load the myContact ContentValues object with the parsed ContentUris URI ID and table and column values for the DISPLAY_NAME field that we wish to write, and the newName primary name string variable data (“Steve Wozniak”), using the following lines of code:

myContact.clear();
 
myContact.put(Data.RAW_CONTACT_ID, rawContactId);
myContact.put(Data.MIMETYPE, StructuredName.CONTENT_ITEM_TYPE);
myContact.put(StructuredName.DISPLAY_NAME, newName);
 

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

getContentResolver().insert(data.CONTENT_URI, 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, Toast.LENGTH_SHORT);

Figure 10-16 shows the code as it appears in Eclipse with the import statements and our addContact() method highlighted.

Now right-click your ContentProviders project folder and select Run As Android Application. As you will see when you click the second button, the new name in our code is added to the Contacts database and a message confirming this is toasted (isn’t that a cool term? Hope you’re not toasted as well as trying to learn Java programming!) to the screen, as shown in Figure 10-17 . Now let’s go into our Android 4.1 emulator desktop and find the Contact Editor Utility so we can see the name data that we added.

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 (seen on the right screen in Figure 10-17 ). Even better, let’s click the Top Query Button, once you’ve added Steve Wozniak, and see his name pop up in the end of the query code (that is Toasted to the screen) that you wrote earlier in this chapter! Pretty Cool.