We are going to start by creating the prefs.xml - a resource file that outlines what our preference screen will look like. The easiest way to create it would be to use New Android XML File tool in Eclipse. To start the New Android XML File dialog, go to File→New→Android XML File, or click on the little a+ icon in the top menu bar of Eclipse:

Figure 7.1. New Android XML File

The key is to give the new file the name, in this case prefs.xml and to choose Preference for the type of resource. The tool should automatically suggest that this new file should be created in /res/xml folder and that the root element for the XML file should be PreferenceScreen. Just like discussed before in the section called “Alternative Resources”, we could create alternative versions of this same resource by applying various qualifiers such as screen size and orientation, language and region, etc.

Once you click on Finish, Eclipse will create a new file for you and open it up. Eclipse typically opens the XML files it knows about in its developer-friendly view.

In this view, you can create the username preference entry by selecting PreferenceScreen on the left, and then choosing Add→EditTextPreference On the right hand side, expand Attributes from Preferences section. Eclipse will offer you number of attributes to set for this EditTextPreference.

Not all attributes are equally important. Typically, you will care about the following:

For username preference, we’ll put username for key. We will define Title and Summary in strings.xml as this is the best practice.

Instead of modifying strings.xml file directly, you can use an Eclipse shortcut. Here’s how it goes:

The above describes how to add Username preference item. You can now repeat the same steps for Password and API Root items.

To switch to the actual XML code by clicking on the tab on the bottom of this window:

Figure 7.2. Prefs.xml in Developer-friendly view

The raw XML for the preference resource looks like this:

<?xml version="1.0" encoding="utf-8"?>
<PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android">

  <EditTextPreference android:title="@string/titleUsername"
    android:summary="@string/summaryUsername" android:key="username"></EditTextPreference>

  <EditTextPreference android:title="@string/titlePassword"
    android:password="true" android:summary="@string/summaryPassword"
    android:key="password"></EditTextPreference>

  <EditTextPreference android:title="@string/titleApiRoot"
    android:summary="@string/summaryApiRoot" android:key="apiRoot"></EditTextPreference>

</PreferenceScreen>

<PreferenceScreen> is the root element that defines our main preference screen. It has three children, all <EditTextPreference>. This is simply a piece of editable text. Other common elements here could be <CheckBoxPreference>, <ListPreference>, and so on.

The main property of any of these elements is the key. The key is how we’ll look up these values later on. Remember, preferences is just a set of name-value pairs at the end of the day.

Like we said couple of times earlier, while Eclipse does provide a developer-friendly tools to manage XML files, you often run into certain limitations with with Eclipse. For example, we would like to hide the actual text that the user types in the password field as it’s commonly done with passwords. Android does provide support for that but Eclipse tools haven’t integrated it in there yet. Since we can always edit the XML directly, in this case we to that to add android:password="true" property to our password property. This will cause the password to be masked while user is typing it in.

Now that we have the preferences defined in their own XML resource file, we can create the activity to display these preferences. You may recall from <<Activities> that every screen in an Android app is an activity. So, to display the screen where user enters username and password for their online account, we’ll create an activity to handle that screen. This activity will be a special preference-aware activity.

To create an activity, we create a new Java class. To do so, in Eclipse, select your package under your src folder, right-click on the package and select New→Class. A New Java Class window will pop up. You just need to enter PrefsActivity for the Name and click Finish. This will create PrefsActivity.java file under your package in your source folder.

Our PrefsActivity class going to be a very simple Java file. This is because we inherit from PreferenceActivity, an Android framework provided class that knows how to handle preferences.

package com.marakana.yamba2;

import android.os.Bundle;
import android.preference.PreferenceActivity;

public class PrefsActivity extends PreferenceActivity { // 

  @Override
  protected void onCreate(Bundle savedInstanceState) { // 
    super.onCreate(savedInstanceState);
    addPreferencesFromResource(R.xml.prefs); // 
  }

}

Whenever we create one of these main building blocks (Activities, Services, Broadcast Receivers, Content Providers) we need to define them in AndroidManifest.xml file. In this case, we have a new PrefsActivity and we must add it to the manifest file.

Just like with any Android XML file, opening AndroidManifest.xml in Eclipse will typically bring up the developer-friendly view of that file. In this file, you could choose Application tab, then under Application Nodes choose Add→Activity and for its Name type .PrefsActivity.

However, we can also do this straight from the raw XML by clicking on AndroidManifest.xml tab on the bottom of this window. I find that while Eclipse is useful when it comes to creating XML files, often editing raw XML is faster and gives you much more control.

So after adding our manifest file now looks like this:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
  android:versionCode="1" android:versionName="1.0" package="com.marakana.yamba2">
  <application android:icon="@drawable/icon" android:label="@string/app_name">

    <activity android:name=".StatusActivity" android:label="@string/titleStatus">
      <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
      </intent-filter>
    </activity>

    <activity android:name=".PrefsActivity" android:label="@string/titlePrefs" /> <!--  -->

  </application>
  <uses-sdk android:minSdkVersion="4" />

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

We now have a new preference activity, but no good way of getting to it yet. We need a way to launch this new activity. For that, we use options menu.

We start by defining the menus in an XML resource for the options menu. Just like with other Android XML files, we can use the little a+ icon in the Eclipse toolbar or choose File→New…→Android XML to launch New Android XML File dialog. In this dialog, for File enter menu.xml and for Type select Menu. Click Finish button and Eclipse will create a new folder /res/menu with menu.xml file in it. It will also open this file in developer-friendly view.

In this view, you can click on Add→Item. This will add a new menu item to your menu. In the Attributes section on the right, you can see over a dozen various attributes that we can set for this menu item. Just like before, not all attributes are equally important.

The next section describes these resources in more detail.

Just like your application can have its resources so can Android system as well. Like most other operating systems, Android comes with some preloaded images, graphics, sound clips, and other types of resources. Recall that our app resources are in /res/. To refer to Android system resources prefix them with with android: keyword in XML, for example @android:drawable/ic_menu_preferences. If you are referring to an Android system resource from Java, then you use android.R instead the usual R reference.

Figure 7.3. Menu.xml in Developer-friendly view

The raw XML of menu.xml is shown here:

<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">
  <item android:id="@+id/itemPrefs" android:title="@string/titlePrefs"
    android:icon="@android:drawable/ic_menu_preferences"></item>
</menu>

As you can see, there’s just one <item> element within our <menu> element making this a single menu item menu.

Recall that the options menu is loaded by your activity when user clicks on the Menu button on the device. First time menu button is pressed, system will call activity’s onCreateOptionsMenu() method to inflate the menu from the menu.xml resource. This process is similar to inflating user interface from layout resources that we discussed in the section called “StatusActivity Java Class”. Basically, the inflater reads the XML code and for every element, it creates a corresponding Java object and for each attribute in XML is sets that object’s properties accordingly.

From that point on, the menu is in memory and onCreateOptionsMenu() doesn’t get called again until the activity is destroyed. Each time user selects a menu item though, onOptionsItemSelected() gets called to process that click. We’ll talk about this in the next section.

We need to update the StatusActivity to load up the options menu. To do that, add onCreateOptionsMenu() method to StatusActivity. This method gets called only first time when user clicks on the menu button.

// Called first time user clicks on the menu button
@Override
public boolean onCreateOptionsMenu(Menu menu) {
  MenuInflater inflater = getMenuInflater();   // 
  inflater.inflate(R.menu.menu, menu);         // 
  return true; // 
}

We also need a way to handle various clicks on the menu items. To do that, we add another callback method, onOptionsItemSelected(). This method is called every time user clicks on a menu item.

// Called when an options item is clicked
@Override
public boolean onOptionsItemSelected(MenuItem item) {
  switch (item.getItemId()) {                              // 
  case R.id.itemPrefs:
    startActivity(new Intent(this, PrefsActivity.class));  // 
  break;
  }

  return true;  // 
}

Our updated strings.xml now looks like this:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string name="app_name">Yamba 2</string>
  <string name="titleYamba">Yamba 2</string>

  <string name="hintText">Please enter your 140-character status</string>
  <string name="buttonUpdate">Update</string>

  <string name="titleStatus">Status Update</string>
  <string name="titlePrefs">Prefs</string>
  <string name="titleUsername">Username</string>
  <string name="titlePassword">Password</string>
  <string name="titleApiRoot">API Root</string>

  <string name="summaryUsername">Please enter your username</string>
  <string name="summaryPassword">Please enter your password</string>
  <string name="summaryApiRoot">URL of Root API for your service</string>
</resources>

You should be able to run your application at this point and and see the new PrefsActivity by clicking on Menu→Prefs in StatusActivity. Try changing your username and password, then reboot your phone, restart the app, and verify that the information is still there.

Figure 7.4. PrefsActivity

There are two ways for you to access the file system on an Android device. One way is using Eclipse, the other command line.

In Eclipse, we use File Explorer view to access the file system. To open up the File Explorer view, go to Window→Show View→Other…→Android→File Explorer. You can also access File Explorer view via DDMS Perspective. Select DDMS Perspective in the top-right corner of your Eclipse or go to Window→Open Perspective→Other…→DDMS. If you have multiple devices connected to your workstation, make sure you select which one you are working with in the Devices view. You should now be able to navigate through the file system of the device.

If you prefer the command line, you can always use adb shell to get to the shell of the device. From there you can explore the file system like you would on any other Unix platform.

There are three main parts of the file system on every Android device. They are:

Figure 7.5. File System as seen via File Explorer in Eclipse

System partition is where your entire Android operating system is. This is the main partition containing all your preinstalled applications, system libraries, Android framework, linux command line tools, and so on.

System partition is mounted read-only, meaning you as developer have very little influence over it. As such, this partition is of limited interest to us.

The system partition in the Emulator corresponds to system.img file in your platform images directory, located in android-sdk/platforms/android-8/images/ folder.

SDCard partition is a free-for-all mass storage. Your app can read files from this partition as well as write files to it if it holds WRITE_TO_EXTERNAL_STORAGE permission. This is a great place to store large files, such as music, photos, videos and similar.

Note that since FroYo version of Android, /sdcard mount point appears in Eclipse File Explorer under /mnt/sdcard location. This is because of the new feature in FroYo to allow for storing and running applications on the SDCard as well.

As an app developer, SDCard partition is very useful and important to you. At the same time, this partition is not very structured.

This partition typically corresponds to sdcard.img in your Android Virtual Device (AVD) directory. This directory is in you ~/.android/avd/ folder and will have a subdirectory for each specific virtual device. On the physical device, it is an actual SD card.

As user and app developer, the most important partition is the User Data partition. This is where all your user data is stored, all the downloaded apps are located, and most importantly, all apps' data is. This includes both preinstalled apps as well as user-downloaded apps.

So, while user apps are stored in /data/app/ folder, the most important folder to us as app developer is /data/data/ folder. More specifically, within this folder there’s a subfolder corresponding to each app. This folder is identified by the Java package that this app used to sign itself. Again, this is why Java packages are important to Android security.

Android framework provides number of handy methods as part of context that help you access user data file system from within your application. Take a look at getFilesDir() for example.

This partition typically corresponds to user-data.img in your Android Virtual Device (AVD) directory. As before, this directory is in your ~/.android/avd/ folder and will have a subdirectory for each specific virtual device.

When you create a new app, you assign your Java code to a specific package. Typically, this package follows the Java convention of reverse domain name plus app name. For example, Yamba app is in com.marakana.yamba package. So, once installed, Android creates a special folder just for this app under /data/data/com.marakana.yamba/. This folder is the cornerstone of our private secured file system dedicated to each app.

There will be sub-folders in /data/data/com.marakana.yamba2/, but they are well-defined. For example, the preferences are in /data/data/com.marakana.yamba2/shared_prefs/. As a matter of fact, if you open up DDMS perspective in your Eclipse and select File Explorer, you can navigate to this partition. You will probably see com.marakana.yamba2_preferences.xml file in there. You could pull this file and exam in it, or you could use adb shell.

adb shell is another one of those common adb subcommands to access the shell of your device (either physical or virtual). For instance, you could just open up your command line terminal and type:

[user:~]> adb shell
# cd /data/data/com.marakana.yamba2/shared_prefs
# cat com.marakana.yamba2_preferences.xml
<?xml version='1.0' encoding='utf-8' standalone='yes' ?>
<map>
<string name="password">password</string>
<string name="apiRoot">http://yamba.marakana.com/api</string>
<string name="username">student</string>
</map>
#

This XML file represents the storage for all our preference data for this application. As you can see, our username, password and API root are all stored in there.

So, how secure is this? This is a common question by security folks. Username and password stored in clear text always raises eyebrows.

To answer this question, I usually compare it to finding someone’s laptop on the street. While indeed we can easily gain access to the "hard-drive" via adb tool, that doesn’t mean we have a way of reading its data. Each folder under /data/data/ is going to belong to a separate user account. This user account is managed by Linux. Unless our app is that app, it won’t have access to that folder. So, short of us reading byte-by-byte on the physical device, even clear-text data is secure.

On the Emulator, we have root permissions meaning we can explore entire file system. This is useful for development purposes.