android.content
public
abstract
class
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
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
SearchRecentSuggestionsProvider |
This superclass can be used to create a simple search suggestions provider for your application. |
SyncProvider |
ContentProvider that tracks the sync data and overall sync
history on the device. |
SyncableContentProvider |
A specialization of the ContentProvider that centralizes functionality
used by ContentProviders that are syncable. |
Summary
Public Constructors
Public Methods
|
|
|
|
|
void |
attachInfo(Context context, ProviderInfo info) |
|
|
|
|
|
int |
bulkInsert(Uri uri, ContentValues[] values) |
abstract |
|
|
|
|
int |
delete(Uri uri, String selection, String[] selectionArgs) |
|
|
final |
|
|
Context |
getContext() |
|
|
final |
|
|
String |
getReadPermission() |
|
|
|
|
|
SyncAdapter |
getSyncAdapter() |
abstract |
|
|
|
|
String |
getType(Uri uri) |
|
|
final |
|
|
String |
getWritePermission() |
abstract |
|
|
|
|
Uri |
insert(Uri uri, ContentValues values) |
|
|
|
|
|
void |
onConfigurationChanged(Configuration newConfig) |
abstract |
|
|
|
|
boolean |
onCreate() |
|
|
|
|
|
void |
onLowMemory() |
|
|
|
|
|
ParcelFileDescriptor |
openFile(Uri uri, String mode) |
abstract |
|
|
|
|
Cursor |
query(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder) |
abstract |
|
|
|
|
int |
update(Uri uri, ContentValues values, String selection, String[] selectionArgs) |
Protected Methods
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
Details
Public Constructors
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
|
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 the
Threading section of
the Application Model overview.
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 number of values that were inserted.
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.
This method can be called from multiple
threads, as described in the
Threading section of the
Application Model overview.
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.
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()
public
SyncAdapter
getSyncAdapter()
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 the
Threading section of
the Application Model overview.
Returns
- the SyncAdapter that is to be used by this ContentProvider, or null
if this ContentProvider is not syncable
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.
This method can be called from multiple
threads, as described in the
Threading section of
the Application Model overview.
Returns
- a MIME type string, or null if there is no type.
public
final
String
getWritePermission()
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 the
Threading section of the
Application Model overview.
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
void
onConfigurationChanged(Configuration newConfig)
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.
public
abstract
boolean
onCreate()
Called when the provider is being started.
Returns
- true if the provider was successfully loaded, false otherwise
public
void
onLowMemory()
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.
Open a file blob associated with a content URI.
This method can be called from multiple
threads, as described in the
Threading section of the
Application Model overview.
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.
This method can be called from multiple
threads, as described in the
Threading section of
the Application Model overview.
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. |
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.
This method can be called from multiple
threads, as described in the
Threading section of the
Application Model overview.
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
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.
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.
|