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: *
Data access methods (such as {@link #insert} and * {@link #update}) may be called from many threads at once, and must be thread-safe. * Other methods (such as {@link #onCreate}) are only called from the application * main thread, and must avoid performing lengthy operations. See the method * descriptions for their expected thread behavior.
* *Requests to {@link ContentResolver} are automatically forwarded to the appropriate * ContentProvider instance, so subclasses don't have to worry about the details of * cross-process calls.
*/ public abstract class ContentProvider implements ComponentCallbacks { /* * Note: if you add methods to ContentProvider, you must add similar methods to * MockContentProvider. */ private Context mContext = null; private int mMyUid; private String mReadPermission; private String mWritePermission; private PathPermission[] mPathPermissions; private boolean mExported; private Transport mTransport = new Transport(); /** * Construct a ContentProvider instance. Content providers must be * declared * in the manifest, accessed with {@link ContentResolver}, and created * automatically by the system, so applications usually do not create * ContentProvider instances directly. * *At construction time, the object is uninitialized, and most fields and * methods are unavailable. Subclasses should initialize themselves in * {@link #onCreate}, not the constructor. * *
Content providers are created on the application main thread at
* application launch time. The constructor must not perform lengthy
* operations, or application startup will be delayed.
*/
public ContentProvider() {
}
/**
* Constructor just for mocking.
*
* @param context A Context object which should be some mock instance (like the
* instance of {@link android.test.mock.MockContext}).
* @param readPermission The read permision you want this instance should have in the
* test, which is available via {@link #getReadPermission()}.
* @param writePermission The write permission you want this instance should have
* in the test, which is available via {@link #getWritePermission()}.
* @param pathPermissions The PathPermissions you want this instance should have
* in the test, which is available via {@link #getPathPermissions()}.
* @hide
*/
public ContentProvider(
Context context,
String readPermission,
String writePermission,
PathPermission[] pathPermissions) {
mContext = context;
mReadPermission = readPermission;
mWritePermission = writePermission;
mPathPermissions = pathPermissions;
}
/**
* 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
*/
public static ContentProvider coerceToLocalContentProvider(
IContentProvider abstractInterface) {
if (abstractInterface instanceof Transport) {
return ((Transport)abstractInterface).getContentProvider();
}
return null;
}
/**
* Binder object that deals with remoting.
*
* @hide
*/
class Transport extends ContentProviderNative {
ContentProvider getContentProvider() {
return ContentProvider.this;
}
/**
* Remote version of a query, which returns an IBulkCursor. The bulk
* cursor should be wrapped with BulkCursorToCursorAdaptor before use.
*/
public IBulkCursor bulkQuery(Uri uri, String[] projection,
String selection, String[] selectionArgs, String sortOrder,
IContentObserver observer, CursorWindow window) {
enforceReadPermission(uri);
Cursor cursor = ContentProvider.this.query(uri, projection,
selection, selectionArgs, sortOrder);
if (cursor == null) {
return null;
}
return new CursorToBulkCursorAdaptor(cursor, observer,
ContentProvider.this.getClass().getName(),
hasWritePermission(uri), window);
}
public Cursor query(Uri uri, String[] projection,
String selection, String[] selectionArgs, String sortOrder) {
enforceReadPermission(uri);
return ContentProvider.this.query(uri, projection, selection,
selectionArgs, sortOrder);
}
public String getType(Uri uri) {
return ContentProvider.this.getType(uri);
}
public Uri insert(Uri uri, ContentValues initialValues) {
enforceWritePermission(uri);
return ContentProvider.this.insert(uri, initialValues);
}
public int bulkInsert(Uri uri, ContentValues[] initialValues) {
enforceWritePermission(uri);
return ContentProvider.this.bulkInsert(uri, initialValues);
}
public ContentProviderResult[] applyBatch(ArrayList You should defer nontrivial initialization (such as opening,
* upgrading, and scanning databases) until the content provider is used
* (via {@link #query}, {@link #insert}, etc). Deferred initialization
* keeps application startup fast, avoids unnecessary work if the provider
* turns out not to be needed, and stops database errors (such as a full
* disk) from halting application launch.
*
* If you use SQLite, {@link android.database.sqlite.SQLiteOpenHelper}
* is a helpful utility class that makes it easy to manage databases,
* and will automatically defer opening until first use. If you do use
* SQLiteOpenHelper, make sure to avoid calling
* {@link android.database.sqlite.SQLiteOpenHelper#getReadableDatabase} or
* {@link android.database.sqlite.SQLiteOpenHelper#getWritableDatabase}
* from this method. (Instead, override
* {@link android.database.sqlite.SQLiteOpenHelper#onOpen} to initialize the
* database when it is first opened.)
*
* @return true if the provider was successfully loaded, false otherwise
*/
public abstract boolean onCreate();
/**
* {@inheritDoc}
* This method is always called on the application main thread, and must
* not perform lengthy operations.
*
* The default content provider implementation does nothing.
* Override this method to take appropriate action.
* (Content providers do not usually care about things like screen
* orientation, but may want to know about locale changes.)
*/
public void onConfigurationChanged(Configuration newConfig) {
}
/**
* {@inheritDoc}
* This method is always called on the application main thread, and must
* not perform lengthy operations.
*
* The default content provider implementation does nothing.
* Subclasses may override this method to take appropriate action.
*/
public void onLowMemory() {
}
/**
* Implement this to handle query requests from clients.
* This method can be called from multiple threads, as described in
* Application Fundamentals:
* Processes and Threads.
*
* Example client call:
*
* 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 This method returns a ParcelFileDescriptor, which is returned directly
* to the caller. This way large data (such as images and documents) can be
* returned without copying the 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)
*/
public ParcelFileDescriptor openFile(Uri uri, String mode)
throws FileNotFoundException {
throw new FileNotFoundException("No files supported by provider at "
+ uri);
}
/**
* 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.
* This method can be called from multiple threads, as described in
* Application Fundamentals:
* Processes and Threads.
*
* If you implement this, your clients must be able to deal with such
* file slices, either directly with
* {@link ContentResolver#openAssetFileDescriptor}, or by using the higher-level
* {@link ContentResolver#openInputStream ContentResolver.openInputStream}
* or {@link ContentResolver#openOutputStream ContentResolver.openOutputStream}
* methods.
*
* 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.// Request a specific record.
* Cursor managedCursor = managedQuery(
ContentUris.withAppendedId(Contacts.People.CONTENT_URI, 2),
projection, // Which columns to return.
null, // WHERE clause.
null, // WHERE clause value substitution
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 selectionArgs You may include ?s in selection, which will be replaced by
* the values from selectionArgs, in order that they appear in the selection.
* The values will be bound as Strings.
* @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.
*/
public abstract Cursor query(Uri uri, String[] projection,
String selection, String[] selectionArgs, String sortOrder);
/**
* Implement this to handle requests for the MIME type of the data at the
* given URI. The returned MIME type 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 abstract String getType(Uri uri);
/**
* Implement this to handle requests 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.
*/
public abstract Uri insert(Uri uri, ContentValues values);
/**
* Override this to handle requests 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.
*/
public int bulkInsert(Uri uri, ContentValues[] values) {
int numValues = values.length;
for (int i = 0; i < numValues; i++) {
insert(uri, values[i]);
}
return numValues;
}
/**
* Implement this to handle requests to delete one or more rows.
* The implementation should apply the selection clause when performing
* 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.
*
* 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 abstract int delete(Uri uri, String selection, String[] selectionArgs);
/**
* Implement this to handle requests to update one or more rows.
* The implementation should update all rows matching the selection
* to set the columns according to the provided values map.
* 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.
*/
public abstract int update(Uri uri, ContentValues values, String selection,
String[] selectionArgs);
/**
* Override this to handle requests to open a file blob.
* The default implementation always throws {@link FileNotFoundException}.
* This method can be called from multiple threads, as described in
* Application Fundamentals:
* Processes and Threads.
*
*