The Android MediaStore Databases

The MediaStore databases include 9 different new media asset databases, the CalendarContract databases include 11 different Calendar component databases, and the ContactsContract databases include the most databases, with 21 functional databases.

The MediaStore databases include five audio data related databases and one image and one video related database. Table 19-1 shows the MediaStore data provider interfaces, as well as the types of data they access (reference).

The Android CalendarContract Databases

The CalendarContract databases include 11 Calendar-related databases, each supporting various Calendar functions such as Events, Attendees, Alerts, Reminders, and other similar Calendar-related data support functions.

The reason that the Android operating system provides pre-built support, via its android.provider package for the Android Calendar database access is because it would be logical for applications that want to access these Calendar features to be able to add cool new capabilities to the existing Android Calendar feature set.

Table 19-2 shows the CalendarContract data provider interfaces, as well as the different types of Calendar function data that they access (and thus, which they will allow you to reference directly using a Content Provider).

Next we will take a look at the new Android Contacts database structures, which are now referenced via the ContactsContract moniker (instead of just using Contacts), as of the Android 2.1 (Éclair) operating system version.

The Android ContactsContract Databases

The ContactsContract databases include a whopping 21 Contact data related database tables, which is not so surprising, as these days Contact management includes a myriad of information such as name, phone number, e-mail address, social media presence, status, display name, and so on. Table 19-3 shows the ContactsContract data provider interfaces, as well as the types of data that they access (and thus, which they will reference).

Next, we will take a look at the concept of deprecation, as it relates to Android databases, since some of you may need to use the old Contacts data structures to support ancient users of Android 2.0, or even 1.5 and 1.6.

Content Provider Activity: Prepare the AlienContact Class

Add your usual protected void onCreate(Bundle savedInstanceState) method with a call to super.onCreate(savedInstanceState); as we have done in previous chapters, and then also add a setContentView( ) method referencing the activity_contact.xml file, which we will create next. Here’s the code:

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_contact);
}

The new AlienContact.java Activity subclass and onCreate( ) method is shown in Figure 19-8. Notice the reference to our activity_contact.xml UI definition, which we are going to create next, is red error highlighted. Because we know that this reference is going to be defined and put in place soon, we can safely ignore this error in our Java code in Eclipse for now.

Next, we need to define our AlienContact Activity in our Android Manifest XML file, using an <activity> tag and android:label parameter, as we have done before to give our UI screen a title, as shown in Figure 19-9. Here is the XML mark-up that we will be adding at the bottom of our AndroidManifest.xml file:

<activity android:name="chapter.two.hello_world.AlienContact"
          android:label="@string/activity_title_alien_contact"  />

Now we are ready to create our Activity user interface screen XML file, which we will call activity_contact.xml following the Android convention.

Content Provider User Interface: Creating activity_contact.xml

Right-click the /res/layout folder in your project hierarchy in the Package Explorer pane of Eclipse, and select the New Android XML File menu sequence. This launches the New Android XML File helper dialog, which is shown in Figure 19-10.

Select a Resource Type of Layout and a Project setting of Hello_World, and then name the file activity_contact and finally select a Root Element type of LinearLayout for your user interface design container.

The next thing that we will need to do is to add some string constants to our strings.xml file using the <string> tag. First, let’s add the Activity screen title (label) string tag using the following XML mark-up:

<string name="activity_title_alien_contact">Hello World - Alien Contacts</string>

Next, let’s add the three Alien Contact UI Button labels that we need to reference in our XML UI mark-up that we are going to write next. These would be written as follows and are shown at the top part of Figure 19-11.

<string name="find_alien_button_value">List Aliens in this Galaxy</string>
<string name="add_spock_button_value">Add Spock to my Alliance</string>
<string name="add_worf_button_value">Add Worf to my Alliance</string>

Next we need to add the Button tag elements inside our parent LinearLayout container tag as well as adding parameters to the LinearLayout to add in a background space image, so that our user interface looks professional, and matches up with the rest of the application design we have used thus far.

The first user interface Button tag utilizes an android:id parameter set to findAliens, and features a text color of yellow or #FFFFAA and references the string constant that we created previously.

Additionally, we utilize an android:layout_marginTop parameter set to 40dp to push our UI elements down from the top of the UI screen design a little bit, and an android:layout_gravity parameter set to center so that our UI elements center nicely in the middle of the screen design.

Finally, make sure that you have your default android:layout_width and height parameter set to wrap_content. Your Button XML looks like this:

<Button android:id="@+id/findAliens"
        android:text="@string/find_alien_button_value"
        android:textColor="#FFFFAA"
        android:layout_marginTop="40dp"
        android:layout_gravity="center"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content" />

This first user interface Button element, as well as the next three, which we are going to generate using copy and paste operations to quickly create the remainder of our XML mark-up for this user interface design, are shown in Figure 19-12. Once we copy this XML definition and paste it three more times underneath itself we can modify the parameters to create new UI element tags for our buttons that will Add Aliens and Exit the Activity.

Let’s do that now; copy and paste the findAliens (ID) Button tag three more times underneath itself, and change the android:id parameter from findAliens to addSpock, addWorf, and returnHome, respectively.

Next, change the android:layout_marginTop parameter to be 25dp for the addSpock and addWorf Button tags, and to 60dp for the returnHome Button.

We will leave the android:textColor parameter set to #FFFFAA or Yellow, and the android:layout_gravity parameter set to center and finally, the android:layout_width and height parameters set to wrap_content so that all our Button user interface elements are formatted uniformly.

Next let’s use the Graphical Layout Editor tab at the bottom of the XML editing pane and see how our new user interface design looks. Because our last Button element that we edited was the returnHome Button, it should be selected in the view because that is where our cursor is in the XML text editing tab.

The visual results can be seen in Figure 19-13, and our design seems to look quite professional, and matches up well with our other five Activity screen designs. That means we are done with our XML user interface design mark-up, and we can proceed to work on our Java code to implement the functionality of our user interface design. We will be using Button objects along with their event handling methods, which will eventually contain our Java code which will access the Contact database structures stored inside of the Android operating system.

Next let’s go back into our AlienContacts.java editing tab in Eclipse and add in the lines of code to instantiate each Button object and then attach event handling logic to it so we have a framework to trigger our database operations with.

Coding User Interface Elements in the AlienContact Class

First we need to write our first aliensButton Button object Java code for object creation and event handling and then we can copy it three more times underneath itself and create the other three user interface buttons.

The Java code to do this is shown in Figure 19-14 and has been copied to create Button objects for our aliensButton, spockButton, worfButton, and homeButton user interface elements, using the following Java code block:

Button aliensButton = (Button)findViewById(R.id.findAliens);
aliensButton.setOnClickListener(new View.OnClickListener() {
   @Override
   public void onClick(View v) {
      finish();
   }
}

We are using a finish( ) method call inside our onClick( ) event handling code block so that each button has a function (returns us to Home Screen) until we replace it with database related code later on in the chapter. This makes testing the Java code as we go along easier and error-free.

If you like you can use your Run As Android Application work process to launch the Nexus S emulator and see the user interface screen in all its glory and click each button to return to the app Home Screen.

Next we will code the aliensButton object so that it calls a listAliens( ) method which lists all the aliens in our Galaxy using the Toast class, so that all the alien names are broadcast to our user interface screen.

Using a ContentResolver: Coding Our listAliens( ) Method

The first thing that we need to do is to replace the finish( ) method call in our aliensButton event handling code block with a listAliens( ) method call. When you do this Eclipse uses a wavy red underline to highlight the fact that this method does not exist, as is shown in Figure 19-15.

Also shown in Figure 19-15 is the helper dialog that comes up when your mouse is held over this error highlighting, as well as the empty method that Eclipse writes for you when you select the second option named Create method ‘findAliens( )’ in type ‘AlienContact’ and voila! Look at the bottom of your editing screen: the empty listAliens( ) method has appeared!

Now it is time to write our first database related Java code to access the Contacts database that we have requested permission to use in our Android Manifest XML file. In this case we’ll initially be using the READ_CONTACTS permission, because we are going to read the Contacts database and then list all the Aliens in our Galaxy Alliance on the user interface screen.

First we use the Android Cursor class, used to navigate through database tables, and create a Cursor object named AlienCur (I was tempted to name this object alienCurse but resisted). In the same line of code we can load this Cursor object with the database table we want to traverse using the getContentResolver( ) method, using the following single line of Java code:

Cursor alienCur = getContentResolver().query(ContactsContract.Contacts.CONTENT_URI, null, null, null, null);

This calls the ContentResolver class getContentResolver( ).query( ) method, which accepts parameters for the database URI that you want to query, as well as projection, selection, arguments, and sort order. Since we are just reading through the entire Contacts database, we are not going to use any of these other database access specifier parameters, and thus we use the null value (which serves as an unused indicator) in that parameter slot.

Now that we have created our alienCur Cursor object and loaded it with the database content that we want it to traverse and read, we can construct a Java while statement to read through all the records (fields) in this database table. Because we want the Cursor object to .moveToNext( ) or move to the next record while the while loop is still valid, we start off with:

while (alienCur.moveToNext()) { our while loop processing Java code goes in here }

Inside of the while loop, we have two Java statements, which process the database contents during the time that the while loop is running (valid). This is defined by the while loop’s condition, which specifies that the contents of the while loop should be executed while the loop can still MoveToNext (while there is another record to READ in the database table).

The first line of code creates a String object named alienName to hold the data we are about to read and then sets it equal to the operation that actually reads the data from the database table using the Cursor object we created in the first line of code. The Java code to do this is as follows:

String alienName =
alienCur.getString(alienCur.getColumnIndex (ContactsContract.Contacts.DISPLAY_NAME_PRIMARY));

We set our alienName String object equal to a result from the .getString( ) method, called on the alienCur Cursor object, which gets its results from the .getColumnIndex( ) method that is called on the alienCur Cursor object.

As you can see, the parameter given to the Cursor object .getColumnIndex( ) method call specifies the data column (field) held in the primary display name database record. This is referenced by using the DISPLAY_NAME_PRIMARY constant, which is itself referenced via the ContactsContract database, and is located in the Contacts table. This is shown in Figure 19-16.

Now that we have the data that we want to display, in the String format that we need it to be in, we can simply call the Toast object, via its .makeText( ) method, and display the data to our new user interface screen.

We will do this by using the following familiar line of Java code, which chains the .makeText( ) and the .show( ) methods one after the other off the Toast object. like this:

Toast.makeText(this, alienName, Toast.LENGTH_SHORT).show();

After entering the closing bracket, which ends our while loop definition, we’ll finally need to close (remove the Cursor object from system memory) the alienCur Cursor object, which is currently holding our database data.

This Cursor object can potentially take up a significant amount of system memory, by the way, so it is quite important that when we are done, we use the Cursor class’s .close( ) method to clear the Cursor object that we have defined out of the system memory.

This is done using one simple method call off the alienCur object. This is done using Java dot notation, and is shown in the following Java code:

alienCur.close();

Now we’re ready to add Aliens to our Android emulator’s Contact database, so that we can test the Permissions, Java code, and XML mark-up which we have just written in the previous sections.

Adding Alien Contacts to the ContactsContract Database

Assuming that you still have Eclipse open, launch the Android emulator, by using the Window Android Virtual Device Manager menu sequence. This work process launches the Nexus S emulator, without having the emulator load and run your Hello World application automatically.

It is also important to note here that if for some reason a Run As Android Application work process for any reason does not launch Android’s emulator functionality, that this is the way to “hard launch” the Android emulator.

When the Android Virtual Device Manager dialog appears, select the Nexus S emulator option from the list of emulators we set up earlier in this book, and click on the Start… button.

When the Launch Options dialog appears, uncheck the Launch from snapshot, as well as the Save to snapshot option, and click the Launch button.

This then brings up the Starting Android Emulator dialog as well as a progress bar that shows the emulator being loaded and launched. Once it launches, you can then close the Android Virtual Device Manager dialog.

What you will see when the Nexus S emulator launches is a Smartphone Start Screen emulator, shown in Figure 19-17 on the left side of the screenshot.

The utility for managing your Contacts database is so important that it is right there on the bottom left of your Smartphone Start Screen, indicated by a little talking head inside of a blue contact sheet icon simulation.

Click this icon to launch your emulator’s Contact Management Utility, which is shown on the right-hand side of Figure 19-17.

Click the top button to Create a new contact in your Smartphone (emulator) Contacts database. This brings up a dialog that informs you that because you are using an emulator, the new contact information that you are about to enter will not be backed up since you are not using a real phone.

In case you want to use the emulator to create real contact database information that can be accessed by your real Android Smartphone account, the dialog then asks you if you want to add an account that would back up the contacts that you enter in the emulator on-line.

Because we are just using this as a testing application for the Contacts database code that we are learning about in this chapter, we are going to select the button option on the left that says “Keep Local,” so that the information that we enter is stored on our workstation’s hard disk drive, and not “in the cloud” as it were.

This Keep Local dialog is shown in Figure 19-18, and once we select the Keep Local option, we will see the Contact Management user interface.

Once the Contact Management screen appears, as shown on the right side of Figure 19-18, we will enter our first alien name, Goran Agar, one of the Jem Hadar race, featured on the popular Star Trek series.

Once you enter Goran Agar’s name on the dark blue line located at the top of the user interface screen, click the light blue Done button located right above and to the left of the text entry field, as shown in Figure 19-18.

To see the entry you have just entered in your contacts database, click the left-facing arrow at the top of the screen and you will be brought to the Contacts database listing screen shown in Figure 19-19 on the left.

On the bottom right of the Contacts database listing screen, which, at this point in time, only shows our alien friend Goran Agar, if you look closely, you will see a square gray icon of a head with a + symbol next to it. This allows you to add another contact to your Contact database, so click this icon now, and we will add some more aliens to our Galaxy Alliance.

Add two more aliens from the Jem Hadar race, named Remata Klan and Kudak Etan, using the same work process as outlined previously. Once you do this, the Contact Database List Screen should look like it does in the right side of the screenshot shown in Figure 19-19.

Now we have enough aliens in our Alien Contacts database to test our app!

Before we test our AlienContact.java Activity we need to be able to access it from our Home Screen options menu, so let’s do that next so that we can test our listAliens( ) method now that we have the data in the (Alien) Contacts database to do this.

Adding the AlienContact Activity to the Home Screen Menu

The first thing we need to do to add a new options menu entry is to create a <string> constant in our strings.xml file for the menu label.

Following the format for our other menu string constants, let’s create a menu_contact_planet named <string> tag with the menu label value of Make Alien Contact, and place it in the strings.xml file under our other menu string constants, as shown in Figure 19-20. Your XML mark-up for the <string> tag should look like the following:

<string name="menu_contact_planet">Make Alien Contact</string>

Once this is done, we will be ready to change the placeholder fifth menu item entry in our activity_main.xml file in our /res/menu subfolder with the Make Alien Contact menu option that will call our AlienContact.java Activity subclass. Remember that there are two activity_main.xml files for our application, one in /layout for UI, and one in /menu for menu design.

Right-click the activity_main.xml file, in the /res/menu folder, and select the Open option (or select the filename in the Package Explorer and then hit F3). Edit the last placeholder item in the file to have an android:id setting of menu_contact and edit the android:title parameter to reference @string/menu_contact_planet, as is shown in Figure 19-21.

Because our onCreateOptionsMenu( ) method already inflates our menu XML file definition, the next thing that we logically need to do is to modify our onOptionsItemsSelected( ) method, and add a case statement that handles the menu_contact ID and that launches our AlienContact.java Activity subclass.

Open your MainActivity.java Activity in the Eclipse central editing pane and close up all the methods except for onOptionsItemSelected( ) as shown in Figure 19-22. Then, add a case R.id.menu_contact: statement that creates an intent_contact Intent object, and sets it to call the new AlienContact class. Finally, call the .startActivity( ) method, using this Intent object, then use break; to exit this section of the case statement.

The fifth menu item case statement code should look like the following:

case R.id.menu_contact:
    Intent intent_contact = new Intent(this, AlienContact.class);
    this.startActivity(intent_contact);
    break;

Now that we have enabled our user (and ourselves) to start the AlienContact.java Activity subclass, we can test our activity_contact.xml user interface design and our Java code that implements it, as well as the ContentResolver that will read our Alien Contacts database entries that we just created in the previous section.

Right-click your Hello_World project folder and then select the Run As Android Application menu sequence, or, if you prefer, utilize the Window Android Virtual Device Manager work process we used earlier in the chapter to launch the emulator.

Testing the listAliens( ) Method in the AlienContact Activity

Once the Nexus S emulator launches, find the Hello_World icon (Saturn) and launch the app. If you used the Run As Android Application menu sequence, this will be done automatically for you.

Once the Hello_World Home Screen appears, click the Menu button on the top right of the emulator, and bring up the options menu that we just created, as shown on the left-hand side of Figure 19-23.

Select the Make Alien Contact menu item at the bottom of the menu and open the Alien Contacts Activity user interface screen shown on the right-hand side of Figure 19-23.

Click the Return Home button as well as the Add Spock and Add Worf buttons and make sure that they call the finish( ) method and take you back to the Hello_World app Home Screen.

Once you have tested those, click the Menu button in the emulator again, and enter the AlienContact.java Activity subclass, so we can test the List Aliens in this Galaxy button and make sure that it is traversing through our Alien Contacts database, using the Cursor object, and listing all our Alien Contacts from the elite Jem Hadar intergalactic race.

When you click the List Aliens in this Galaxy button as shown on the left-hand side of Figure 19-24, you will see the Toast messages appear at the bottom of the user interface screen, listing all three of the Jem Hadar race members in your Alien Contacts database.

The Toast message for Goran Agar is shown on the bottom right-hand side of the screenshot in Figure 19-24 so our ContentResolver Java code is working perfectly. Next, let’s write another Java method called addToAlliance( ), which shows us how to use the Android ContentValues class to enable us to add new Alien Contacts to our Alliance Database, by using our own custom Java code, rather than having to use the Android OSes’ Contact Management Utility.

Android ContentValues: Code an addToAlliance( ) Method

Open up the AlienContact.java editing tab in Eclipse and replace the finish( ) method calls in the onClick( ) event handlers for the spockButton and worfButton code blocks with method calls to the new addToAlliance( ) method that we will be writing. The format for this method call passes a String parameter like this addToAlliance(String Value) so the line of Java code would look like this:

addToAlliance("Spock");

Once you have added addToAlliance( ) method calls for Spock and Worf, we need to code the protected void addToAlliance(String newAlien) method.

The first thing that we do in our addToAlliance( ) method is to construct a ContentValues object named alienContact using the Java new keyword, using the following single line of Java code:

ContentValues alienContact = new ContentValues();

After that, we can load the alienContact ContentValues object with the newAlien parameter String data that we passed into the method. We do this by using the .put( ) method, called off of the alienContact ContentValues object, with the first parameter directing where we want the data to be placed, and the second parameter being the data itself to be placed into that field. This is shown in Figure 19-25 near the bottom of the screen.

As you can see, this is done for the ACCOUNT_NAME and ACCOUNT_TYPE columns (data fields) in the RawContacts database table that we want to specify in the ContentValues object, by using the following two lines of Java code:

alienContact.put(RawContacts.ACCOUNT_NAME, newAlien);
alienContact.put(RawContacts.ACCOUNT_TYPE, newAlien);

Then we create a Uri object named addUri, and set that equal to the result of a getContentResolver.insert( ) method call, using the parameters for the database to WRITE to (insert data) and the data to be written. This is the RawContacts database, specified using the RawContacts.CONTENT_URI constant and the alienContact ContentValues object, now loaded with our newAlien String data. This is done using the following single line of Java code:

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

Next we create a long variable named rawContactId, and set it equal to the result of a ContentUris.parseId(addUri) method call, which puts the addUri Uri object into long value format compatible with the .put( ) method we are about to call. This is done using the following single line of Java code:

long rawContactId = ContentUris.parseId(addUri);

Remember that as you type in this new database WRITE operation Java code, any Android class that you call or use, such as ContentValues, ContentUris, or ContentResolver that has not already been imported, that is, an import statement written for it at the top of the class (which, as you have seen, Eclipse will readily do for you) will be highlighted with a wavy red line underneath the offending method call.

Now that we have our database ID in the correct (long) numeric format in our variable rawContactId, we can now use the .clear( ) method to clear our alienContact ContentValues object, so that we can use it again, to WRITE more data values into the other databases which are interrelated with the Android Contacts database. The line of Java code should look like this:

alienContact.clear();

This is why database coding in Android is difficult; as I mentioned at the beginning of this chapter, it has to do more with the intricacy of how the database hierarchy is set up than the Java code that is used to access (or to write) the data. You are about to see that here, as we discuss how the rawContactId is used to write the same data you wrote into the RawContacts database table into the related Data and StructuredName database tables.

First we need to put the rawContactId value into the Data.RAW_CONTACT_ID database table, using the .put( ) method via this single line of Java code:

alienContact.put(Data.RAW_CONTACT_ID, rawContactId);

Then we need to put the data value that is in the CONTENT_ITEM_TYPE data column of the StructuredName database table into the MIME_TYPE data column in the Data database table, using the following line of Java code:

alienContact.put(Data.MIME_TYPE, StructuredName.CONTENT_ITEM_TYPE);

Then we need to put our newAlien String object (alien name) into the DISPLAY_NAME data column of the StructuredName database table, like this:

alienContact.put(StructuredName.DISPLAY_NAME, newAlien);

Finally we can insert all this data related to the RawContacts database that we have set up into the Data database table using the CONTENT_URI and alienContact ContentValues object that we have been building over the past several lines of code. We will again accomplish this by using our trusty getContentResolver( ).insert( ) method call, using the following Java code:

getContentResolver.insert(Data.CONTENT_URI, alienContact);

Now we are ready to Toast the end-user and tell them what we have just done so that they are aware that the newAlien has been added to the RawContacts (and Data) database table as a New Alliance Member. This is done using the following line of code, which chains two methods together:

Toast.makeText(this, "New Alliance Member: " + newAlien, Toast.LENGTH_SHORT).show();

Let’s test our new addToAlliance( ) Java method via our AlienContact.java Activity inside the Android Nexus S emulator, to see if our new alliance members, Spock and Worf, are being added to the Alien Contacts database.

Launch the Nexus S emulator, and when the Hello_World Home Screen appears, click the Menu button, and select the Make Alien Contact menu option.

Once that Activity screen appears, click your Add Spock to my Alliance and Add Worf to my Alliance buttons, and make sure that the Toast messages appear at the bottom of the user interface screen. Looking great so far!

Now, all that we have left to do is to confirm that the Alien Contact data has indeed been properly added to the Android Contacts databases, as if we had done it using the Contact Management Utilities, which we used earlier.

If we wrote our database code correctly, then our new Alien Contacts data will be in the Android Contact Management Utility when we enter it next, just as if we had added it directly using that utility. If we did not write our database structures correctly, the data will not appear there.

Exit your Hello_World application and return to the Smartphone emulator Home Screen and click the Contact Management icon on the bottom left of the screen as we did earlier in the chapter. When your (alien) contacts list appears, you will see when you scroll down that Spock and Worf are now present and correctly alphabetized in your Contacts database listing!

Note that you can also use your List Aliens Button in your app to test to make sure these two aliens have been added as well if you like.