Reference/android/content/ContentProvider
From Android中文网
public abstract class
android.content.ContentProvider
- java.lang.Object
- android.content.ContentProvider
Content providers是Andorid应用的重要构建模块，它提供应用间共享所需要的数据。Content Providers数据封装后，通过ContentResolver接口给应用进行访问。只有在应用间共享数据时，Content provider才是需要的。例如，联系人信息可能被很多应用引用，这时，有必要将数据保存在Content Provider中。如果不需要在应用间共享数据，你可直接将通过SQLiteDatabase保持在数据库中。
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.
可以查看此处获取更多关于Content Provider的信息。
See this page for more information on content providers.
通过ContentResolver发起数据请求，系统检查请求的URI所属的提供者，并将该请求转发到注册了此URI的Content Provider进行处理。此Content Provider可以采用任何方式解析此URI。ContentURIParser类提供了一组URI解析的有用接口。
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 ContentURIParser class is helpful for parsing URIs.
Content Provider首先需要实现如下接口：
- query(ContentURI, String[], String, String[], String, String, String) 返回实际数据给调用者
- insert(ContentURI, ContentValues) 向Content Provider插入数据
- update(ContentURI, ContentValues, String, String[]) 更新已有数据
- delete(ContentURI, String, String[]) 从Content Provider中删除数据
- getType(ContentURI) 返回此Content Provider所包含数据的MIME类型
The primary methods that need to be implemented are:
- query(ContentURI, String[], String, String[], String, String, String) which returns data to the caller
- insert(ContentURI, ContentValues) which inserts new data into the content provider
- update(ContentURI, ContentValues, String, String[]) which updates existing data in the content provider
- delete(ContentURI, String, String[]) which deletes data from the content provider
- getType(ContentURI) 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 | DatabaseContentProvider A specialization of the ContentProvider that centralizes functionality used by ContentProviders that use the database, including controlling access to the database via the use of database transactions and java locks. |
[编辑] Summary
[编辑] Public Constructors
ContentProvider()
[编辑] Public Methods
void attachInfo(Context context, ContentProviderInfo info)
After being instantiated, this is called to tell the content provider about itself.
int bulkInsert(ContentURI uri, ContentValues[] values)
Implement this to insert a set of new rows, or the default implementation will iterate over the values and call insert(ContentURI, ContentValues) on each of them. abstract int delete(ContentURI 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.
ContentProvider getTemporaryInstance()
Get a non-persistent instance of this content provider. abstract String getType(ContentURI 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 ContentURI insert(ContentURI 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. abstract boolean onCreate() Called when the provider is being started.
void onSyncCancelled()
Invoked when the active sync has been canceled.
void onSyncStart(SyncContext context)
Called right before a sync is started.
void onSyncStop(SyncContext context, boolean success)
Called right after a sync is completed abstract Cursor query(ContentURI uri, String[] projection, String selection, String[] selectionArgs, String groupBy, String having, String sortOrder) Receives a query request from a client in a local process, and returns a Cursor.
void setContainsDiffs(boolean containsDiffs)
abstract int update(ContentURI 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 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, ContentProviderInfo 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(ContentURI uri, ContentValues[] values)
Implement this to insert a set of new rows, or the default implementation will iterate over the values and call insert(ContentURI, 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(ContentURI 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 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 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(ContentURI 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.
[编辑] public final String getWritePermission()
Return the name of the permission required for read/write access to this content provider. public abstract ContentURI insert(ContentURI 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 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)
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 abstract Cursor query(ContentURI uri, String[] projection, String selection, String[] selectionArgs, String groupBy, String having, 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:
// QueryBuilder is a helper class that creates the
// proper SQL syntax for us.
QueryBuilder qBuilder = new QueryBuilder();
// 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.
- groupBy This parameter will be removed shortly, please ignore it.
- having This parameter will be removed shortly, please ignore it.
- 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(ContentURI 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 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.
