java.lang.Object | |
↳ | android.content.ContentProvider |
Known Direct Subclasses |
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
.
For more information, read 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 callerinsert(Uri, ContentValues)
which inserts new data into the content providerupdate(Uri, ContentValues, String, String[])
which updates existing data in the content providerdelete(Uri, String, String[])
which deletes data from the content providergetType(Uri)
which returns the MIME type of data in the content providerThis class takes care of cross process calls so subclasses don't have to worry about which process a request is coming from.
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Applies each of the
ContentProviderOperation objects and returns an array
of their results. | |||||||||||
After being instantiated, this is called to tell the content provider
about itself.
| |||||||||||
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. | |||||||||||
A request to delete one or more rows.
| |||||||||||
Retrieve the Context this provider is running in.
| |||||||||||
Return the path-based permissions required for read and/or write access to
this content provider.
| |||||||||||
Return the name of the permission required for read-only access to
this content provider.
| |||||||||||
Return the MIME type of the data at the given URI.
| |||||||||||
Return the name of the permission required for read/write access to
this content provider.
| |||||||||||
Implement this to insert a new row.
| |||||||||||
Called by the system when the device configuration changes while your
component is running.
| |||||||||||
Called when the provider is being started.
| |||||||||||
This is called when the overall system is running low on memory, and
would like actively running process to try to tighten their belt.
| |||||||||||
This is like
openFile(Uri, String) , but can be implemented by providers
that need to be able to return sub-sections of files, often assets
inside of their .apk. | |||||||||||
Open a file blob associated with a content URI.
| |||||||||||
Receives a query request from a client in a local process, and
returns a Cursor.
| |||||||||||
Update a content URI.
|
Protected Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Returns true if this instance is a temporary content provider.
| |||||||||||
Convenience for subclasses that wish to implement
openFile(Uri, String)
by looking up a column named "_data" at the given URI. | |||||||||||
Change the path-based permission required to read and/or write data in
the content provider.
| |||||||||||
Change the permission required to read data from the content
provider.
| |||||||||||
Change the permission required to read and write data in the content
provider.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class java.lang.Object
| |||||||||||
From interface android.content.ComponentCallbacks
|
Applies each of the ContentProviderOperation
objects and returns an array
of their results. Passes through OperationApplicationException, which may be thrown
by the call to apply(ContentProvider, ContentProviderResult[], int)
.
If all the applications succeed then a ContentProviderResult
array with the
same number of elements as the operations will be returned. It is implementation-specific
how many, if any, operations will have been successfully applied if a call to
apply results in a OperationApplicationException
.
operations | the operations to apply |
---|
OperationApplicationException | thrown if an application fails.
See apply(ContentProvider, ContentProviderResult[], int) for more information.
|
---|
After being instantiated, this is called to tell the content provider about itself.
context | The context this provider is running in |
---|---|
info | Registered information about this content provider |
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.
This method can be called from multiple
threads, as described in
Application Fundamentals:
Processes and Threads.
uri | The content:// URI of the insertion request. |
---|---|
values | An array of sets of column_name/value pairs to add to the database. |
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
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.
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. |
SQLException |
---|
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 the path-based permissions required for read and/or write access to this content provider. This method can be called from multiple threads, as described in Application Fundamentals: Processes and Threads.
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 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.
uri | the URI to query. |
---|
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.
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
Application Fundamentals:
Processes and Threads.
uri | The content:// URI of the insertion request. |
---|---|
values | A set of column_name/value pairs to add to the database. |
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.
newConfig | The new device configuration. |
---|
Called when the provider is being started.
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.
This is like openFile(Uri, String)
, 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
ContentResolver.openAssetFileDescriptor
, or by using the higher-level
ContentResolver.openInputStream
or ContentResolver.openOutputStream
methods.
Note: if you are implementing this to return a full file, you
should create the AssetFileDescriptor with
UNKNOWN_LENGTH
to be compatible with
applications that can not handle sub-sections of files.
uri | The URI whose file is to be opened. |
---|---|
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. |
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. |
Open a file blob associated with a content URI. This method can be called from multiple threads, as described inentity Application Fundamentals: Processes and Threads.
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.
uri | The URI whose file is to be opened. |
---|---|
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. |
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. |
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
Application Fundamentals:
Processes and Threads.
Example client call:
// 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;
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. |
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. |
sortOrder | How the rows in the cursor should be sorted. If null then the provider is free to define the sort order. |
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
Application Fundamentals:
Processes and Threads.
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 true if this instance is a temporary content provider.
Convenience for subclasses that wish to implement openFile(Uri, String)
by looking up a column named "_data" at the given URI.
uri | The URI to be opened. |
---|---|
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. |
FileNotFoundException |
---|
Change the path-based permission required to read and/or write data in the content provider. This is normally set for you from its manifest information when the provider is first created.
permissions | Array of path permission descriptions. |
---|
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.
permission | Name of the permission required for read-only access. |
---|
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.
permission | Name of the permission required for read/write access. |
---|