Problem

You want to know how to store files in internal versus external storage. Files can be created and accessed in several different places on the device (notably, application private data and SD card–style data). You need to learn the APIs for dealing with these sections of the filesystem.

Solution

Use the Context methods getFilesDir(), openFileInput(), and openFileOutput() for “internal” storage, and use the methods Context.getExternalFilesDir() or Environment.getExternalStoragePublicDirectory() for shared storage.

Discussion

Every Android device features a fairly complete Unix/Linux filesystem hierarchy. Parts of it are “off-limits” for normal applications, to ensure that the device’s integrity and functionality are not compromised. Storage areas available for reading/writing within the application are divided into “internal” storage, which is private per application, and “public” storage, which may be accessed by other applications.

Internal storage is always located in the device’s “flash memory” area—part of the 8 GB or 32 GB of “storage” that your device was advertised with—under /data/data/PKG_NAME/. External storage may be on the SD card (which should technically be called “removable storage,” as it might be a MicroSD card or even some other media type). However, there are several complications.

First, some devices don’t have removable storage. On these, the external storage directory always exists—it is just in a different partition of the same flash memory storage as internal storage.

Second, on devices that do have removable storage, the storage might be removed at the time your application checks it. There’s no point trying to write it if it’s not there.

On these devices, as well, the storage might be “read-only” as most removable media memory devices have a “write-protect” switch that disables power to the write circuitry.

    try (FileOutputStream os =
            openFileOutput(DATA_FILE_NAME, Context.MODE_PRIVATE)) {
        os.write(message.getBytes());
        println("Wrote the string " + message + " to file " +
                DATA_FILE_NAME);
    } catch (IOException e) {
        println("Failed to write " + DATA_FILE_NAME + " due to " + e);
    }

    // Get the absolute path to the directory for our app's internal storage
    File where = getFilesDir();
    println("Our private dir is " + where.getAbsolutePath());

    try (BufferedReader is = new BufferedReader(
            new InputStreamReader(openFileInput(DATA_FILE_NAME)))) {
        String line = is.readLine();
        println("Read the string " + line);
    } catch (IOException e) {
        println("Failed to read back " + DATA_FILE_NAME + " due to " + e);
    }

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

String state = Environment.getExternalStorageState();
println("External storage state = " + state);
if (state.equals(Environment.MEDIA_MOUNTED_READ_ONLY)) {
    mounted = true;
    readOnly = true;
    println("External storage is read-only!!");
} else if (state.equals(Environment.MEDIA_MOUNTED)) {
    mounted = true;
    readOnly = false;
    println("External storage is usable");
} else {
    println("External storage NOT USABLE");
}

// Get the external storage folder for Music
final File externalStoragePublicDirectory =
        Environment.getExternalStoragePublicDirectory(
                Environment.DIRECTORY_MUSIC);
// Get the directory for the user's public pictures directory.
// We want to use it, for example, to create a new music album.
File albumDir = new File(externalStoragePublicDirectory, "Jam Session 2017");
albumDir.mkdirs();
if (!albumDir.isDirectory()) {
    println("Unable to create music album");
} else {
    println("Music album exists as " + albumDir);
}

        // Finally, we'll create an "application private" file on /sdcard,
        // Note that these are accessible to all other applications!
        final File privateDir = getExternalFilesDir(null);
        File semiPrivateFile = new File(privateDir, "fred.jpg");
        try (OutputStream is = new FileOutputStream(semiPrivateFile)) {
            println("Writing to " + semiPrivateFile);
            // Do some writing here...
        } catch (IOException e) {
            println("Failed to create " + semiPrivateFile + " due to " + e);
        }

See Also

For getting information about files, and directory listings, see Recipe 10.2. To read static files that are shipped (read-only) as part of your application, see Recipe 10.3. For more information on data storage options in Android, refer to the official documentation.

Source Download URL

The source code for this example is in the Android Cookbook repository, in the subdirectory FilesystemDemos (see “Getting and Using the Code Examples”).

Figure 10-1. FilesystemDemos in action

Problem

You need to know all you can about a given file “on disk,” typically in internal memory or on the SD card, or you need to list the filesystem entries named in a directory.

Solution

Use a java.io.File object.

Discussion

The File class has a number of “informational” methods. To use any of these, you must construct a File object containing the name of the file on which it is to operate. It should be noted up front that creating a File object has no effect on the permanent filesystem; it is only an object in Java’s memory. You must call methods on the File object in order to change the filesystem; there are numerous “change” methods, such as one for creating a new (but empty) file, one for renaming a file, and so on, as well as many informational methods. Table 10-1 lists some of the informational methods.

You cannot change the name stored in a File object; you simply create a new File object each time you need to refer to a different file.

Example 10-3 is drawn from desktop Java, but the File object operates the same in Android as in Java SE.

import java.io.*;
import java.util.*;

/**
 * Report on a file's status in Java
 */
public class FileStatus {

    public static void main(String[] argv) throws IOException {
        // Ensure that a filename (or something) was given in argv[0]
        if (argv.length == 0) {
            System.err.println("Usage: FileStatus filename");
            System.exit(1);
        }

        for (int i = 0; i< argv.length; i++) {
            status(argv[i]);
        }
    }

    public static void status(String fileName) throws IOException {
        System.out.println("---" + fileName + "---");

        // Construct a File object for the given file
        File f = new File(fileName);

        // See if it actually exists
        if (!f.exists()) {
            System.out.println("file not found");
            System.out.println(); // Blank line
            return;
        }

        // Print full name
        System.out.println("Canonical name " + f.getCanonicalPath());

        // Print parent directory if possible
        String p = f.getParent();
        if (p != null) {
            System.out.println("Parent directory: " + p);
        }

        // Check our permissions on this file
        if (f.canRead()) {
            System.out.println("File is readable by us.");
        }
        // Check if the file is writable
        if (f.canWrite()) {
            System.out.println("File is writable by us.");
        }

        // Report on the modification time
        Date d = new Date();
        d.setTime(f.lastModified());
        System.out.println("Last modified " + d);

        // See if file, directory, or other. If file, print size.
        if (f.isFile()) {
            // Report on the file's size
            System.out.println("File size is " + f.length() + " bytes.");
        } else if (f.isDirectory()) {
            System.out.println("It's a directory");
        } else {
            System.out.println("So weird, man! Neither a file nor a directory!");
        }

        System.out.println(); // Blank line between entries
    }
}

Take a look at the output produced when the program is run (on MS Windows) with the three command-line arguments shown, it produces the output shown here:

C:javasrcdir_file> java FileStatus / /tmp/id /autoexec.bat
---/---
Canonical name C:
File is readable.
File is writable.
Last modified Thu Jan 01 00:00:00 GMT 1970
It's a directory

---/tmp/id---
file not found

---/autoexec.bat---
Canonical name C:AUTOEXEC.BAT
Parent directory: 
File is readable.
File is writable.
Last modified Fri Sep 10 15:40:32 GMT 1999
File size is 308 bytes.

As you can see, the so-called canonical name not only includes a leading directory root of C:, but also has had the name converted to uppercase. You can tell I ran that on an older version of Windows. On Unix, it behaves differently, as you can see here:

$ java FileStatus / /tmp/id /autoexec.bat
---/---
Canonical name /
File is readable.
Last modified October 4, 1999 6:29:14 AM PDT
It's a directory

---/tmp/id---
Canonical name /tmp/id
Parent directory: /tmp
File is readable.
File is writable.
Last modified October 8, 1999 1:01:54 PM PDT
File size is 0 bytes.

---/autoexec.bat---

file not found

$

This is because a typical Unix system has no autoexec.bat file. And Unix filenames (like those on the filesystem inside your Android device, and those on a Mac) can consist of upper- and lowercase characters: what you type is what you get.

The java.io.File class also contains methods for working with directories. For example, to list the filesystem entities named in the current directory, just write:

String[] list = new File(".").list()

To get an array of already constructed File objects rather than strings, use:

File[] list = new File(".").listFiles();

You can display the result in a ListView (see Recipe 8.2).

Of course, there’s lots of room for elaboration. You could print the names in multiple columns across or down the screen in a TextView in a monospace font, since you know the number of items in the list before you print. You could omit filenames with leading periods, as does the Unix ls program, or you could print the directory names first, as some “file manager"–type programs do. By using listFiles(), which constructs a new File object for each name, you could print the size of each, as per the MS-DOS dir command or the Unix ls -l command. Or you could figure out whether each object is a file, a directory, or neither. Having done that, you could pass each directory to your top-level function, and you would have directory recursion (the equivalent of using the Unix find command, or ls -R, or the DOS DIR /S command). Quite the makings of a file manager application of your own!

A more flexible way to list filesystem entries is with list(FilenameFilter ff). FilenameFilter is a tiny interface with only one method: boolean accept(File inDir, String fileName). Suppose you want a listing of only Java-related files (*.java, *.class, *.jar, etc.). Just write the accept() method so that it returns true for these files and false for any others. Example 10-4 shows the Ls class warmed over to use a FilenameFilter instance.

import java.io.*;

/**
 * FNFilter - directory lister modified to use FilenameFilter
 */
public class FNFilter {
 public static String[] getListing(String startingDir) {
 // Generate the selective list, with a one-use File object
 String[] dir = new java.io.File(startingDir).list(new OnlyJava());
 java.util.Arrays.sort(dir); // Sorts by name
 return dir;
}

/** FilenameFilter implementation:
 * The accept() method only returns true for .java , .jar, and .class files.
 */
class OnlyJava implements FilenameFilter {
 public boolean accept(File dir, String s) {
 if (s.endsWith(".java") || s.endsWith(".jar") || s.endsWith(".dex"))
 return true;
 // Others: projects, ... ?
 return false;
 }
}

We could make the FilenameFilter a bit more flexible; in a full-scale application, the list of files returned by the FilenameFilter would be chosen dynamically, possibly automatically, based on what you were working on. File chooser dialogs implement this as well, allowing the user to select interactively from one of several sets of files to be listed. This is a great convenience in finding files, just as it is here in reducing the number of files that must be examined.

For the listFiles() method, there is an additional overload that accepts a FileFilter. The only difference is that FileFilter’s accept() method is called with a File object, whereas FileNameFilter’s is called with a filename string.

See Also

See Recipe 8.2 to display the results in your GUI. Chapter 11 of Java Cookbook, written by me and published by O’Reilly, has more information on file and directory operations.

Problem

The standard file-oriented Java I/O classes can only open files stored on “disk,” as described in Recipe 10.1. If you want to read a file that is a static part of your application (installed as part of the APK rather than downloaded), you can access it in one of two special places.

Solution

If you’d like to read a static file, you can place it either in the assets directory or in res/raw. For res/raw, open it with the getResources() and openRawResource() methods, and then read it normally. For assets, you access the file as a filesystem entry (see Recipe 10.1); Android maps this directory to file:///android_asset/ (note the triple slash and singular spelling of “asset”).

Discussion

We wish to read information from a file packaged with the Android application, so we will need to put the relevant file in the res/raw directory or the assets directory (and probably create the directory, since it is often not created by default).

If the file is stored in res/raw, the generated R class will have an ID for it, which we pass into openRawResource(). Then we will read the file using the returned InputStreamReader wrapped in a BufferedReader. Finally, we extract the string from the BufferedReader using the readLine() method.

If the file is stored in assets, it will appear to be in the file:///android_asset/ directory, which we can just open and read normally.

In both cases the IDE will ask us to enclose the readLine() function within a try-catch block since there is a possibility of it throwing an IOException.

For res/$$raw the file is named samplefile and is shown in Example 10-5.

InputStreamReader is =
    new InputStreamReader(this.getResources().openRawResource(R.raw.samplefile));
BufferedReader reader = new BufferedReader(is);
StringBuilder finalText = new StringBuilder();
String line;
try {
    while ((line = reader.readLine()) != null) {
        finalText.append(line);
    }
} catch (IOException e) {
    e.printStackTrace();
}
fileTextView = (TextView)findViewById(R.id.fileText);
fileTextView.setText(finalText.toString());

After reading the entire string, we set it to the TextView in the Activity.

When using the assets folder, the most common use is for loading a web resource into a WebView. Suppose we have samplefile.html stored in the assets folder; the code in Example 10-6 will load it into a web display.

webView = (WebView)findViewById(R.id.about_html);
webview.loadUrl("file:///android_asset/samplefile.html");

Figure 10-2 shows the result of both the text and HTML files.

Figure 10-2. File read from application resource

Source Download URL

The source code for this example is in the Android Cookbook repository, in the subdirectory StaticFileRead (see “Getting and Using the Code Examples”).

Problem

You want to find out the amount of total and available space on the SD card.

Solution

Use the StatFs and Environment classes from the android.os package to find the total and available space on the SD card.

Discussion

Here is some code that obtains the information:

StatFs statFs = new StatFs(Environment.getExternalStorageDirectory().getPath());
double bytesTotal = (long) statFs.getBlockSize() * (long) statFs.getBlockCount();
double megTotal = bytesTotal / 1048576;

To get the total space on the SD card, use StatFs in the android.os package. Use Environment.getExternalStorageDirectory().getPath() as a constructor parameter.

Then, multiply the block size by the number of blocks on the SD card:

(long) statFs.getBlockSize() * (long) statFs.getBlockCount();

To get size in megabytes, divide the result by 1048576. To get the amount of available space on the SD card, replace statFs.getBlockCount() with statFs.getAvailableBlocks():

(long) statFs.getBlockSize() * (long) statFs.getAvailableBlocks();

If you want to display the value with two decimal places you can use a DecimalFormat object from java.text:

DecimalFormat twoDecimalForm = new DecimalFormat("#.##");

Problem

You want to let the user specify one or more preferences values, and have them persisted across runs of the program.

Solution

Have your Preferences or Settings menu item or button load an Activity that subclasses PreferenceActivity; in its onCreate() method, load an XML PreferenceScreen.

Discussion

Android will happily maintain a SharedPreferences object for you in semipermanent storage. To retrieve settings from it, use:

sharedPreferences = PreferenceManager.getDefaultSharedPreferences(this);

This should be called in your main Activity’s onCreate() method, or in the onCreate() of any Activity that needs to view the user’s chosen preferences.

You do need to tell Android what values you want the user to be able to specify, such as name, Twitter account, favorite color, or whatever. You don’t use the traditional view items such as ListView or Spinner, but instead use the special Preference items. A reasonable set of choices are available, such as Lists, TextEdits, CheckBoxes, and so on, but remember, these are not the standard View subclasses. Example 10-7 uses a List, a TextEdit, and a CheckBox.

<PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android">

    <ListPreference
        android:key="listChoice"
        android:title="List Choice"
        android:entries="@array/choices"
        android:entryValues="@array/choices"
        />

    <PreferenceCategory
        android:title="Personal">

        <EditTextPreference
            android:key="nameChoice"
            android:title="Name"
            android:hint="Name"
        />

        <CheckBoxPreference
            android:key="booleanChoice"
            android:title="Binary Choice"
        />

    </PreferenceCategory>

</PreferenceScreen>

The PreferenceCategory in the XML allows you to subdivide your panel into labeled sections. It is also possible to have more than one PreferenceScreen if you have a large number of settings and want to divide it into “pages.” Several additional kinds of UI elements can be used in the XML PreferenceScreen; see the official documentation for details.

The PreferenceActivity subclass can consist of as little as this onCreate() method:

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

When activated, the PreferenceActivity looks like Figure 10-3.

When the user clicks, say, Name, an Edit dialog opens, as in Figure 10-4.

In the XML layout for the preferences screen, each preference setting is assigned a name or “key,” as in a Java Map or Properties object. The supported value types are the obvious String, int, float, and boolean. You use this to retrieve the user’s values, and you provide a default value in case the settings screen hasn’t been put up yet or in case the user didn’t bother to specify a particular setting:

String preferredName =
    sharedPreferences.getString("nameChoice", "No name");

Figure 10-3. Preferences screen

Figure 10-4. String edit dialog

Since the preferences screen does the editing for you, there is little need to set preferences from within your application. There are a few uses, though, such as remembering that the user has accepted an end-user license agreement, or EULA. The code for this would be something like the following:

sharedPreferences.edit().putBoolean("accepted EULA", true).commit();

When writing, don’t forget the commit()! And, for this particular use case, the EULA option should obviously not appear in the GUI, or the user could just set it there without having a chance to read and ignore the text of your license agreement.

Like many Android apps, this demo has no Back button from its preferences screen; the user simply presses the system’s Back button. When the user returns to the main Activity, a real app would operate based on the user’s choices. My demo app simply displays the values. This is shown in Figure 10-5.

Figure 10-5. Values the main Activity uses

There is no “official” way to add a Done button to an XML PreferenceScreen, but some developers use a generic Preference item:

<Preference android:title="@string/done"
    android:key="settingsDoneButton"
    />

You can then make this work like a Button just by giving it an OnClickListener (from Preference, not the normal one from View):

    // Set up our Done preference to function as a Button
    Preference button = findPreference("settingsDoneButton"); // NOI18N
    button.setOnPreferenceClickListener(
            new Preference.OnPreferenceClickListener() {
        @Override
        public boolean onPreferenceClick(Preference arg0) {
            finish();
            return true;
        }
    });

When building a full-size application, I like to define the keys used as strings, for stylistic reasons and to prevent misspellings. I create a separate XML resource file for these strings called, say, keys.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources>

<string translatable="false" name="key_enable_sync">KEY_ENABLE_SYNC</string>
<string translatable="false" name="key_sync_interval">KEY_SYNC_INTERVAL</string>
<string translatable="false" name="key_username">KEY_USERNAME</string>
<string translatable="false" name="key_password">KEY_PASSWORD</string>
...
</resources>

Note the use of translatable="false" to prevent translation accidents.

I can use these strings directly in the prefs.xml file, and in code using the Activity method getString():

<PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android">

    <PreferenceCategory android:title="Synchronization">
        <CheckBoxPreference
            android:key="@string/key_enable_synch"
            android:title="Enable Sync"
            android:hint="Sync"
            />

        <EditTextPreference
            android:key="@string/key_sync_interval"
            android:title="Sync Interval (minutes)"
            android:inputType="number"
            android:defaultValue="60"
        />
    ...
</PreferenceScreen>

Basically, that’s all you need: an XML PreferenceScreen to define the properties and how the user sets them; a call to getDefaultSharedPrefences(); and calls to getString(), getBoolean(), and so on on the returned SharedPreferences object. It’s easy to handle preferences this way, and it gives the Android system a feel of uniformity, consistency, and predictability that is important to the overall user experience.

Problem

Android provides a very easy way to set up default preferences by defining a PreferenceActivity and providing it a resource file, as discussed in Recipe 10.5. What is not clear is how to perform checks on preferences given by the user.

Solution

You can implement the PreferenceActivity method onSharedPreferenceChanged():

public void onSharedPreferenceChanged(SharedPreferences prefs, String key)

You perform your checks in this method’s body. If the check fails you can restore a default value for the preference. Be aware that even though the SharedPreferences will contain the right value, you won’t see it displayed correctly; for this reason, you need to reload the PreferenceActivity.

Discussion

If you have a default PreferenceActivity that implements On​ Sha⁠redPref⁠erenceChan⁠geList⁠ener, your PreferenceActivity can implement the on​ Sha⁠redPref⁠erenceChan⁠ged() method, as shown in Example 10-8.

public class MyPreferenceActivity extends PreferenceActivity
         implements OnSharedPreferenceChangeListener {

     public void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
          Context context = getApplicationContext();
          prefs = PreferenceManager.getDefaultSharedPreferences(context);
          addPreferencesFromResource(R.xml.userprefs);
    }

The onSharedPreferenceChanged() method will be called after the change is committed, so every other change you perform will be permanent.

The idea is to check whether the value is appropriate, and if not replace it with a default value or disable it.

To arrange to have this method called at the appropriate time, you have to register your Activity as a valid listener. A good way to do so is to register in onResume() and unregister in onPause():

    @Override
    protected void onResume() {
        super.onResume();
        prefs.registerOnSharedPreferenceChangeListener(this);
    }

    @Override
    protected void onPause() {
        super.onPause();
        prefs.unregisterOnSharedPreferenceChangeListener(this);
    }

Now it’s time to perform the consistency check. For example, if you have an option whose key is MY_OPTION_KEY, you can use the code in Example 10-9 to check and allow/disallow the value.

public void onSharedPreferenceChanged(SharedPreferences prefs, String key) {
     SharedPreferences.Editor prefEditor = prefs.edit();

     if(key.equals(MY_OPTION_KEY)) {
          String optionValue = prefs.getString(MY_OPTION_KEY, "");
          if(dontLikeTheValue(optionValue)) {
               prefEditor.putString(MY_OPTION_KEY, "Default value");
               prefEditor.commit();
               reload();
          }
     }
     return;
}

Of course, if the check fails the user will be surprised and will not know why you refused his option. You can then show an error dialog and perform the reload action after the user confirms the dialog (see Example 10-10).

private void showErrorDialog(String errorString) {
     String okButtonString = context.getString(R.string.ok_name);
     AlertDialog.Builder ad = new AlertDialog.Builder(context);
     ad.setTitle(context.getString(R.string.error_name));
     ad.setMessage(errorString);
     ad.setPositiveButton(okButtonString,new OnClickListener() {
          public void onClick(DialogInterface dialog, int arg1) {
               reload();
          }
     } );
     ad.show();
     return;
}

In this way, the dontLikeTheValue() “if” becomes:

     if(dontLikeTheValue(optionValue)) {
          if(!GeneralUtils.isPhoneNumber(smsNumber)) {
               showErrorDialog("I dont like the option");
               prefEditor.putString(MY_OPTION_KEY, "Default value");
               prefEditor.commit();
          }
     }

What’s still missing is the reload() function, but it’s pretty obvious. It relaunches the Activity using the same Intent that fired it:

private void reload() {
     startActivity(getIntent());
     finish();
}

Problem

You want data you save to last longer than the application’s run, and you want to access that data in a standardized way.

Solution

SQLite is a popular relational database using the SQL model that you can use to store application data. To access it in Android, create and use a class that subclasses SQLiteOpenHelper.

Discussion

SQLite is used in many platforms, not just Android. While SQLite provides an API, many systems (including Android) develop their own APIs for their particular needs.

public class SqlOpenHelper extends SQLiteOpenHelper {

    public static final String DBNAME = "tasksdb.sqlite";
    public static final int VERSION =1;
    public static final String TABLE_NAME = "tasks";
    public static final String ID= "id";
    public static final String NAME="name";

    public SqlOpenHelper(Context context) {
        super(context, DBNAME, null, VERSION);
    }

CREATE TABLE some_table_name (
    _id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
    name TEXT);

    public void onCreate(SQLiteDatabase db) {
        createDatabase(db);
    }

    private void createDatabase(SQLiteDatabase db) {
        db.execSQL("create table " + TABLE_NAME + "(" +
            ID + " integer primary key autoincrement not null, " +
            NAME + " text "
            + ");"
            );
    }

    SqlOpenHelper helper = new SqlOpenHelper(this);
    SQLiteDatabase database= helper.getWritableDatabase();

ContentValues values = new ContentValues();
values.put(NAME, "Mangoes");
long id = (database.insert(TABLE_NAME, null, values));

ArrayList<Food> foods = new ArrayList();
Cursor listCursor = database.query(TABLE_NAME,
    new String [] {ID, NAME},
    null, null, null, null, NAME);
while (listCursor.moveToNext()) {
    Long id = listCursor.getLong(0);
    String name= listCursor.getString(1);
    Food t = new Food(name);
    foods.add(t);
}
listCursor.close();

Cursor query(String tableName, String[] columns, String selection,
    String[] selectionArgs, String groupBy, String having, String orderBy)

Cursor custCursor =
    db.query("customer", "age > ? AND state = ? and COUNTRY = ?",
    new String[] { Integer.toString(minAge), "NY", "US" },
    null, null, "lastname ASC");

Problem

You want to implement an advanced “search” capability, and you need to know how to build a data layer to store and search text data using SQLite’s full-text search extension.

Solution

Use a SQLite Full-Text Search 3 (FTS3) virtual table and the MATCH function from SQLite to build such a mechanism.

Discussion

By following these steps, you will be able to create an example Android project with a data layer where you will be able to store and retrieve some data using a SQLite database:

1. Create a new Android project (AdvancedSearchProject) targeting a current API level.

2. Specify AdvancedSearch as the application name.

3. Use com.androidcookbook.example.advancedsearch as the package name.

4. Create an Activity with the name AdvancedSearchActivity.

5. Create a new Java class called DbAdapter within the package com.androidcookbook.example.advancedsearch in the src folder.

To create the data layer for the example application, enter the Example 10-12 source code in the created file.

public class DbAdapter {
    public static final String APP_NAME = "AdvancedSearch";
    private static final String DATABASE_NAME = "AdvancedSearch_db";
    private static final int DATABASE_VERSION = 1;
    // Our internal database version (e.g., to control upgrades)
    private static final String TABLE_NAME = "example_tbl";
    public static final String KEY_USERNAME = "username";
    public static final String KEY_FULLNAME = "fullname";
    public static final String KEY_EMAIL = "email";
    public static long GENERIC_ERROR = -1;
    public static long GENERIC_NO_RESULTS = -2;
    public static long ROW_INSERT_FAILED = -3;
    private final Context context;
    private DbHelper dbHelper;
    private SQLiteDatabase sqlDatabase;

    public DbAdapter(Context context) {
        this.context = context;
    }

    private static class DbHelper extends SQLiteOpenHelper {
        private boolean databaseCreated=false;
        DbHelper(Context context) {
            super(context, DATABASE_NAME, null, DATABASE_VERSION);
        }
        @Override
        public void onCreate(SQLiteDatabase db) {
            Log.d(APP_NAME, "Creating the application database");

            try {
                // Create the FTS3 virtual table
                db.execSQL(
                    "CREATE VIRTUAL TABLE ["+TABLE_NAME+"] USING FTS3 (" +
                        "["+KEY_USERNAME+"] TEXT," +
                        "["+KEY_FULLNAME+"] TEXT," +
                        "["+KEY_EMAIL+"] TEXT" +
                    ");"
                );
                this.databaseCreated = true;
            } catch (Exception e) {
                Log.e(APP_NAME,
                "An error occurred while creating the database: " + e.toString(), e);
                this.deleteDatabaseStructure(db);
            }
        }
        public boolean databaseCreated() {
            return this.databaseCreated;
        }
        private boolean deleteDatabaseStructure(SQLiteDatabase db) {
            try {
                db.execSQL("DROP TABLE IF EXISTS ["+TABLE_NAME+"];");
                return true;
            } catch (Exception e) {
                Log.e(APP_NAME,
                "An error occurred while deleting the database: " + e.toString(), e);
            }
            return false;
        }
    }

    /**
     * Open the database; if the database can't be opened, try to create it
     *
     * @return {@link Boolean} true if database opened/created OK, false otherwise
     * @throws {@link SQLException] if an error occurred
     */
    public boolean open() throws SQLException {
        try {
            this.dbHelper = new DbHelper(this.context);
            this.sqlDatabase = this.dbHelper.getWritableDatabase();
            return this.sqlDatabase.isOpen();
        } catch (SQLException e) {
            throw e;
        }
    }

    /**
     * Close the database connection
     * @return {@link Boolean} true if the connection was terminated, false otherwise
     */
    public boolean close() {
        this.dbHelper.close();
        return !this.sqlDatabase.isOpen();
    }

    /**
     * Check if the database was opened
     *
     * @return {@link Boolean} true if it was, false otherwise
     */
    public boolean isOpen() {
        return this.sqlDatabase.isOpen();
    }

    /**
     * Check if the database was created
     *
     * @return {@link Boolean} true if it was, false otherwise
     */
    public boolean databaseCreated() {
        return this.dbHelper.databaseCreated();
    }

    /**
     * Insert a new row i3n the table
     *
     * @param username {@link String} with the username
     * @param fullname {@link String} with the fullname
     * @param email {@link String} with the email
     * @return {@link Long} with the row ID or ROW_INSERT_FAILED (value < 0) on error
     */
    public long insertRow(String username, String fullname, String email) {
        try{
            // Prepare the values
            ContentValues values = new ContentValues();
            values.put(KEY_USERNAME, username);
            values.put(KEY_FULLNAME, fullname);
            values.put(KEY_EMAIL, email);

            // Try to insert the row
            return this.sqlDatabase.insert(TABLE_NAME, null, values);
         }catch (Exception e) {
            Log.e(APP_NAME,
                "An error occurred while inserting the row: "+e.toString(), e);
        }
        return ROW_INSERT_FAILED;
    }

    /**
     * The search() method uses the FTS3 virtual table and
     * the MATCH function from SQLite to search for data.
     * @see http://www.sqlite.org/fts3.html to know more about the syntax.
     * @param search {@link String} with the search expression
     * @return {@link LinkedList} with the {@link String} search results
     */
    public LinkedList<String> search(String search) {

        LinkedList<String> results = new LinkedList<String>();
        Cursor cursor = null;
        try {
            cursor = this.sqlDatabase.query(true, TABLE_NAME, new String[] {
                KEY_USERNAME, KEY_FULLNAME, KEY_EMAIL }, TABLE_NAME + " MATCH ?",
                new String[] { search }, null, null, null, null);

            if(cursor!=null && cursor.getCount()>0 && cursor.moveToFirst()) {
                int iUsername = cursor.getColumnIndex(KEY_USERNAME);
                int iFullname = cursor.getColumnIndex(KEY_FULLNAME);
                int iEmail = cursor.getColumnIndex(KEY_EMAIL);

                do {
                    results.add(
                        new String(
                            "Username: "+cursor.getString(iUsername) +
                            ", Fullname: "+cursor.getString(iFullname) +
                            ", Email: "+cursor.getString(iEmail)
                        )
                    );
                } while(cursor.moveToNext());
            }
        } catch(Exception e) {
            Log.e(APP_NAME,
               "An error occurred while searching for "+search+": "+e.toString(), e);
        } finally {
            if(cursor!=null && !cursor.isClosed()) {
                cursor.close();
            }
        }

        return results;
    }
}

Now that the data layer is usable, the AdvancedSearchActivity can be used to test it.

To define the application strings, replace the contents of the res/values/strings.xml file with the following:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="label_search">Search</string>
    <string name="app_name">AdvancedSearch</string>
</resources>

The application layout can be set within the file res/layout/main.xml. This contains the expected EditText (named etSearch), a Button (named btnSearch), and a TextView (named tvResults) to display the results, all in a LinearLayout.

Finally, Example 10-13 shows the AdvancedSearchActivity.java code.

public class AdvancedSearchActivity extends Activity {
    private DbAdapter dbAdapter;
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);

        dbAdapter = new DbAdapter(this);
        dbAdapter.open();

        if(dbAdapter.databaseCreated()) {
            dbAdapter.insertRow("test", "test example", "[email protected]");
            dbAdapter.insertRow("lorem", "lorem ipsum", "[email protected]");
            dbAdapter.insertRow("jdoe", "Jonh Doe", "[email protected]");
        }

        Button button = (Button) findViewById(R.id.btnSearch);
        final EditText etSearch = (EditText) findViewById(R.id.etSearch);
        final TextView tvResults = (TextView) findViewById(R.id.tvResults);
        button.setOnClickListener(new View.OnClickListener() {
            public void onClick(View v) {
                LinkedList<String> results =
                    dbAdapter.search(etSearch.getText().toString());

                if(results.isEmpty()) {
                    tvResults.setText("No results found");
                } else {
                    Iterator<String> i = results.iterator();
                    tvResults.setText("");
                    while(i.hasNext()) {
                        tvResults.setText(tvResults.getText()+i.next()+"
");
                    }
                }
            }
        });
    }
    @Override
    protected void onDestroy() {
        dbAdapter.close();
        super.onDestroy();
    }
}

See Also

See the SQLite website to learn more about the Full-Text Search 3 extension module’s capabilities, including the search syntax, and localizeandroid to learn about a project with an implementation of this search mechanism.

Problem

Android’s embedded SQLite3 database supports date and time data directly, including some useful date and time arithmetic. However, getting these dates out of the database is troublesome: there is no Cursor.getDate() in the Android API.

Solution

Use SQLite’s strftime() function to convert between the SQLite timestamp format and the Java API’s “milliseconds since the epoch” representation.

Discussion

This recipe demonstrates the advantages of using SQLite timestamps over storing raw millisecond values in your database, and shows how to retrieve those timestamps from your database as java.util.Date objects.

CREATE TABLE current_list (
        item_id INTEGER NOT NULL,
        added_on TIMESTAMP NOT NULL DEFAULT current_timestamp,
        added_by VARCHAR(50) NOT NULL,
        quantity INTEGER NOT NULL,
        units VARCHAR(50) NOT NULL,
        CONSTRAINT current_list_pk PRIMARY KEY (item_id)
);

sqlite> insert into current_list (item_id, added_by, quantity, units)
   ...> values (1, 'fuerth', 1, 'EA');
sqlite> select * from current_list where item_id = 1;
1|2020-05-14 23:10:26|fuerth|1|EA
sqlite>

sqlite> select item_id, date(added_on,'start of day')
   ...> from current_list where item_id = 1;
1|2020-05-14
sqlite>

sqlite> select item_id, date(added_on,'weekday 1')
   ...> from current_list where item_id = 1;
1|2020-05-17
sqlite>

sqlite> select item_id, date(added_on,'weekday 1','-7 days')
   ...> from current_list where item_id = 1;
1|2020-05-10
sqlite>

Cursor cursor = database.rawQuery(
        "SELECT item_id AS _id," +
        " (strftime('%s', added_on) * 1000) AS added_on," +
        " added_by, quantity, units" +
        " FROM current_list", new String[0]);
long millis = cursor.getLong(cursor.getColumnIndexOrThrow("added_on"));
Date addedOn = new Date(millis);

See Also

SQLite’s documentation for its date and time functions.

Problem

You have non-SQL data, such as a list of files, and want to present it as a Cursor.

Solution

Subclass AbstractCursor and implement various required methods.

Discussion

It is common to have data in a form other than a Cursor, but to want to present it as a Cursor for use in a ListView with an Adapter or a CursorLoader.

The AbstractCursor class facilitates this. While Cursor is an interface that you could implement directly, there are a number of routines therein that are pretty much the same in every implementation of Cursor, so they have been abstracted out and made into the AbstractCursor class.

In this short example we expose a list of filenames with the following structure:

• _id is the sequence number.

• filename is the full path.

• type is the filename extension.

This list of files is hardcoded to simplify the demo. We will expose this as a Cursor and consume it in a SimpleCursorAdapter. First, the start of the DataToCursor class:

/**
 * Provide a Cursor from a fixed list of data
 * column 1 - _id
 * column 2 - filename
 * column 3 - file type
 */
public class DataToCursor extends AbstractCursor {

    private static final String[] COLUMN_NAMES = {"_id", "filename", "type"};

    private static final String[] DATA_ROWS = {
        "one.mpg",
        "two.jpg",
        "tre.dat",
        "fou.git",
    };

As you can see, there are two arrays: one for the column names going across, and one for the rows going down. In this simple example we don’t have to track the ID values (since they are the same as the index into the DATA_ROWS array) or the file types (since they are the same as the filename extension).

There are a few structural methods that are needed:

@Override
public int getCount() {
    return DATA.length;
}

@Override
public int getColumnCount() {
    return COLUMN_NAMES.length;
}

@Override
public String[] getColumnNames() {
    return COLUMN_NAMES;
}

The getColumnCount() method’s value is obviously derivable from the array, but since it’s constant, we override the method for efficiency reasons—probably not necessary in most applications.

Then there are some necessary get methods, notably getType() for getting the type of a given column (whether it’s numeric, string, etc.):

@Override
public int getType(int column) {
    switch(column) {
    case 0:
        return Cursor.FIELD_TYPE_INTEGER;
    case 1:
    case 2:
        return Cursor.FIELD_TYPE_STRING;
    default: throw new IllegalArgumentException(Integer.toString(column));
    }
}

The next methods have to do with getting the value of a given column in the current row. Nicely, the AbstractCursor handles all the moveToRow() and related methods, so we just have to call the inherited (and protected) method getPosition():

/**
* Return the _id value (the only integer-valued column).
* Conveniently, rows and array indices are both 0-based.
*/
@Override
public int getInt(int column) {
    int row = getPosition();
    switch(column) {
        case 0: return row;
        default: throw new IllegalArgumentException(Integer.toString(column));
    }
}

/** SQLite _ids are actually long, so make this work as well.
* This direct equivalence is usually not applicable; do not blindly copy.
*/
@Override
public long getLong(int column) {
    return getInt(column);
}

@Override
public String getString(int column) {
    int row = getPosition();
    switch(column) {
        case 1: return DATA_ROWS[row];
        case 2: return extension(DATA_ROWS[row]);
        default: throw new IllegalArgumentException(Integer.toString(column));
    }
}

The remaining methods aren’t interesting; methods like getFloat(), getBlob(), and so on merely throw exceptions as, in this example, there are no columns of those types.

The main Activity shows nothing different than the other ListView examples in Chapter 8: the data from the Cursor is loaded into a ListView using a SimpleCursorAdapter (this overload of which is deprecated, but works fine for this example).

The result is shown in Figure 10-6.

Figure 10-6. Main Activity with synthetic Cursor data

We have successfully shown this proof-of-concept of generating a Cursor without using SQLite. It would obviously be straightforward to turn this into a more dynamic file-listing utility, even a file manager. You’d want to use a CursorLoader instead of a SimpleCursorAdapter to make it complete, though; CursorLoader is covered in the next recipe.

Problem

You need to fetch information via a database Cursor and display it in a graphical user interface with correct use of threads to avoid blocking the UI thread.

Solution

Use a CursorLoader.

Discussion

Loader is a top-level class that provides a basic capability for loading almost any type of data. AsyncTaskLoader<T> provides a specialization of Loader to handle threading. Its important subclass is CursorLoader, which is used to load data from a database Cursor and, typically in conjunction with a Fragment or Activity, to display it. The Android documentation for AsyncTaskLoader<T> shows a comprehensive example of loading the list of all applications installed on a device, and keeping that information up-to-date as it changes. We will start with something a bit simpler, which reads (as CursorLoader classes are expected to) a list of data from a ContentProvider implementation, and displays it in a list. To keep the example simple, we’ll use the preinstalled Browser Bookmarks content provider. (Note that this content provider is not available in Android 7 or later). The application will provide a list of installed bookmarks, similar to that shown in Figure 10-7.

Figure 10-7. CursorLoader showing Browser Bookmarks

To use the Loader, you have to provide an implementation of the LoaderManager.LoaderCallbacks<T> interface, where T is the type you want to load from; in our case, Cursor. While most examples have the Activity or Fragment directly implement this, we’ll make it an inner class just to isolate it, and make more of the argument types explicit.

We start off in onCreate() or onResume() by creating a SimpleCursorAdapter. The constructor for this adapter—the mainstay of many a list-based application in prior releases of Android—is now deprecated, but calling it with an additional flags argument (the final 0 argument here) for use with the Loader family is not deprecated. Other than the final flags arg, and passing null for the Cursor, the code is largely the same as our non-Loader-based example, ContentProviderBookmarks, which has been left in the Android Cookbook repository to show “the old way.” With the extra flags argument the Cursor may be null, as we will provide it later, in the LoaderCallbacks code (Example 10-14):

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

    String[] fromFields = new String[] {
            Browser.BookmarkColumns.TITLE,
            Browser.BookmarkColumns.URL
    };
    int[] toViews = new int[] { android.R.id.text1, android.R.id.text2 };
    mAdapter = new SimpleCursorAdapter(this, android.R.layout.simple_list_item_2,
            null, fromFields, toViews, 0);
    setListAdapter(mAdapter);

    // Prepare the loader: reconnects an existing one or reuses one
    getLoaderManager().initLoader(0, null, new MyCallbacks(this));
}

Note also the last line, which will find a Loader instance and associate our callbacks with it. The callbacks are where the actual work gets done. There are three required methods in the LoaderCallbacks object:

onCreateLoader()

Called to create an instance of the actual loader; the framework will start it, which will perform a ContentProvider query

onLoadFinished()

Called when the loader has finished loading its data, to set its cursor to the one from the query

onLoaderReset()

Called when the loader is done, to disassociate it from the view (by setting its cursor back to null)

Our implementation is fairly simple. As we want all the columns and don’t care about the order, we only need to provide the bookmarks Uri, which is predefined for us (see Example 10-14).

class MyCallbacks implements LoaderCallbacks<Cursor> {
    Context context;

    public MyCallbacks(Activity context) {
        this.context = context;
    }

    @Override
    public Loader<Cursor> onCreateLoader(int id, Bundle stuff) {
        Log.d(TAG, "MainActivity.onCreateLoader()");
        return new CursorLoader(context,
                // Normal CP query: url, proj, select, where, having
                Browser.BOOKMARKS_URI, null, null, null, null);
    }

    @Override
    public void onLoadFinished(Loader<Cursor> loader, Cursor data) {
        // Load has finished, swap the loaded cursor into the view
        mAdapter.swapCursor(data);
    }

    @Override
    public void onLoaderReset(Loader<Cursor> loader) {
        // The end of time: set cursor to null to prevent bad ending
        mAdapter.swapCursor(null);
    }
}

The Loader family is quite sophisticated; it lets you load a Cursor in the background then adapt it to the GUI. The AsyncTaskLoader<T>, as the name implies, uses an AsyncTask (see Recipe 4.10) to do the data loading on a background thread and runs the updating on the UI thread. Its subclass, the CursorLoader, is now the tool of choice for loading lists of data.

Source Download URL

The source code for this example is in the Android Cookbook repository, in the subdirectory CursorLoaderDemo (see “Getting and Using the Code Examples”).

Problem

JavaScript Object Notation (JSON) is a simple text format for data interchange. Many websites provide data in JSON, and many applications need to parse and provide JSON data.

Solution

While there are a couple of dozen Java APIs for JSON listed on the JSON website, we’ll use the built-in JSONObject class to parse JSON and retrieve the data values contained in it.

Discussion

For this recipe, we will use a method to generate JSON code. In a real application you would likely obtain the JSON data from some web service. In this method we make use of a JSONObject class object to put in values and then to return the corresponding string (using the toString() method). Creating an object of type JSONObject can throw a JSONException, so we enclose the code in a try-catch block (see Example 10-15).

private String getJsonString() {
    JSONObject string = new JSONObject();
    try {
        string.put("name", "John Doe");
        string.put("age", new Integer(25));
        string.put("address", "75 Ninth Avenue, New York, NY 10011");
        string.put("phone", "8367667829");
    } catch (JSONException e) {
        e.printStackTrace();
    }
    return string.toString();
}

We need to instantiate an object of class JSONObject that takes the JSON string as an argument. In this case, the JSON string is being obtained from the getJsonString() method. We extract the information from the JSONObject and print it in a TextView (see Example 10-16).

try {
    String jsonString = getJsonString();
    JSONObject jsonObject = new JSONObject(jsonString);
    String name = jsonObject.getString("name");
    String age = jsonObject.getString("age");
    String address = jsonObject.getString("address");
    String phone = jsonObject.getString("phone");
    String jsonText = name + "
" + age + "
" + address + "
" + phone;
    json = (TextView)findViewById(R.id.json);
    json.setText(jsonText);
} catch (JSONException e) {
    // Display the exception...
}

See Also

For more information on JavaScript Object Notation, see the JSON website.

There are about two dozen JSON APIs for Java alone. One of the more powerful ones—which includes a data-binding package that will automatically convert between Java objects and JSON—is JackSON.

Source Download URL

The source code for this project is in the Android Cookbook repository, in the subdirectory JSONParsing (see “Getting and Using the Code Examples”).

Problem

You have data in XML, and you want to transform it into something useful in your application.

Solution

Android provides a fairly good clone of the standard DOM API used in the Java Standard Edition. Using the DOM API instead of writing your own parsing code is clearly the more efficient approach.

Discussion

Example 10-17 is the code that parses the XML document containing the list of recipes in this book, as discussed in Recipe 12.1. The input file has a single recipes root element, followed by a sequence of recipe elements, each with an id and a title with textual content.

The code creates a DOM DocumentBuilderFactory, which can be tailored, for example, to make schema-aware parsers. In real code you could create this in a static initializer instead of re-creating it each time. The DocumentBuilderFactory is used to create a document builder, a.k.a. parser. The parser expects to be reading from an InputStream, so we convert the data that we have in string form into an array of bytes and construct a ByteArrayInputStream. Again, in real life you would probably want to combine this code with the web service consumer so that you could simply get the input stream from the network connection and read the XML directly into the parser, instead of saving it as a string and then wrapping that in a converter as we do here.

Once the elements are parsed, we convert the document into an array of data (the singular of data is datum, so the class is called Datum) by calling tDOM API methods such as getDocumentElement(), getChildNodes(), and getNodeValue(). Since the DOM API was not invented by Java people, it doesn’t use the standard Collections API but has its own collections, like NodeList. In DOM’s defense, the same or similar APIs are used in a really wide variety of programming languages, so it can be said to be as much a standard as Java’s Collections.

Example 10-17 shows the code.

/** Convert the list of Recipes in the String result from the
 * web service into an ArrayList of Datum objects.
 * @throws ParserConfigurationException
 * @throws IOException
 * @throws SAXException
 */
public static ArrayList<Datum> parse(String input) throws Exception {

    final ArrayList<Datum> results = new ArrayList<Datum>(1000);
    final DocumentBuilderFactory dbFactory =
        DocumentBuilderFactory.newInstance();
    final DocumentBuilder parser = dbFactory.newDocumentBuilder();

    final Document document =
        parser.parse(new ByteArrayInputStream(input.getBytes()));

    Element root = document.getDocumentElement();
    NodeList recipesList = root.getChildNodes();
    for (int i = 0; i < recipesList.getLength(); i++) {
        Node recipe = recipesList.item(i);
        NodeList fields = recipe.getChildNodes();
        String id = ((Element) fields.item(0)).getNodeValue();
        String title =
            ((Element) fields.item(1)).getNodeValue();
        Datum d = new Datum(Integer.parseInt(id), title);
        results.add(d);
    }
    return results;
}

In converting this code from Java SE to Android, the only change we had to make was to use getNodeValue() in the retrieval of id and title instead of Java SE’s getTextContent(), so the API really is very close.

See Also

The web service is discussed in Recipe 12.1. There is much more in the XML chapter of my Java Cookbook (O’Reilly).

Should you wish to process XML in a streaming mode, you can use the XMLPullParser, documented in the online version of this Cookbook.

Problem

You want to read from and write to a ContentProvider such as Contacts.

Solution

One way is to create a Content Uri using constants provided by the ContentProvider and use Activity.getContentResolver().query(), which returns a SQLite Cursor object. Another way, useful if you want to select one record such as a single contact, is to create a PICK Uri, open it in an Intent using startActivityForResult(), extract the URI from the returned Intent, then perform the query as just described.

Discussion

This is part of the contact selection code from TabbyText, my SMS-over-WiFi text message sender (the rest of its code is in Recipe 10.17).

First, the main program sets up an OnClickListener to use the Contacts app as a chooser, from a Find Contact button:

b.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View arg0) {
        Uri uri = ContactsContract.Contacts.CONTENT_URI;
        System.out.println(uri);
        Intent intent = new Intent(Intent.ACTION_PICK, uri);
        startActivityForResult(intent, REQ_GET_CONTACT);
    }
});

The URI is predefined for us; it actually has the value content://com.android.contacts/contacts. The constant REQ_GET_CONTACT is arbitrary; it’s just there to associate this Intent start-up with the handler code, since more complex apps will often start more than one Intent and they need to handle the results differently. Once this button is pressed, control passes from our app out to the Contacts app. The user can then select a contact she wishes to send an SMS message to. The Contacts app then is backgrounded and control returns to our app at the onActivityResult() method, to indicate that the Activity we started has completed and delivered a result.

The next bit of code shows how the onActivityResult() method converts the response from the Activity into a SQLite cursor (see Example 10-18).

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQ_GET_CONTACT) {
        switch(resultCode) {
        case Activity.RESULT_OK:
        // The Contacts API is about the most complex to use.
        // First retrieve the Contact, as we only get its URI from the Intent.
        Uri resultUri = data.getData(); // E.g., content://contacts/people/123
        Cursor cont = getContentResolver().query(resultUri, null, null, null, null);
        if (!cont.moveToNext()) {    // Expect exactly one row
            Toast.makeText(this, "Cursor has no data", Toast.LENGTH_LONG).show();
            return;
        }
        ...

There are a few key things to note here. First, make sure the request Code is the one you started, and the resultCode is RESULT_OK or RESULT_CANCELED (if not, pop up a warning dialog). Then, extract the URL for the response you picked—the Intent data from the returned Intent—and use that to create a query, using the inherited Activity method getContentResolver() to get the ContentResolver and its query() method to make up a SQLite cursor.

We expect the user to have selected one contact, so if that’s not the case we error out. Otherwise, we’d go ahead and use the SQLite cursor to read the data. The exact formatting of the Contacts database is a bit out of scope for this recipe, so it’s been deferred to Recipe 10.17.

To insert data, we need to create a ContentValues object and populate it with the fields. Once that’s done, we use the ContentContracts-provided base Uri value, along with the ContentValues, to insert the values, somewhat like the following:

mNewUri = getContentResolver().
    insert(ContactsContract.Contacts.CONTENT_URI, contentValues);

You could then put the mNewUri into an Intent and display it.

This is shown in more detail in Recipe 10.16.

Problem

You want to expose data from your application without giving direct access to your application’s database.

Solution

Write a ContentProvider that will allow other applications to access data contained in your app.

Discussion

ContentProviders allow other applications to access the data generated by your app. A custom ContentProvider is effectively a wrapper around your existing application data (typically but not necessarily contained in a SQLite database; see Recipe 10.7). Remember that just because you can do so doesn’t mean that you should; in particular, you generally do not need to write a ContentProvider just to access your data from within your application.

To make other apps aware that a ContentProvider is available, we need to declare it in AndroidManifest.xml as follows:

<application ...>
    <activity .../>
    <provider
        android:authorities="com.example.contentprovidersample"
        android:name="MyContentProvider" />
</application>

The android:authorities attribute is a string used throughout the system to identify your ContentProvider; it should also be declared in a public static final String variable in your provider class. The android:name attribute refers to the class MyContentProvider, which extends the ContentProvider class. We need to override the following methods in this class:

onCreate();
getType(Uri);

insert(Uri, ContentValues);
query(Uri, String[], String, String[], String);
update(Uri, ContentValues, String, String[]);
delete(Uri, String, String[]);

The onCreate() method is for setup, as in any other Android component. Our example just creates a SQLite database in a field:

mDatabase = new MyDatabaseHelper(this);

The getType() method assigns MIME types to incoming Uri values. This method will typically use a statically allocated UriMatcher to determine whether the incoming Uri refers to a list of values (does not end with a numeric ID) or a single value (ends with a / and a numeric ID, indicated by “/#” in the pattern argument). The method must return either ContentResolver.CURSOR_ITEM_BASE_TYPE + "/" + MIME_VND_TYPE for a single item or ContentResolver.CURSOR_DIR_BASE_TYPE + "/" + MIME_VND_TYPE for a multiplicity, where MIME_VND_TYPE is an application-specific MIME type string; in our example that’s “vnd.example.item”. It must begin with “vnd,” which stands, throughout this paragraph, for “Vendor,” as these values are not provided by the official MIME type committee but by Android. The UriMatcher is also used in the four data methods shown next to sort out singular from plural requests. Example 10-19 contains the declarations and code for the matcher and the getType() method.

public class MyContentProvider extends ContentProvider {

    /** The authority name. MUST be as listed in
     * <provider android:authorities=...> in AndroidManifest.xml
     */
    public static final String AUTHORITY = "com.example.contentprovidersample";

    public static final String MIME_VND_TYPE = "vnd.example.item";

    private static final UriMatcher matcher = new UriMatcher(UriMatcher.NO_MATCH);

    private static final int ITEM = 1;
    private static final int ITEMS = 2;
    static {
        matcher.addURI(AUTHORITY, "items/#", ITEM);
        matcher.addURI(AUTHORITY, "items", ITEMS);
    }

    @Override
    public String getType(Uri uri) {
        int matchType = matcher.match(uri);
        Log.d("ReadingsContentProvider.getType()", uri + " --> " + matchType);
        switch (matchType) {
        case ITEM:
            return ContentResolver.CURSOR_ITEM_BASE_TYPE + "/" + MIME_VND_TYPE;
        case ITEMS:
            return ContentResolver.CURSOR_DIR_BASE_TYPE + "/" + MIME_VND_TYPE;
        default:
            throw new IllegalArgumentException("Unknown or Invalid URI " + uri);
        }
    }

The last four methods are usually wrapper functions for SQL queries on the SQLite database; note that they have the same parameter lists as the like-named SQLite methods, with the insertion of a Uri at the front of the parameter list. These methods typically parse the input parameters, do some error checking, and forward the operation on to the SQLite database, as shown in Example 10-20.

    /** The C of CRUD: insert() */
    @Override
    public Uri insert(Uri uri, ContentValues values) {
        Log.d(Constants.TAG, "MyContentProvider.insert()");
        switch(matcher.match(uri)) {
        case ITEM: // Fail
            throw new RuntimeException("Cannot specify ID when inserting");
        case ITEMS: // OK
            break;
        default:
            throw new IllegalArgumentException("Did not recognize URI " + uri);
        }

        long id = mDatabase.getWritableDatabase().insert(
                TABLE_NAME, null, values);
        uri = Uri.withAppendedPath(uri, "/" + id);
        getContext().getContentResolver().notifyChange(uri, null);
        return uri;
    }

    /** The R of CRUD: query() */
    @Override
    public Cursor query(Uri uri, String[] projection, String selection,
            String[] selectionArgs, String sortOrder) {
        Log.d(Constants.TAG, "MyContentProvider.query()");
        switch(matcher.match(uri)) {
        case ITEM: // OK
            selection = "_id = ?";
            selectionArgs = new String[]{ Long.toString(ContentUris.parseId(uri)) };
            break;
        case ITEMS: // OK
            break;
        default:
            throw new IllegalArgumentException("Did not recognize URI " + uri);
        }
        // Build the query with SQLiteQueryBuilder
        SQLiteQueryBuilder qBuilder = new SQLiteQueryBuilder();
        qBuilder.setTables(TABLE_NAME);

        // Query the database and get result in cursor
        final SQLiteDatabase db = mDatabase.getWritableDatabase();
        Cursor resultCursor = qBuilder.query(db,
                projection, selection, selectionArgs, null, null, sortOrder,
                null);
        resultCursor.setNotificationUri(getContext().getContentResolver(), uri);
        return resultCursor;
    }
}

The remaining methods, update() and delete(), are parallel in structure and so have been omitted from this book to save space, but the online example is fully fleshed out.

Providing a ContentProvider lets you expose your data without giving other developers direct access to your database and also reduces the chances of database inconsistency.

Source Download URL

The source code for this recipe is in the Android Cookbook repository, in the subdirectory ContentProviderSample (see “Getting and Using the Code Examples”).

Problem

You have a person’s contact information that you want to save for use by the Contacts application and other apps on your device.

Solution

Set up a list of operations for batch insert, and tell the persistence manager to run it.

Discussion

The Contacts database is, to be sure, “flexible.” It has to adapt to many different kinds of accounts and contact management uses, with different types of data. And it is, as a result, somewhat complicated.

We’ll start with the simplest case of adding a person’s contact information. We want to insert the following information, which we either got from the user or found on the network someplace:

First we have to determine which Android account to associate the data with. For now we will use a fake account name (darwinian is both an adjective and my name, so we’ll use that).

For each of the four fields, we’ll need to create an account operation.

We add all five operations to a List, and pass that into getContentResolver().applyBatch().

Example 10-21 shows the code for the addContact() method.

private void addContact() {
    final String ACCOUNT_NAME = "darwinian"
    String name = "Jon Smith";
    String homePhone = "416-555-5555";
    String workPhone = "416-555-6666";
    String email = "[email protected]";

    // Use new-style Contacts batch operations.
    // Build List of ops, then call applyBatch().
    try {
        ArrayList<ContentProviderOperation> ops =
           new ArrayList<ContentProviderOperation>();
        AuthenticatorDescription[] types = accountManager.getAuthenticatorTypes();
        ops.add(ContentProviderOperation.newInsert(
            ContactsContract.RawContacts.CONTENT_URI).withValue(
                ContactsContract.RawContacts.ACCOUNT_TYPE, types[0].type)
                  .withValue(ContactsContract.RawContacts.ACCOUNT_NAME, ACCOUNT_NAME)
                .build());
        ops.add(ContentProviderOperation
            .newInsert(ContactsContract.Data.CONTENT_URI)
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)
            .withValue(ContactsContract.Data.MIMETYPE,
                ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE)
                .withValue
                  (ContactsContract.CommonDataKinds.StructuredName.DISPLAY_NAME,name)
                .build());
        ops.add(ContentProviderOperation.newInsert(
            ContactsContract.Data.CONTENT_URI).withValueBackReference(
                ContactsContract.Data.RAW_CONTACT_ID, 0).withValue(
                    ContactsContract.Data.MIMETYPE,
                      ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE)
                        .withValue(ContactsContract.CommonDataKinds.Phone.NUMBER,
                        homePhone).withValue(
                                ContactsContract.CommonDataKinds.Phone.TYPE,
                                ContactsContract.CommonDataKinds.Phone.TYPE_HOME)
                .build());
        ops.add(ContentProviderOperation.newInsert(
            ContactsContract.Data.CONTENT_URI).withValueBackReference(
                ContactsContract.Data.RAW_CONTACT_ID, 0).withValue(
                    ContactsContract.Data.MIMETYPE,
                        ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE)
                        .withValue(ContactsContract.CommonDataKinds.Phone.NUMBER,
                            workPhone).withValue(
                                    ContactsContract.CommonDataKinds.Phone.TYPE,
                                    ContactsContract.CommonDataKinds.Phone.TYPE_WORK)
                    .build());
        ops.add(ContentProviderOperation.newInsert(
            ContactsContract.Data.CONTENT_URI).withValueBackReference(
                ContactsContract.Data.RAW_CONTACT_ID, 0).withValue(
                    ContactsContract.Data.MIMETYPE,
                        ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE)
                       .withValue(ContactsContract.CommonDataKinds.Email.DATA,email)
                       .withValue(ContactsContract.CommonDataKinds.Email.TYPE,
                              ContactsContract.CommonDataKinds.Email.TYPE_HOME)
                    .build());

        getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops);

        Toast.makeText(this, getString(R.string.addContactSuccess),
            Toast.LENGTH_LONG).show();
    } catch (Exception e) {

        Toast.makeText(this, getString(R.string.addContactFailure),
            Toast.LENGTH_LONG).show();
        Log.e(LOG_TAG, getString(R.string.addContactFailure), e);
    }
}

The resultant contact shows up in the Contacts app, as shown in Figure 10-8. If the new contact is not initially visible, go to the main Contacts list page, press Menu, select Display Options, and select Groups until it does appear. Alternatively, you can search in All Contacts and it will show up.

Source Download URL

The source code for this project is in the Android Cookbook repository, in the subdirectory AddContact (see “Getting and Using the Code Examples”).

Figure 10-8. Contact added

Problem

You need to extract details, such as a phone number or email address, from the Contacts database.

Solution

Use an Intent to let the user pick one contact. Use a ContentResolver to create a SQLite query for the chosen contact, and use SQLite and predefined constants in the confusingly named ContactsContract class to retrieve the parts you want. Be aware that the Contacts database was designed for generality, not for simplicity.

Discussion

The code in Example 10-22 is from TabbyText, my SMS/text message sender for tablets. The user has already picked the given contact (using the Contactz app; see Recipe 10.14). Here we want to extract the mobile number and save it in a text field in the current Activity, so the user can post-edit it if need be, or even reject it, before actually sending the message, so we just set the text in an EditText once we find it.

Finding it turns out to be the hard part. We start with a query that we get from the ContentProvider, to extract the ID field for the given contact. Information such as phone numbers and email addresses are in their own tables, so we need a second query to feed in the ID as part of the “select” part of the query. This query gives a list of the contact’s phone numbers. We iterate through this, taking each valid phone number and setting it on the EditText.

A further elaboration would restrict this to only selecting the mobile number (some versions of Contacts allow both home and work numbers, but only one mobile number).

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
  if (requestCode == REQ_GET_CONTACT) {
      switch(resultCode) {
      case Activity.RESULT_OK:
          // The Contacts API is about the most complex to use.
          // First we have to retrieve the Contact, since
          // we only get its URI from the Intent.
          Uri resultUri = data.getData(); // E.g., content://contacts/people/123
          Cursor cont =
              getContentResolver().query(resultUri, null, null, null, null);
          if (!cont.moveToNext()) {    // Expect 001 row(s)
              Toast.makeText(this,
                  "Cursor contains no data", Toast.LENGTH_LONG).show();
              return;
          }
          int columnIndexForId =
                cont.getColumnIndex(ContactsContract.Contacts._ID);
          String contactId =
                cont.getString(columnIndexForId);
          int columnIndexForHasPhone =
                cont.getColumnIndex(ContactsContract.Contacts.HAS_PHONE_NUMBER);
          boolean hasAnyPhone =
                Boolean.parseBoolean(cont.getString(columnIndexForHasPhone));
          if (!hasAnyPhone) {
              Toast.makeText(this,
                  "Selected contact seems to have no phone numbers ",
                  Toast.LENGTH_LONG).show();
          }

          // Now we have to do another query to actually get the numbers!
          Cursor numbers = getContentResolver().query(
                    ContactsContract.CommonDataKinds.Phone.CONTENT_URI,
                    null,
                    ContactsContract.CommonDataKinds.Phone.CONTACT_ID +
                    "=" + contactId, // "selection",
                    null, null);
          // Could further restrict to mobile number...
          while (numbers.moveToNext()) {
              String aNumber = numbers.getString(numbers.getColumnIndex(
                  ContactsContract.CommonDataKinds.Phone.NUMBER));
              System.out.println(aNumber);
              number.setText(aNumber);
          }
          if (cont.moveToNext()) {
              System.out.println(
                  "WARNING: More than 1 contact returned by picker!");
          }
          numbers.close();
          cont.close();
          break;
      case Activity.RESULT_CANCELED:
          // Nothing to do here
          break;
      default:
          Toast.makeText(this, "Unexpected resultCode: " + resultCode,
              Toast.LENGTH_LONG).show();
          break;
      }
  }
  super.onActivityResult(requestCode, resultCode, data);
}

Source Download URL

You can download the source code for this example from GitHub.

Problem

You want to implement drag-and-drop, similar to what the Home screen/launcher does when you long-press on an application icon.

Solution

Use the drag and drop API, supported since Android 3.0 and even in the appcompat library. Register a drag listener on the drop target. Start the drag in response to a UI event in the drag source.

Discussion

The normal use of drag-and-drop is to request a change, such as uninstalling an application, removing an item from a list, and so on. The normal operation of a drag is to communicate some user-chosen data from one View to another; i.e, both the source of the drag and the target of the drop must be View objects. To pass information from the source View (e.g., the list item from where you start the drag) to the drop target, there is a special wrapper object called a ClipData. The ClipData can either hold an Android URI representing the object to be dropped, or some arbitrary data. The URI will usually be passed to a ContentProvider for processing.

The basic steps in a drag and drop are:

1. Implement an OnDragListener; its only method is onDrag(), in which you should be prepared for the various action events such as ACTION_DRAG_STARTED, ACTION_DRAG_ENTERED, ACTION_DRAG_EXITED, ACTION_DROP, and ACTION_DRAG_ENDED.

2. Register this listener on the drop target, using the View’s setOnDragListener() method.

3. In a listener attached to the source View, usually in an onItemLongClick() or similar method, start the drag.

4. For ACTION_DRAG_STARTED and/or ACTION_DRAG_ENTERED on the drop target, highlight the View to direct the user’s attention to it as a target, by changing the background color, the image, or similar.

5. For ACTION_DROP, in the drop target, perform the action.

6. For ACTION_DRAG_EXITED and/or ACTION_DRAG_ENDED, do any cleanup required (e.g., undo changes made in the ACTION_DRAG_STARTED and/or ACTION_DRAG_ENTERED case).

In this example (Figure 10-9) we implement a very simple drag-and-drop scenario: a URL is passed from a button to a text field. You start the drag by long-pressing on the button at the top, and drag it down to the text view at the bottom. As soon as you start the drag, the drop target’s background changes to yellow, and the “drag shadow” (by default, an image of the source View object) appears to indicate the drag position. At this point, if you release the drag shadow outside the drop target, the drag shadow will find its way back to the drag source, and the drag will end (the target turns white again). On the other hand, if you drag into the drop target, its color changes to red. If you release the drag shadow here, it is considered a successful drop, and the listener is called with an action code of ACTION_DROP; you should perform the corresponding action (our example just displays the Uri in a toast to prove that it arrived).

Figure 10-9. Drag and drop sequence

Example 10-23 shows the code in onCreate() to start the drag in response to a long-press on the top button.

// Register the long-click listener to START the drag
Button b = (Button) findViewById(R.id.button);
b.setOnLongClickListener(new View.OnLongClickListener() {

    @Override
    public boolean onLongClick(View v) {
        Uri contentUri = Uri.parse("http://oracle.com/java/");
        ClipData cd = ClipData.newUri(getContentResolver(), "Dragging", contentUri);
        v.startDrag(cd, new DragShadowBuilder(v), null, 0);
        return true;
    }
});

This version passes a Uri through the ClipData. To pass arbitrary information, you can use another factory method such as:

ClipData.newPlainText(String label, String data)

Then you need to register your OnDragListener with the target View:

target = findViewById(R.id.drop_target);
target.setOnDragListener(new MyDrag());

The code for our OnDragListener is shown in Example 10-24.

public class MyDrag implements View.OnDragListener {
    @Override
    public boolean onDrag(View v, DragEvent e) {
        switch (e.getAction()) {
        case DragEvent.ACTION_DRAG_STARTED:
            target.setBackgroundColor(COLOR_TARGET_DRAGGING);
            return true;
        case DragEvent.ACTION_DRAG_ENTERED:
            Log.d(TAG, "onDrag: ENTERED e=" + e);
            target.setBackgroundColor(COLOR_TARGET_ALERT);
            return true;
        case DragEvent.ACTION_DRAG_LOCATION:
            // Nothing to do but MUST consume the event
            return true;
        case DragEvent.ACTION_DROP:
            Log.d(TAG, "onDrag: DROP e=" + e);
            final ClipData clipItem = e.getClipData();
            Toast.makeText(DragDropActivity.this,
                "DROPPED: " + clipItem.getItemAt(0).getUri(),
                Toast.LENGTH_LONG).show();
            return true;
        case DragEvent.ACTION_DRAG_EXITED:
            target.setBackgroundColor(COLOR_TARGET_NORMAL);
            return true;
        case DragEvent.ACTION_DRAG_ENDED:
            target.setBackgroundColor(COLOR_TARGET_NORMAL);
            return true;
        default:            // Unhandled event type
            return false;
        }
    }
}

In the ACTION_DROP case, you would usually pass the Uri to a ContentResolver; for example:

getContentResolver().delete(event.getClipData().getItemAt(0).getUri());

Problem

You want to share internal-storage files (see Recipe 10.1) with another app, without the bother of putting the data into a Cursor and creating a ContentProvider.

Solution

The FileProvider class allows you to make files available to another application, usually in response to an Intent. It is simpler to set up than a ContentProvider (Recipe 10.15), but is actually a subclass of ContentProvider.

Discussion

This example exposes a secrets.txt file from one application to another. For this example I have created an Android Studio project called FileProviderDemo, which contains two different applications in two different packages, providerapp and requestingapp. We’ll start by discussing the Provider app since it contains the actual FileProvider. However, you have to run the Requester application first, as it will start the Provider app. Figure 10-10 shows the sequence of the Requester app, then the Provider app, and finally the Requester app with its request satisfied.

Figure 10-10. FileProviderDemo in action: request, confirmation, completion

Unlike the ContentProvider case, you rarely have to write code for the provider itself; instead, use the FileProvider class directly as a provider in your AndroidManifest.xml file, as shown in Example 10-25.

<provider
    android:name="android.support.v4.content.FileProvider"
    android:authorities="com.darwinsys.fileprovider"
    android:grantUriPermissions="true"
    android:exported="false">
    <meta-data
        android:name="android.support.FILE_PROVIDER_PATHS"
        android:resource="@xml/filepaths" />
</provider>

The provider does not have to be exported for this usage, but must have the ability to grant Uri permissions as shown. The meta-data element gives the name of a simple mapping file, which is required to map “virtual paths” to actual paths, as shown in Example 10-26.

<paths>
    <files-path path="secrets/" name="shared_secrets"/>
</paths>

Finally, there has to be an Activity to provide the Uri to the requested file. In our example this is the ProvidingActivity, shown in Example 10-27.

/**
 * The backend app, part of FileProviderDemo.
 * There is only one file provided; in a real app there would
 * probably be a file chooser UI or other means of selecting a file.
 */
public class ProvidingActivity extends AppCompatActivity {

    private File mRequestFile;
    private Intent mResultIntent;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        mResultIntent = new Intent("com.darwinsys.fileprovider.ACTION_RETURN_FILE");
        setContentView(R.layout.activity_providing);
        Toolbar toolbar = (Toolbar) findViewById(R.id.toolbar);
        setSupportActionBar(toolbar);

        // The Layout provides a text field with text like
        // "If you agree to provide the file, press the Agree button"

        Button button = (Button) findViewById(R.id.button);
        button.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View view) {
                provideFile();
            }
        });

        mRequestFile = new File(getFilesDir(), "secrets/demo.txt");

        // On first run of application, create the "hidden" file in internal storage
        if (!mRequestFile.exists()) {
            mRequestFile.getParentFile().mkdirs();
            try (PrintWriter pout = new PrintWriter(mRequestFile)) {
                pout.println("This is the revealed text");
                pout.println("And then some.");
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
    }

    /**
     * The provider application has to return a Uri wrapped in an Intent,
     * along with permission to read that file.
     */
    private void provideFile() {

        // The approved target is one hardcoded file in our directory
        mRequestFile = new File(getFilesDir(), "secrets/demo.txt");
        Uri fileUri = FileProvider.getUriForFile(this,
                "com.darwinsys.fileprovider",
                mRequestFile);

        // The requester is in a different app so can't normally read our files!
        mResultIntent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION);

        mResultIntent.setDataAndType(fileUri, getContentResolver().getType(fileUri));

        // Attach that to the result Intent
        mResultIntent.setData(fileUri);

        // Set the result to be "success" + the result
        setResult(Activity.RESULT_OK, mResultIntent);
        finish();
    }
}

The important part of this code is in the provideFile() method, which:

• Creates a Uri for the actual file (in this trivial example there is only one file, with a hardcoded filename)

• Adds flags to the result Intent to let the receiving app read this one file (only) with our permissions

• Sets the MIME type of the result

• Adds the file Uri as data to the result Intent

• Sets the result Intent, and the “success” flags Activity.RESULT_OK, as the result of this Activity

• Calls finish() to end the Activity

Note that this Activity is not meant to be invoked by the user directly, so it does not have LAUNCHER in its AndroidManifest entry. Thus when you “run” it, you will get an error message, “Could not identify launch activity: Default Activity not found.” This error is normal and expected. If it bothers you, build the application and install it, but don’t try to run it. Or, you could add a dummy Activity with a trivial message onscreen.

Remember that the point of the FileProvider is to share files from one application to another, running with different user permissions. Our second application also has only one Activity, the “requesting” Activity. Most of this is pretty standard boilerplate code. In onCreate(), we create the requesting Intent:

    mRequestFileIntent = new Intent(Intent.ACTION_PICK);
    mRequestFileIntent.setType("text/plain");

The main part of the UI is a text area, which initially suggests that you request a file by pressing the button. That button’s action listener is only one line:

    startActivityForResult(mRequestFileIntent, ACTION_GET_FILE);

This will, as discussed in Recipe 4.5, result in a subsequent call to onActivityComplete(), which is shown in Example 10-28.

public class RequestingActivity extends AppCompatActivity {

    private static final int ACTION_GET_FILE = 1;
    private Intent mRequestFileIntent;

    ...

    @Override
    protected void onActivityResult(int requestCode,
    int resultCode, Intent resultIntent) {
        if (requestCode == ACTION_GET_FILE) {
            if (resultCode == Activity.RESULT_OK) {
                try {
                    // get the file
                    Uri returnUri = resultIntent.getData();
                    final InputStream is =
                        getContentResolver().openInputStream(returnUri);
                    final BufferedReader br =
                        new BufferedReader(new InputStreamReader(is));
                    String line;
                    TextView fileViewTextArea =
                        (TextView) findViewById(R.id.fileView);
                    fileViewTextArea.setText(""); // reset each time
                    while ((line = br.readLine()) != null) {
                        fileViewTextArea.append(line);
                        fileViewTextArea.append("
");
                    }
                } catch (IOException e) {
                    Toast.makeText(this, "IO Error: " + e, Toast.LENGTH_LONG).show();
                }
            } else {
                Toast.makeText(this,
                    "Request denied or canceled", Toast.LENGTH_LONG).show();
            }
            return;
        }
        // For any other Activity, we can do nothing...
        super.onActivityResult(requestCode, resultCode, resultIntent);
    }
}

Assuming that the request succeeds, you will get called here with requestCode set to the only valid action, RESULT_OK, and the resultIntent being the one that the providing Activity set as the Activity result—that is, the Intent wrapping the Uri that we need in order to read the file! So we just get the Uri from the Intent and open that as an input stream, and we can read the “secret” file from the providing application’s otherwise-private internal storage. Just to show that we got it, we display the “secret” file in a text area, shown in the righthand screenshot in Figure 10-10.

See Also

The official documentation on sharing files.

Problem

You want your SQLite or ContentProvider data to be bidirectionally synchronized with a database running on a server.

Solution

Use a SyncAdapter, which lets you synchronize in both directions, providing the infrastructure to run a “merge” algorithm of your own devising.

Discussion

Assuming that you have decided to go the SyncAdapter route, you will first need to make some design decisions:

• How will you access the remote service? (A REST API, as in Recipe 12.1? Volley, as in Recipe 12.2? Custom socket code?)

• How will you package the remote service code? (ContentProvider, as in Recipe 10.15? DAO? Other?)

• What algorithm will you use for ensuring that all the objects are kept up-to-date on the server and on one (or more!) mobile devices? (Don’t forget to handle inserts, updates, and deletions originating from either end!)

Then you need to prepare (design and code) the following:

1. A ContentProvider (see Recipe 10.15. You’ll need this even if you aren’t using one to access your on-device data, but if you already have one, you can certainly use it.

2. An AuthenticatorService, which is boilerplate code, to start the Authenticator.

3. An Authenticator class, since you must have an on-device “account” to allow the system to control syncing.

4. A SyncAdapterService, which is boilerplate code, to start the SyncAdapter.

5. And finally, the actual SyncAdapter, which can probably subclass AbstractThreadedSyncAdapter.

The following code snippets are taken from my working todo list manager, TodoMore, which exists as an Android app, a JavaServer Faces (JSF) web application, a JAX-RS REST service used by the Android app, and possibly others. Each is its own GitHub module, so you can git clone just the parts you need.

In your main Activity’s onCreate() method you need to tell the system that you want to be synchronized. This consists mainly of creating an Account (the first time; after that, finding it) and requesting synchronization using this Account. You can start this in your main Activity’s onCreate() method by calling two helper methods shown in Example 10-29. Note that accountType is just a unique string, such as "MyTodoAccount".

public void onCreate(Bundle savedInstanceState) {
    // ...
    mAccount = createSyncAccount(this);
    enableSynching(mPrefs.getBoolean(KEY_ENABLE_SYNC, true));
}

Account createSyncAccount(Context context) {
    AccountManager accountManager =
            (AccountManager) context.getSystemService(ACCOUNT_SERVICE);
    Account[] accounts = accountManager.getAccountsByType(
            getString(R.string.accountType));    // Our account type
    if (accounts.length == 0) {                    // Haven't created one?
        // Create the account type and default account
        Account newAccount =
                new Account(ACCOUNT, getString(R.string.accountType));
        /*
         * Add the account and account type; no password or user data yet.
         * If successful, return the Account object; else report an error.
         */
        if (accountManager.addAccountExplicitly(
                newAccount, "top secret", null)) {
            Log.d(TAG, "Add Account Explicitly: Success!");
            return newAccount;
        } else {
            throw new IllegalStateException("Add Account failed...");
        }
    } else {                    // Or we already created one, so use it
        return accounts[0];
    }
}

void enableSynching(boolean enable) {
    String authority = getString(R.string.datasync_provider_authority);
    if (enable) {
        ContentResolver.setSyncAutomatically(mAccount, authority, true);

        // Force immediate syncing at startup - optional feature
        Bundle immedExtras = new Bundle();
        immedExtras.putBoolean("SYNC_EXTRAS_MANUAL", true);
        ContentResolver.requestSync(mAccount, authority, immedExtras);

        Bundle extras = new Bundle();
        long pollFrequency = SYNC_INTERVAL_IN_MINUTES;
        ContentResolver.addPeriodicSync(
                mAccount, authority, extras, pollFrequency);
    } else {
        // Disabling, so cancel all outstanding syncs until further notice
        ContentResolver.cancelSync(mAccount, authority);
    }
}