FileDocCategorySizeDatePackage
ContentProvider.javaAPI DocAndroid 1.5 API25601Wed May 06 22:41:54 BST 2009android.content

ContentProvider

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 {@link 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 {@link android.database.sqlite.SQLiteDatabase}.

For more information, read Content Providers.

When a request is made via a {@link 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 {@link UriMatcher} class is helpful for parsing URIs.

The primary methods that need to be implemented are:

  • {@link #query} which returns data to the caller
  • {@link #insert} which inserts new data into the content provider
  • {@link #update} which updates existing data in the content provider
  • {@link #delete} which deletes data from the content provider
  • {@link #getType} 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.

Fields Summary
private Context
mContext
private String
mReadPermission
private String
mWritePermission
private Transport
mTransport
Constructors Summary
Methods Summary
public voidattachInfo(Context context, android.content.pm.ProviderInfo info)
After being instantiated, this is called to tell the content provider about itself.

param
context The context this provider is running in
param
info Registered information about this content provider


        /*
         * Only allow it to be set once, so after the content service gives
         * this to us clients can't change it.
         */
        if (mContext == null) {
            mContext = context;
            if (info != null) {
                setReadPermission(info.readPermission);
                setWritePermission(info.writePermission);
            }
            ContentProvider.this.onCreate();
        }
    
public intbulkInsert(android.net.Uri uri, ContentValues[] values)
Implement this to insert a set of new rows, or the default implementation will iterate over the values and call {@link #insert} on each of them. As a courtesy, call {@link ContentResolver#notifyChange(android.net.Uri ,android.database.ContentObserver) notifyChange()} after inserting. This method can be called from multiple threads, as described in Application Fundamentals: Processes and Threads.

param
uri The content:// URI of the insertion request.
param
values An array of sets of column_name/value pairs to add to the database.
return
The number of values that were inserted.

        int numValues = values.length;
        for (int i = 0; i < numValues; i++) {
            insert(uri, values[i]);
        }
        return numValues;
    
public static android.content.ContentProvidercoerceToLocalContentProvider(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.

param
abstractInterface The ContentProvider interface that is to be coerced.
return
If the IContentProvider is non-null and local, returns its actual ContentProvider instance. Otherwise returns null.
hide


                                                                                                               
       
              
        if (abstractInterface instanceof Transport) {
            return ((Transport)abstractInterface).getContentProvider();
        }
        return null;
    
public abstract intdelete(android.net.Uri uri, java.lang.String selection, java.lang.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 {@link ContentResolver#notifyChange(android.net.Uri ,android.database.ContentObserver) notifyDelete()} after deleting. This method can be called from multiple threads, as described in Application Fundamentals: Processes and Threads.

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.

param
uri The full URI to query, including a row ID (if a specific record is requested).
param
selection An optional restriction to apply to rows when deleting.
return
The number of rows affected.
throws
SQLException

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

        return mContext;
    
public IContentProvidergetIContentProvider()
Returns the Binder object for this provider.

return
the Binder object for this provider
hide

        return mTransport;
    
public final java.lang.StringgetReadPermission()
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 Application Fundamentals: Processes and Threads.

        return mReadPermission;
    
public SyncAdaptergetSyncAdapter()
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 Application Fundamentals: Processes and Threads.

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

        return null;
    
public abstract java.lang.StringgetType(android.net.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 Application Fundamentals: Processes and Threads.

param
uri the URI to query.
return
a MIME type string, or null if there is no type.

public final java.lang.StringgetWritePermission()
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 Application Fundamentals: Processes and Threads.

        return mWritePermission;
    
public abstract android.net.Uriinsert(android.net.Uri uri, ContentValues values)
Implement this to insert a new row. As a courtesy, call {@link ContentResolver#notifyChange(android.net.Uri ,android.database.ContentObserver) notifyChange()} after inserting. This method can be called from multiple threads, as described in Application Fundamentals: Processes and Threads.

param
uri The content:// URI of the insertion request.
param
values A set of column_name/value pairs to add to the database.
return
The URI for the newly inserted item.

protected booleanisTemporary()
Returns true if this instance is a temporary content provider.

return
true if this instance is a temporary content provider

        return false;
    
public voidonConfigurationChanged(android.content.res.Configuration newConfig)

    
public abstract booleanonCreate()
Called when the provider is being started.

return
true if the provider was successfully loaded, false otherwise

public voidonLowMemory()

    
public android.content.res.AssetFileDescriptoropenAssetFile(android.net.Uri uri, java.lang.String mode)
This is like {@link #openFile}, but can be implemented by providers that need to be able to return sub-sections of files, often assets inside of their .apk. Note that when implementing this your clients must be able to deal with such files, either directly with {@link ContentResolver#openAssetFileDescriptor ContentResolver.openAssetFileDescriptor}, or by using the higher-level {@link ContentResolver#openInputStream ContentResolver.openInputStream} or {@link ContentResolver#openOutputStream ContentResolver.openOutputStream} methods.

Note: if you are implementing this to return a full file, you should create the AssetFileDescriptor with {@link AssetFileDescriptor#UNKNOWN_LENGTH} to be compatible with applications that can not handle sub-sections of files.

param
uri The URI whose file is to be opened.
param
mode Access mode for the file. May be "r" for read-only access, "w" for write-only access (erasing whatever data is currently in the file), "wa" for write-only access to append to any existing data, "rw" for read and write access on any existing data, and "rwt" for read and write access that truncates any existing file.
return
Returns a new AssetFileDescriptor 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.
throws
SecurityException Throws SecurityException if the caller does not have permission to access the file.
see
#openFile(Uri, String)
see
#openFileHelper(Uri, String)

        ParcelFileDescriptor fd = openFile(uri, mode);
        return fd != null ? new AssetFileDescriptor(fd, 0, -1) : null;
    
public android.os.ParcelFileDescriptoropenFile(android.net.Uri uri, java.lang.String mode)
Open a file blob associated with a content URI. This method can be called from multiple threads, as described in Application Fundamentals: Processes and Threads.

Returns a ParcelFileDescriptor, from which you can obtain a {@link java.io.FileDescriptor} for use with {@link java.io.FileInputStream}, {@link java.io.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.

param
uri The URI whose file is to be opened.
param
mode Access mode for the file. May be "r" for read-only access, "rw" for read and write access, or "rwt" for read and write access that truncates any existing file.
return
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.
throws
SecurityException Throws SecurityException if the caller does not have permission to access the file.
see
#openAssetFile(Uri, String)
see
#openFileHelper(Uri, String)

        throw new FileNotFoundException("No files supported by provider at "
                + uri);
    
protected final android.os.ParcelFileDescriptoropenFileHelper(android.net.Uri uri, java.lang.String mode)
Convenience for subclasses that wish to implement {@link #openFile} by looking up a column named "_data" at the given URI.

param
uri The URI to be opened.
param
mode The file mode. May be "r" for read-only access, "w" for write-only access (erasing whatever data is currently in the file), "wa" for write-only access to append to any existing data, "rw" for read and write access on any existing data, and "rwt" for read and write access that truncates any existing file.
return
Returns a new ParcelFileDescriptor that can be used by the client to access the file.

        Cursor c = query(uri, new String[]{"_data"}, null, null, null);
        int count = (c != null) ? c.getCount() : 0;
        if (count != 1) {
            // If there is not exactly one result, throw an appropriate
            // exception.
            if (c != null) {
                c.close();
            }
            if (count == 0) {
                throw new FileNotFoundException("No entry for " + uri);
            }
            throw new FileNotFoundException("Multiple items at " + uri);
        }

        c.moveToFirst();
        int i = c.getColumnIndex("_data");
        String path = (i >= 0 ? c.getString(i) : null);
        c.close();
        if (path == null) {
            throw new FileNotFoundException("Column _data not found.");
        }

        int modeBits = ContentResolver.modeToMode(uri, mode);
        return ParcelFileDescriptor.open(new File(path), modeBits);
    
public abstract android.database.Cursorquery(android.net.Uri uri, java.lang.String[] projection, java.lang.String selection, java.lang.String[] selectionArgs, java.lang.String sortOrder)
Receives a query request from a client in a local process, and returns a Cursor. This is called internally by the {@link ContentResolver}. This method can be called from multiple threads, as described in Application Fundamentals: Processes and Threads.

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;

param
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.
param
projection The list of columns to put into the cursor. If null all columns are included.
param
selection A selection criteria to apply when filtering rows. If null then all rows are included.
param
sortOrder How the rows in the cursor should be sorted. If null then the provider is free to define the sort order.
return
a Cursor or null.

protected final voidsetReadPermission(java.lang.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.

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

        mReadPermission = permission;
    
protected final voidsetWritePermission(java.lang.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.

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

        mWritePermission = permission;
    
public abstract intupdate(android.net.Uri uri, ContentValues values, java.lang.String selection, java.lang.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 {@link ContentResolver#notifyChange(android.net.Uri ,android.database.ContentObserver) notifyChange()} after updating. This method can be called from multiple threads, as described in Application Fundamentals: Processes and Threads.

param
uri The URI to query. This can potentially have a record ID if this is an update request for a specific record.
param
values A Bundle mapping from column names to new column values (NULL is a valid value).
param
selection An optional filter to match rows to update.
return
the number of rows affected.