Android - An Open Handset Alliance Project

android.content
public abstract class

android.content.ContentProvider

java.lang.Object
	android.content.ContentProvider

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(Uri, String[], String, String[], String) which returns data to the caller
insert(Uri, ContentValues) which inserts new data into the content provider
update(Uri, ContentValues, String, String[]) which updates existing data in the content provider
delete(Uri, String, String[]) which deletes data from the content provider
getType(Uri) which returns the MIME type of data in the content provider

Content providers may be syncable to external data sources, and if they are they must additionally implement the methods required for sync and make sure to return true from isSyncable(). By default providers are not syncable and you don't have to worry about the sync related methods.

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

Known Direct Subclasses

DatabaseContentProvider

Summary

Public Constructors

ContentProvider()

Public Methods

		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(Uri, ContentValues) on each of them.
abstract		int	delete(Uri uri, String selection, String[] selectionArgs)
			A request to delete one or more rows.
		boolean	getContainsDiffs()
	final	Context	getContext()
			Retrieve the Context this provider is running in.
	final	String	getReadPermission()
			Return the name of the permission required for read-only access to this content provider.
		SyncAdapter	getSyncAdapter(Context context)
			Get the sync adapter that is to be used by this content provider.
		String	getSyncingAccount()
			The account of the most recent call to onSyncStart()
		ContentProvider	getTemporaryInstance()
			Get a non-persistent instance of this content provider.
abstract		String	getType(Uri uri)
			Return the MIME type of the data at the given URI.
	final	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.
		boolean	isSyncable()
			Returns true if this content provider supports syncing.
		MergeResult	merge(SyncContext context, ContentProvider diffs, boolean readOnly)
			Merge diffs from a sync source with this content provider.
		void	onConfigurationChanged(Configuration newConfig)
			Called by the system when the device configuration changes while your provider is running.
abstract		boolean	onCreate()
			Called when the provider is being started.
		void	onSyncCancelled()
			Invoked when the active sync has been canceled.
		void	onSyncStart(SyncContext context, String account)
			Called right before a sync is started.
		void	onSyncStop(SyncContext context, boolean success)
			Called right after a sync is completed
		ParcelFileDescriptor	openFile(Uri uri, String mode)
			Open a file blob associated with a content 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.
		void	setContainsDiffs(boolean containsDiffs)
abstract		int	update(Uri uri, ContentValues values, String selection, String[] selectionArgs)
			Update a content URI.

Protected Methods

	boolean	isTemporary()
		Returns true if this instance is a temporary content provider.
final	ParcelFileDescriptor	openFileHelper(Uri uri, String mode)
		Convenience for subclasses that wish to implement openFile(Uri, String) by looking up a column named "_data" at the given URI.
final	void	setReadPermission(String permission)
		Change the permission required to read data from the content provider.
final	void	setWritePermission(String permission)
		Change the permission required to read and write data in the content provider.

Methods inherited from class java.lang.Object

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

	Object	clone()
		Answers a new instance of the same class as the receiver, whose slots have been filled in with the values in the slots of the receiver.
	boolean	equals(Object o)
		Compares the argument to the receiver, and answers true if they represent the same object using a class specific comparison.
	void	finalize()
		Called by the virtual machine when there are no longer any (non-weak) references to the receiver.
final	Class	getClass()
		Answers the unique instance of java.lang.Class which represents the class of the receiver.
	int	hashCode()
		Answers an integer hash code for the receiver.
final	void	notify()
		Causes one thread which is `wait` ing on the receiver to be made ready to run.
final	void	notifyAll()
		Causes all threads which are `wait` ing on the receiver to be made ready to run.
	String	toString()
		Answers a string containing a concise, human-readable description of the receiver.
final	void	wait(long time, int frac)
		Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by `notify` or `notifyAll`) or the expiration of the timeout.
final	void	wait(long time)
		Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by `notify` or `notifyAll`) or the expiration of the timeout.
final	void	wait()
		Causes the thread which sent this message to be made not ready to run pending some change in the receiver (as indicated by `notify` or `notifyAll`).

Details

Public Constructors

public ContentProvider()

Public Methods

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

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(Uri, ContentValues) on each of them. As a courtesy, call notifyChange() after inserting.

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 URI for the newly inserted item.

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. 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

public boolean getContainsDiffs()

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.

public final String getReadPermission()

Return the name of the permission required for read-only access to this content provider.

public SyncAdapter getSyncAdapter(Context context)

Get the sync adapter that is to be used by this content provider. This is intended for use by the sync system, and is only required to be implemented if isSyncable() returns true.

Returns

the SyncAdapter that is to be used by this ContentProvider

public String getSyncingAccount()

The account of the most recent call to onSyncStart()

Returns

the account

public ContentProvider getTemporaryInstance()

Get a non-persistent instance of this content provider. This is intended for use by the sync system, and is only required to be implemented if isSyncable() returns true.

Returns

a non-persistent content provider with the same layout as this provider.

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.





    Parameters
    
    
        uri
        the URI to query.
      
    
    






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

uri	the URI to query.





 
    
        public 
         
        final 
         
         
        String
        getWritePermission()
    
    




Return the name of the permission required for read/write access to
 this content provider.




















 
    
        public 
         
         
        abstract 
         
        Uri
        insert(Uri uri, ContentValues values)
    
    




Implement this to insert a new row.
 As a courtesy, call notifyChange()
 after inserting.





    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.















 
    
        public 
         
         
         
         
        boolean
        isSyncable()
    
    




Returns true if this content provider supports syncing.








    Returns
    true if this content provider supports syncing.








    See Also
    
    getTemporaryInstance()
    merge(SyncContext, ContentProvider, boolean)
    
    
    









 
    
        public 
         
         
         
         
        MergeResult
        merge(SyncContext context, ContentProvider diffs, boolean readOnly)
    
    




Merge diffs from a sync source with this content provider. This is
 intended for use by the sync system, and is only required to be
 implemented if isSyncable() returns true and this content provider
 is persistent.





    Parameters
    
    
        context
        the SyncContext within which this merge is taking place
      
    
        diffs
        A temporary content provider containing diffs from a sync
          source.
      
    
        readOnly
        if set then this merge should not return any local
          changes to sync up to the server.
      
    
    






    Returns
    a MergeResult, which contains a temporary content provider
   with the same layout as this provider containing local, unsynced
   changes from this content provider.















 
    
        public 
         
         
         
         
        void
        onConfigurationChanged(Configuration newConfig)
    
    




Called by the system when the device configuration changes while your
 provider is running.  Note that, unlike activities, providers 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.





    Parameters
    
    
        newConfig
        The new device configuration.

      
    
    

















 
    
        public 
         
         
        abstract 
         
        boolean
        onCreate()
    
    




Called when the provider is being started.








    Returns
    true if the provider was successfully loaded, false otherwise















 
    
        public 
         
         
         
         
        void
        onSyncCancelled()
    
    




Invoked when the active sync has been canceled. The default
 implementation doesn't do anything (except ensure that this
 provider is syncable). Subclasses of ContentProvider
 that support canceling of sync should override this.




















 
    
        public 
         
         
         
         
        void
        onSyncStart(SyncContext context, String account)
    
    




Called right before a sync is started.





    Parameters
    
    
        context
        the sync context for the operation
      
    
    

















 
    
        public 
         
         
         
         
        void
        onSyncStop(SyncContext context, boolean success)
    
    




Called right after a sync is completed





    Parameters
    
    
        context
        the sync context for the operation
      
    
        success
        true if the sync succeeded, false if an error occurred

      
    
    

















 
    
        public 
         
         
         
         
        ParcelFileDescriptor
        openFile(Uri uri, String mode)
    
    




Open a file blob associated with a content URI.  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.

        
    
    












 
    
        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.
 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.















 
    
        public 
         
         
         
         
        void
        setContainsDiffs(boolean containsDiffs)
    
    
























 
    
        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.





    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.



















Protected Methods




 
    
        protected 
         
         
         
         
        boolean
        isTemporary()
    
    




Returns true if this instance is a temporary content provider.








    Returns
    true if this instance is a temporary content provider















 
    
        protected 
         
        final 
         
         
        ParcelFileDescriptor
        openFileHelper(Uri uri, String mode)
    
    




Convenience for subclasses that wish to implement openFile(Uri, 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
            
        
    
    












 
    
        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.

      
    
    

















 
    
        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.

uri	The content:// URI of the insertion request.
values	A set of column_name/value pairs to add to the database.

context	the SyncContext within which this merge is taking place
diffs	A temporary content provider containing diffs from a sync source.
readOnly	if set then this merge should not return any local changes to sync up to the server.

context	the sync context for the operation
success	true if the sync succeeded, false if an error occurred

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.

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.

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.

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.


e.g. "intent" or "activity"

Android - An Open Handset Alliance Project

Documentation

Goodies

android.content.ContentProvider

Known Direct Subclasses

Summary

Public Constructors

Public Methods

Protected Methods

Methods inherited from class java.lang.Object

Details

Public Constructors

public ContentProvider()

Public Methods

public void attachInfo(Context context, ProviderInfo info)

Parameters

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

Parameters

Returns

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

Parameters

Returns

Throws

public boolean getContainsDiffs()

public final Context getContext()

public final String getReadPermission()

public SyncAdapter getSyncAdapter(Context context)

Returns

public String getSyncingAccount()

Returns

public ContentProvider getTemporaryInstance()

Returns

public abstract String getType(Uri uri)

Parameters

Returns

public final String getWritePermission()

public abstract Uri insert(Uri uri, ContentValues values)

Parameters

Returns

public boolean isSyncable()

Returns

See Also

public MergeResult merge(SyncContext context, ContentProvider diffs, boolean readOnly)

Parameters

Returns

public void onConfigurationChanged(Configuration newConfig)

Parameters

public abstract boolean onCreate()

Returns

public void onSyncCancelled()

public void onSyncStart(SyncContext context, String account)

Parameters

public void onSyncStop(SyncContext context, boolean success)

Parameters

public ParcelFileDescriptor openFile(Uri uri, String mode)

Parameters

Returns

Throws

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

Parameters

Returns

public void setContainsDiffs(boolean containsDiffs)

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

Parameters

Returns

Protected Methods

protected boolean isTemporary()

Returns

protected final ParcelFileDescriptor openFileHelper(Uri uri, String mode)

Parameters

Returns

Throws

protected final void setReadPermission(String permission)

Parameters

protected final void setWritePermission(String permission)

Parameters