android.content
Class ContentProvider

java.lang.Object
  android.content.ContentProvider

All Implemented Interfaces:

ComponentCallbacks

Direct Known Subclasses:

CheckinProvider, SearchRecentSuggestionsProvider, SyncableContentProvider, SyncProvider, SyncStateContentProviderHelper.Provider

public abstract class ContentProvider
extends Object
implements ComponentCallbacks

Content providers are one of the primary building blocks of Android applications, providing content to applications. They encapsulate data and provide it to applications through the single ContentResolver interface. A content provider is only required if you need to share data between multiple applications. For example, the contacts data is used by multiple applications and must be stored in a content provider. If you don't need to share data amongst multiple applications you can use a database directly via SQLiteDatabase.

See this page for more information on content providers.

When a request is made via a ContentResolver the system inspects the authority of the given URI and passes the request to the content provider registered with the authority. The content provider can interpret the rest of the URI however it wants. The UriMatcher class is helpful for parsing URIs.

The primary methods that need to be implemented are:

• query(android.net.Uri, java.lang.String[], java.lang.String, java.lang.String[], java.lang.String) which returns data to the caller
• insert(android.net.Uri, android.content.ContentValues) which inserts new data into the content provider
• update(android.net.Uri, android.content.ContentValues, java.lang.String, java.lang.String[]) which updates existing data in the content provider
• delete(android.net.Uri, java.lang.String, java.lang.String[]) which deletes data from the content provider
• getType(android.net.Uri) which returns the MIME type of data in the content provider

This class takes care of cross process calls so subclasses don't have to worry about which process a request is coming from.

Nested Class Summary

(package private) class

ContentProvider.Transport Binder object that deals with remoting.

Constructor Summary

ContentProvider()

Method Summary

void	attachInfo(Context context, ProviderInfo info) After being instantiated, this is called to tell the content provider about itself.
int	bulkInsert(Uri uri, ContentValues[] values) Implement this to insert a set of new rows, or the default implementation will iterate over the values and call insert(android.net.Uri, android.content.ContentValues) on each of them.
static ContentProvider	coerceToLocalContentProvider(IContentProvider abstractInterface) Given an IContentProvider, try to coerce it back to the real ContentProvider object if it is running in the local process.
abstract int	delete(Uri uri, String selection, String[] selectionArgs) A request to delete one or more rows.
Context	getContext() Retrieve the Context this provider is running in.
IContentProvider	getIContentProvider() Returns the Binder object for this provider.
String	getReadPermission() Return the name of the permission required for read-only access to this content provider.
SyncAdapter	getSyncAdapter() Get the sync adapter that is to be used by this content provider.
abstract String	getType(Uri uri) Return the MIME type of the data at the given URI.
String	getWritePermission() Return the name of the permission required for read/write access to this content provider.
abstract Uri	insert(Uri uri, ContentValues values) Implement this to insert a new row.
protected boolean	isTemporary() Returns true if this instance is a temporary content provider.
void	onConfigurationChanged(Configuration newConfig) Called by the system when the device configuration changes while your component is running.
abstract boolean	onCreate() Called when the provider is being started.
void	onLowMemory() This is called when the overall system is running low on memory, and would like actively running process to try to tighten their belt.
ParcelFileDescriptor	openFile(Uri uri, String mode) Open a file blob associated with a content URI.
protected ParcelFileDescriptor	openFileHelper(Uri uri, String mode) Convenience for subclasses that wish to implement openFile(android.net.Uri, java.lang.String) by looking up a column named "_data" at the given URI.
abstract Cursor	query(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder) Receives a query request from a client in a local process, and returns a Cursor.
protected void	setReadPermission(String permission) Change the permission required to read data from the content provider.
protected void	setWritePermission(String permission) Change the permission required to read and write data in the content provider.
abstract int	update(Uri uri, ContentValues values, String selection, String[] selectionArgs) Update a content URI.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ContentProvider

public ContentProvider()

Method Detail

coerceToLocalContentProvider

public static ContentProvider coerceToLocalContentProvider(IContentProvider abstractInterface)

Given an IContentProvider, try to coerce it back to the real ContentProvider object if it is running in the local process. This can be used if you know you are running in the same process as a provider, and want to get direct access to its implementation details. Most clients should not nor have a reason to use it.

Parameters:

abstractInterface - The ContentProvider interface that is to be coerced.

Returns:

If the IContentProvider is non-null and local, returns its actual ContentProvider instance. Otherwise returns null.

getContext

public final Context getContext()

Retrieve the Context this provider is running in. Only available once onCreate(Map icicle) has been called -- this will be null in the constructor.

setReadPermission

protected final void setReadPermission(String permission)

Change the permission required to read data from the content provider. This is normally set for you from its manifest information when the provider is first created.

Parameters:

permission - Name of the permission required for read-only access.

getReadPermission

public final String getReadPermission()

Return the name of the permission required for read-only access to this content provider. This method can be called from multiple threads, as described in the Threading section of the Application Model overview.

setWritePermission

protected final void setWritePermission(String permission)

Change the permission required to read and write data in the content provider. This is normally set for you from its manifest information when the provider is first created.

Parameters:

permission - Name of the permission required for read/write access.

getWritePermission

public final String getWritePermission()

Return the name of the permission required for read/write access to this content provider. This method can be called from multiple threads, as described in the Threading section of the Application Model overview.

onCreate

public abstract boolean onCreate()

Called when the provider is being started.

Returns:

true if the provider was successfully loaded, false otherwise

onConfigurationChanged

public void onConfigurationChanged(Configuration newConfig)

Description copied from interface: ComponentCallbacks

Called by the system when the device configuration changes while your component is running. Note that, unlike activities, other components are never restarted when a configuration changes: they must always deal with the results of the change, such as by re-retrieving resources.

At the time that this function has been called, your Resources object will have been updated to return resource values matching the new configuration.

Specified by:

onConfigurationChanged in interface ComponentCallbacks

Parameters:

newConfig - The new device configuration.

onLowMemory

public void onLowMemory()

Description copied from interface: ComponentCallbacks

This is called when the overall system is running low on memory, and would like actively running process to try to tighten their belt. While the exact point at which this will be called is not defined, generally it will happen around the time all background process have been killed, that is before reaching the point of killing processes hosting service and foreground UI that we would like to avoid killing.

Applications that want to be nice can implement this method to release any caches or other unnecessary resources they may be holding on to. The system will perform a gc for you after returning from this method.

Specified by:

onLowMemory in interface ComponentCallbacks

query

public abstract Cursor query(Uri uri,
                             String[] projection,
                             String selection,
                             String[] selectionArgs,
                             String sortOrder)

Receives a query request from a client in a local process, and returns a Cursor. This is called internally by the ContentResolver. This method can be called from multiple threads, as described in the Threading section of the Application Model overview.

Example client call:

// Request a specific record.
 Cursor managedCursor = managedQuery(
                Contacts.People.CONTENT_URI.addId(2),
                projection,    // Which columns to return.
                null,          // WHERE clause.
                People.NAME + " ASC");   // Sort order.

Example implementation:

// SQLiteQueryBuilder is a helper class that creates the
        // proper SQL syntax for us.
        SQLiteQueryBuilder qBuilder = new SQLiteQueryBuilder();

        // Set the table we're querying.
        qBuilder.setTables(DATABASE_TABLE_NAME);

        // If the query ends in a specific record number, we're
        // being asked for a specific record, so set the
        // WHERE clause in our query.
        if((URI_MATCHER.match(uri)) == SPECIFIC_MESSAGE){
            qBuilder.appendWhere("_id=" + uri.getPathLeafId());
        }

        // Make the query.
        Cursor c = qBuilder.query(mDb,
                projection,
                selection,
                selectionArgs,
                groupBy,
                having,
                sortOrder);
        c.setNotificationUri(getContext().getContentResolver(), uri);
        return c;

Parameters:

uri - The URI to query. This will be the full URI sent by the client; if the client is requesting a specific record, the URI will end in a record number that the implementation should parse and add to a WHERE or HAVING clause, specifying that _id value.

projection - The list of columns to put into the cursor. If null all columns are included.

selection - A selection criteria to apply when filtering rows. If null then all rows are included.

sortOrder - How the rows in the cursor should be sorted. If null then the provider is free to define the sort order.

Returns:

a Cursor or null.

getType

public abstract String getType(Uri uri)

Return the MIME type of the data at the given URI. This should start with vnd.android.cursor.item for a single record, or vnd.android.cursor.dir/ for multiple items. This method can be called from multiple threads, as described in the Threading section of the Application Model overview.

Parameters:

uri - the URI to query.

Returns:

a MIME type string, or null if there is no type.

insert

public abstract Uri insert(Uri uri,
                           ContentValues values)

Implement this to insert a new row. As a courtesy, call notifyChange() after inserting. This method can be called from multiple threads, as described in the Threading section of the Application Model overview.

Parameters:

uri - The content:// URI of the insertion request.

values - A set of column_name/value pairs to add to the database.

Returns:

The URI for the newly inserted item.

bulkInsert

public int bulkInsert(Uri uri,
                      ContentValues[] values)

Implement this to insert a set of new rows, or the default implementation will iterate over the values and call insert(android.net.Uri, android.content.ContentValues) on each of them. As a courtesy, call notifyChange() after inserting. This method can be called from multiple threads, as described in the Threading section of the Application Model overview.

Parameters:

uri - The content:// URI of the insertion request.

values - An array of sets of column_name/value pairs to add to the database.

Returns:

The number of values that were inserted.

delete

public abstract int delete(Uri uri,
                           String selection,
                           String[] selectionArgs)

A request to delete one or more rows. The selection clause is applied when performing the deletion, allowing the operation to affect multiple rows in a directory. As a courtesy, call notifyDelete() after deleting. This method can be called from multiple threads, as described in the Threading section of the Application Model overview.

The implementation is responsible for parsing out a row ID at the end of the URI, if a specific row is being deleted. That is, the client would pass in content://contacts/people/22 and the implementation is responsible for parsing the record number (22) when creating a SQL statement.

Parameters:

uri - The full URI to query, including a row ID (if a specific record is requested).

selection - An optional restriction to apply to rows when deleting.

Returns:

The number of rows affected.

Throws:

SQLException

update

public abstract int update(Uri uri,
                           ContentValues values,
                           String selection,
                           String[] selectionArgs)

Update a content URI. All rows matching the optionally provided selection will have their columns listed as the keys in the values map with the values of those keys. As a courtesy, call notifyChange() after updating. This method can be called from multiple threads, as described in the Threading section of the Application Model overview.

Parameters:

uri - The URI to query. This can potentially have a record ID if this is an update request for a specific record.

values - A Bundle mapping from column names to new column values (NULL is a valid value).

selection - An optional filter to match rows to update.

Returns:

the number of rows affected.

openFile

public ParcelFileDescriptor openFile(Uri uri,
                                     String mode)
                              throws FileNotFoundException

Open a file blob associated with a content URI. This method can be called from multiple threads, as described in the Threading section of the Application Model overview.

Returns a ParcelFileDescriptor, from which you can obtain a FileDescriptor for use with FileInputStream, FileOutputStream, etc. This can be used to store large data (such as an image) associated with a particular piece of content.

The returned ParcelFileDescriptor is owned by the caller, so it is their responsibility to close it when done. That is, the implementation of this method should create a new ParcelFileDescriptor for each call.

Parameters:

uri - The URI whose file is to be opened.

mode - Access mode for the file. May be "r" for read-only access or "rw" for read and write access.

Returns:

Returns a new ParcelFileDescriptor which you can use to access the file.

Throws:

FileNotFoundException - Throws FileNotFoundException if there is no file associated with the given URI or the mode is invalid.

SecurityException - Throws SecurityException if the caller does not have permission to access the file.

openFileHelper

protected final ParcelFileDescriptor openFileHelper(Uri uri,
                                                    String mode)
                                             throws FileNotFoundException

Convenience for subclasses that wish to implement openFile(android.net.Uri, java.lang.String) by looking up a column named "_data" at the given URI.

Parameters:

uri - The URI to be opened.

mode - The file mode.

Returns:

Returns a new ParcelFileDescriptor that can be used by the client to access the file.

Throws:

FileNotFoundException

getSyncAdapter

public SyncAdapter getSyncAdapter()

Get the sync adapter that is to be used by this content provider. This is intended for use by the sync system. If null then this content provider is considered not syncable. This method can be called from multiple threads, as described in the Threading section of the Application Model overview.

Returns:

the SyncAdapter that is to be used by this ContentProvider, or null if this ContentProvider is not syncable

isTemporary

protected boolean isTemporary()

Returns true if this instance is a temporary content provider.

Returns:

true if this instance is a temporary content provider

getIContentProvider

public IContentProvider getIContentProvider()

Returns the Binder object for this provider.

Returns:

the Binder object for this provider

attachInfo

public void attachInfo(Context context,
                       ProviderInfo info)

After being instantiated, this is called to tell the content provider about itself.

Parameters:

context - The context this provider is running in

info - Registered information about this content provider