Content provider

Overview One of the four components of Android Provides an abstraction of data as a set of tables Provides an standard interface for other processes to access its data A client uses ContentResolver to interact with a content provider A client may need to request permission in Manifest for accessing data

General Topics How to interact with a content provider What content providers are available in Android Calendar, Contacts, User Dictionary, etc How to write a content provider

Accessing a Provider - Query Requesting access permission in Manifest <uses-permission android.permission_READ_USER_DICTIONARY /> Getting an instance of ContentResolver Context.getContentResolver(); Querying the provide mCursor = getContentResolver().query( URI, projection, selectionClause, selectionArgs, sortOrder);

Accessing a Provider - Query URI Format: content://authority/path_to_table Ex., content://user_dictionary/words Often the provider offers: UserDictionary.Words.Content_URI constant for URI Projection Columns to be returned as an array Ex., String[] projection = { UserDictionary.Words._ID, UserDictionary.Words.WORD}; selectionClause Selection condition with ? marks for fill-in values Ex., String selectionClause = UserDicitonary.Words.WORD + “=?”; selectionArgs Fill-in values for selectionClause Ex., String[] selectionArg = { “your word”}; sortOrder The order of the query result Ex., String sortOrder = UserDicitonary.Words.WORD + “ ASC”;

Accessing a Provider - Insert Inserting a row to the table Syntax URI newUri = getContentResolver().insert(URI, newContentValues); URI: the content URI of the table. Ex., UserDictionary.Word.Content_URI; newContentValues: column-value pairs of the new record. Ex., ContentValues newValues = new ContentValues(); newValues.put(UserDicitonary.Words.APP_ID, “example.user”); newValues.put(UserDictionary.Words.LOCALE, "en_US"); newValues.put(UserDictionary.Words.WORD, "insert"); newValues.put(UserDictionary.Words.FREQUENCY, "100"); Note The operation returns a the Uri of the newly inserted row Content://user_dictionary/words/<id>

Accessing a Provider - Update Updating rows to the table Syntax int rowsUpdated = getContentResolver().update(URI, updateValues, selectionClause, selectionArgs); URI: the content URI of the table. Ex., UserDictionary.Word.Content_URI; updateValues: column-value pairs of the new record. Ex., ContentValues updateValues = new ContentValues(); updateValues.put(UserDictionary.Words.LOCALE, "en_US"); updateValues.put(UserDictionary.Words.WORD, "insert") selectionCause: condition for row selection, ex., String selectionClause = UserDictionary.Word.LOCALE + “ LIKE ?” selectionArgs: values for selectionClause ? marks. Ex., String[] selectionArgs = {“en_us”); Note The operation returns the number of rows affected by the update

Accessing a Provider - Delete Deleting rows to the table Syntax int rowsUpdated = getContentResolver().delete(URI, selectionClause, selectionArgs); URI: the content URI of the table. Ex., UserDictionary.Word.Content_Uri; selectionCause: condition for row selection, ex., String selectionClause = UserDictionary.Word.LOCALE + “ LIKE ?” selectionArgs: values for selectionClause ? marks. Ex., String[] selectionArgs = {“en_us”); Note The operation returns the number of rows affected by the delete

Processing Query Result Query returns a Cursor If no row returned, mCursor.getCount()==0; If error/exception, mCursor == null; Displaying result in ListView Using SimpleCursorAdapter Define columns to be selected from Cursor String[] mFromColumns = { UserDictionary.Words.WORD, UserDictionary.Words.LOCALE}; Define the view ID’s in the layout String[] mToFields = { R.id.word, R.id.locale}; Create a SimpleCursorAdapter mSimpleCursorAdapter = new SimpleCursorAdapter( getApplicationContext(), R.layout.listview, mCursor, mFromColumns, mToFields, 0}; Set the adapter to the listview mListView.setAdapter(mSimpleCursorAdapter );

Using Loader with Providers Activity/Fragment implements LoaderManager.Callbacks interface In onCreate()/onActivityCreated() Create a SimpleCursorAdapter with a null Cursor Zero (0) as the last parameter of the constructor void onActivityCreated(Bundle data) { super.onActivityCreated(data); mAdapter = new SimpleCursorAdapter(getActivity(), R.layout.my_layout, null, // we don’t have data yet, use null new String[] {Contacts.DISPLAY_NAME}, new int[] {R.id.name}, 0}; // since Loader monitors data changes, use 0 // so the adapter would not monitor the data setListAdapter(mAdapter); // prepare the loader getLoaderManager().initLoader(3, null, this); }

Using Loader with Providers In onCreateLoader() // return a CursorLoader Loader<Cursor> onCreateLoader(int id, Bundle args) { Uri baseUri = UserDictionary.Words.Content_URI; String[] projection = { UserDictionary.Words._ID, UserDictionary.Words.WORD}; String selectionClause = UserDicitonary.Words.WORD + “=?”; String[] selectionArgs = { “your word”}; String sortOrder = UserDicitonary.Words.WORD + “ ASC”; return new CursorLoader(getActivity(), baseUri, projections, selectionClause, selectionArgs, sortOrder); }

Using Loader with Providers In onLoadFinised() and onLoaderReset() void onLoadFinished(Loader<Cursor> loader, Cursor data) { // now we have data, put it into the list view // do not try to close the old cursor, // android takes care of it mAdapter.swapCursor(data); } // if the cursor is about to be closed void onLoaderReset(Loader<Cursor> loader) { // called when the cursor is to be closed. // release the reference to the cursor mAdapter.swapCursor(null);

Android Content Providers Calendar Contacts MediaStore Telephony Settings User Dictionary Voice Mail

Creating a Content Provider When you need a content provider If you want your app to provide data to other apps Steps of building your own provider Design the storage for your data Subclass ContentProvider for CRUD operations Define content URIs Add other optional features

Designing Data Storage Using SQLite database SQLite tables map to provider tables nicely You could use views as provider tables. Using files Photos, audio, and videos Your provider offers a handle to the file Using network-based data Use java.net and android.net Synchronize remote data with local database Then offer local data as tables or files

Designing Data Structures Primary key Each table should have a primary key column. Using BaseColumns._ID makes it easier to integrate with other items such as ListView If you need to provide large pieces of data Store data in files Provide data indirectly through those files Use Binary Large OBject (BLOB) for data in different sizes and structures.

Designing Content URIs Identifies data in a provider Consists of authority, path to the table, and row ID Designing an authority Each provider has a single authority – android-internal name To avoid naming conflicts, use your package name Ex., edu.scranton.mypackagename.provider Designing a path structure Append paths to authority Ex.1, edu.scranton.mypackagename.provider/table1 Ex.2, edu.scranton.mypackagename.provider/table2 Handling content URI ID Each table has a column _ID as primary key Ex.1, edu.scranton.mypackagename.provider/table2/324

Implementing Required Methods query(): Cursor Retrieve data from your provider Returns a Cursor Insert(): Uri Insert a new row to the specified table Returns a content URI for the new row Update():int Update rows with the specified column-value pairs (ContentValues) for rows that satisfy selection clause Returns the number of rows affected Delete():int Delete rows that satisfy the specified selection clause onCreate() Android calls it when it starts up the provider. Initialize your provider. It is not executed until a ContentResolver tries to access the provider getType() Return the MIME type corresponding to the content URI> getSteamType() Optional – implement when your provider offers files.

Implementing Contract Class A public final class that contains definitions of URIs, column names, MIME types, and other meta-data of the provider A contract between the provider and its clients Use JavaDoc to document all the items. ContactsContract class is an example of such classes.

Provider Permissions List of permissions from coarse-grained to fine-grained permissions Fine-grained permissions take precedence over ones with coarse-grained Single read-write provider level permission Separate read and write provider level permission Path-level permissions for individual content URI Temporary permission

<Provider> Elements Authority (android:authority) Names that identify the entire provider Provider class name (android:name) The class that implements ContentProvider Permissions Attributes that specify the permissions andorid:grantUriPermissions: temporary permissions flag Android:permission: single provider-wide permission Android:readPermission: provider-wide read permission Android:writePermission: provider-wide write permission Startup and control attributes Determine how and when android starts the provider, the process characteristics of the provider and run-time settings android:enabled, android:exported, android:initOrder, android:multiProceses, android:syncable. Informational attributes An optional icon and label for the provider