ContentProviderClient


public class ContentProviderClient
extends Object implements AutoCloseable

java.lang.Object
   ↳ android.content.ContentProviderClient


The public interface object used to interact with a specific ContentProvider.

Instances can be obtained by calling ContentResolver#acquireContentProviderClient or ContentResolver#acquireUnstableContentProviderClient. Instances must be released using close() in order to indicate to the system that the underlying ContentProvider is no longer needed and can be killed to free up resources.

Note that you should generally create a new ContentProviderClient instance for each thread that will be performing operations. Unlike ContentResolver, the methods here such as query(Uri, String, Bundle, CancellationSignal) and openFile(Uri, String) are not thread safe -- you must not call close() on the ContentProviderClient those calls are made from until you are finished with the data they have returned.

Summary

Public methods

ContentProviderResult[] applyBatch(ArrayList<ContentProviderOperation> operations)

See ContentProvider.applyBatch

ContentProviderResult[] applyBatch(String authority, ArrayList<ContentProviderOperation> operations)

See ContentProvider.applyBatch

int bulkInsert(Uri url, ContentValues[] initialValues)

See ContentProvider.bulkInsert

Bundle call(String authority, String method, String arg, Bundle extras)

See ContentProvider#call(String, String, Bundle)

Bundle call(String method, String arg, Bundle extras)

See ContentProvider#call(String, String, Bundle)

final Uri canonicalize(Uri url)

See ContentProvider#canonicalize

void close()

Closes this client connection, indicating to the system that the underlying ContentProvider is no longer needed.

int delete(Uri url, String selection, String[] selectionArgs)

See ContentProvider.delete

int delete(Uri url, Bundle extras)

See ContentProvider.delete

ContentProvider getLocalContentProvider()

Get a reference to the ContentProvider that is associated with this client.

String[] getStreamTypes(Uri url, String mimeTypeFilter)

See ContentProvider.getStreamTypes

String getType(Uri url)

See ContentProvider.getType

Uri insert(Uri url, ContentValues initialValues, Bundle extras)

See ContentProvider.insert

Uri insert(Uri url, ContentValues initialValues)

See ContentProvider.insert

AssetFileDescriptor openAssetFile(Uri url, String mode, CancellationSignal signal)

See ContentProvider.openAssetFile.

AssetFileDescriptor openAssetFile(Uri url, String mode)

See ContentProvider.openAssetFile.

ParcelFileDescriptor openFile(Uri url, String mode, CancellationSignal signal)

See ContentProvider.openFile.

ParcelFileDescriptor openFile(Uri url, String mode)

See ContentProvider.openFile.

final AssetFileDescriptor openTypedAssetFile(Uri uri, String mimeTypeFilter, Bundle opts, CancellationSignal signal)

final AssetFileDescriptor openTypedAssetFileDescriptor(Uri uri, String mimeType, Bundle opts, CancellationSignal signal)

See ContentProvider.openTypedAssetFile

final AssetFileDescriptor openTypedAssetFileDescriptor(Uri uri, String mimeType, Bundle opts)

See ContentProvider.openTypedAssetFile

Cursor query(Uri uri, String[] projection, Bundle queryArgs, CancellationSignal cancellationSignal)

See ContentProvider.query

Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder, CancellationSignal cancellationSignal)

See ContentProvider.query

Cursor query(Uri url, String[] projection, String selection, String[] selectionArgs, String sortOrder)

See ContentProvider.query

boolean refresh(Uri url, Bundle extras, CancellationSignal cancellationSignal)

See ContentProvider#refresh

boolean release()

This method was deprecated in API level 24. replaced by close().

final Uri uncanonicalize(Uri url)

See ContentProvider#uncanonicalize

int update(Uri url, ContentValues values, Bundle extras)

See ContentProvider.update

int update(Uri url, ContentValues values, String selection, String[] selectionArgs)

See ContentProvider.update

Protected methods

void finalize()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

Inherited methods

Public methods

applyBatch

Added in API level 5
public ContentProviderResult[] applyBatch (ArrayList<ContentProviderOperation> operations)

See ContentProvider.applyBatch

Parameters
operations ArrayList: This value cannot be null.

Returns
ContentProviderResult[] This value cannot be null.

Throws
OperationApplicationException
RemoteException

applyBatch

Added in API level 29
public ContentProviderResult[] applyBatch (String authority, 
                ArrayList<ContentProviderOperation> operations)

See ContentProvider.applyBatch

Parameters
authority String: This value cannot be null.

operations ArrayList: This value cannot be null.

Returns
ContentProviderResult[] This value cannot be null.

Throws
OperationApplicationException
RemoteException

bulkInsert

Added in API level 5
public int bulkInsert (Uri url, 
                ContentValues[] initialValues)

See ContentProvider.bulkInsert

Parameters
url Uri: This value cannot be null.

initialValues ContentValues: This value cannot be null.

Returns
int

Throws
RemoteException

call

Added in API level 29
public Bundle call (String authority, 
                String method, 
                String arg, 
                Bundle extras)

See ContentProvider#call(String, String, Bundle)

Parameters
authority String: This value cannot be null.

method String: This value cannot be null.

arg String: This value may be null.

extras Bundle: This value may be null.

Returns
Bundle This value may be null.

Throws
RemoteException

call

Added in API level 17
public Bundle call (String method, 
                String arg, 
                Bundle extras)

See ContentProvider#call(String, String, Bundle)

Parameters
method String: This value cannot be null.

arg String: This value may be null.

extras Bundle: This value may be null.

Returns
Bundle This value may be null.

Throws
RemoteException

canonicalize

Added in API level 19
public final Uri canonicalize (Uri url)

See ContentProvider#canonicalize

Parameters
url Uri: This value cannot be null.

Returns
Uri This value may be null.

Throws
RemoteException

close

Added in API level 24
public void close ()

Closes this client connection, indicating to the system that the underlying ContentProvider is no longer needed.

delete

Added in API level 5
public int delete (Uri url, 
                String selection, 
                String[] selectionArgs)

See ContentProvider.delete

Parameters
url Uri: This value cannot be null.

selection String: This value may be null.

selectionArgs String: This value may be null.

Returns
int

Throws
RemoteException

delete

Added in API level 30
public int delete (Uri url, 
                Bundle extras)

See ContentProvider.delete

Parameters
url Uri: This value cannot be null.

extras Bundle: This value may be null.

Returns
int

Throws
RemoteException

getLocalContentProvider

Added in API level 5
public ContentProvider getLocalContentProvider ()

Get a reference to the ContentProvider that is associated with this client. If the ContentProvider is running in a different process then null will be returned. 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.

Returns
ContentProvider If the associated ContentProvider is local, returns it. Otherwise returns null.

getStreamTypes

Added in API level 11
public String[] getStreamTypes (Uri url, 
                String mimeTypeFilter)

See ContentProvider.getStreamTypes

Parameters
url Uri: This value cannot be null.

mimeTypeFilter String: This value cannot be null.

Returns
String[] This value may be null.

Throws
RemoteException

getType

Added in API level 5
public String getType (Uri url)

See ContentProvider.getType

Parameters
url Uri: This value cannot be null.

Returns
String This value may be null.

Throws
RemoteException

insert

Added in API level 30
public Uri insert (Uri url, 
                ContentValues initialValues, 
                Bundle extras)

See ContentProvider.insert

Parameters
url Uri: This value cannot be null.

initialValues ContentValues: This value may be null.

extras Bundle: This value may be null.

Returns
Uri This value may be null.

Throws
RemoteException

insert

Added in API level 5
public Uri insert (Uri url, 
                ContentValues initialValues)

See ContentProvider.insert

Parameters
url Uri: This value cannot be null.

initialValues ContentValues: This value may be null.

Returns
Uri This value may be null.

Throws
RemoteException

openAssetFile

Added in API level 19
public AssetFileDescriptor openAssetFile (Uri url, 
                String mode, 
                CancellationSignal signal)

See ContentProvider.openAssetFile. Note that this does not take care of non-content: URIs such as file:. It is strongly recommended you use the ContentResolver.openAssetFileDescriptor API instead.

Parameters
url Uri: This value cannot be null.

mode String: This value cannot be null.

signal CancellationSignal: This value may be null.

Returns
AssetFileDescriptor This value may be null.

Throws
FileNotFoundException
RemoteException

openAssetFile

Added in API level 5
public AssetFileDescriptor openAssetFile (Uri url, 
                String mode)

See ContentProvider.openAssetFile. Note that this does not take care of non-content: URIs such as file:. It is strongly recommended you use the ContentResolver.openAssetFileDescriptor API instead.

Parameters
url Uri: This value cannot be null.

mode String: This value cannot be null.

Returns
AssetFileDescriptor This value may be null.

Throws
FileNotFoundException
RemoteException

openFile

Added in API level 19
public ParcelFileDescriptor openFile (Uri url, 
                String mode, 
                CancellationSignal signal)

See ContentProvider.openFile. Note that this does not take care of non-content: URIs such as file:. It is strongly recommended you use the ContentResolver.openFileDescriptor API instead.

Parameters
url Uri: This value cannot be null.

mode String: This value cannot be null.

signal CancellationSignal: This value may be null.

Returns
ParcelFileDescriptor This value may be null.

Throws
FileNotFoundException
RemoteException

openFile

Added in API level 5
public ParcelFileDescriptor openFile (Uri url, 
                String mode)

See ContentProvider.openFile. Note that this does not take care of non-content: URIs such as file:. It is strongly recommended you use the ContentResolver.openFileDescriptor API instead.

Parameters
url Uri: This value cannot be null.

mode String: This value cannot be null.

Returns
ParcelFileDescriptor This value may be null.

Throws
FileNotFoundException
RemoteException

openTypedAssetFile

Added in API level 29
public final AssetFileDescriptor openTypedAssetFile (Uri uri, 
                String mimeTypeFilter, 
                Bundle opts, 
                CancellationSignal signal)

Parameters
uri Uri: This value cannot be null.

mimeTypeFilter String: This value cannot be null.

opts Bundle: This value may be null.

signal CancellationSignal: This value may be null.

Returns
AssetFileDescriptor This value may be null.

Throws
FileNotFoundException
RemoteException

openTypedAssetFileDescriptor

Added in API level 19
public final AssetFileDescriptor openTypedAssetFileDescriptor (Uri uri, 
                String mimeType, 
                Bundle opts, 
                CancellationSignal signal)

See ContentProvider.openTypedAssetFile

Parameters
uri Uri: This value cannot be null.

mimeType String: This value cannot be null.

opts Bundle: This value may be null.

signal CancellationSignal: This value may be null.

Returns
AssetFileDescriptor This value may be null.

Throws
FileNotFoundException
RemoteException

openTypedAssetFileDescriptor

Added in API level 11
public final AssetFileDescriptor openTypedAssetFileDescriptor (Uri uri, 
                String mimeType, 
                Bundle opts)

See ContentProvider.openTypedAssetFile

Parameters
uri Uri: This value cannot be null.

mimeType String: This value cannot be null.

opts Bundle: This value may be null.

Returns
AssetFileDescriptor This value may be null.

Throws
FileNotFoundException
RemoteException

query

Added in API level 26
public Cursor query (Uri uri, 
                String[] projection, 
                Bundle queryArgs, 
                CancellationSignal cancellationSignal)

See ContentProvider.query

Parameters
uri Uri: This value cannot be null.

projection String: This value may be null.

queryArgs Bundle

cancellationSignal CancellationSignal: This value may be null.

Returns
Cursor This value may be null.

Throws
RemoteException

query

Added in API level 16
public Cursor query (Uri uri, 
                String[] projection, 
                String selection, 
                String[] selectionArgs, 
                String sortOrder, 
                CancellationSignal cancellationSignal)

See ContentProvider.query

Parameters
uri Uri: This value cannot be null.

projection String: This value may be null.

selection String: This value may be null.

selectionArgs String: This value may be null.

sortOrder String: This value may be null.

cancellationSignal CancellationSignal: This value may be null.

Returns
Cursor This value may be null.

Throws
RemoteException

query

Added in API level 5
public Cursor query (Uri url, 
                String[] projection, 
                String selection, 
                String[] selectionArgs, 
                String sortOrder)

See ContentProvider.query

Parameters
url Uri: This value cannot be null.

projection String: This value may be null.

selection String: This value may be null.

selectionArgs String: This value may be null.

sortOrder String: This value may be null.

Returns
Cursor This value may be null.

Throws
RemoteException

refresh

Added in API level 26
public boolean refresh (Uri url, 
                Bundle extras, 
                CancellationSignal cancellationSignal)

See ContentProvider#refresh

Parameters
url Uri

extras Bundle: This value may be null.

cancellationSignal CancellationSignal: This value may be null.

Returns
boolean

Throws
RemoteException

release

Added in API level 5
Deprecated in API level 24
public boolean release ()

This method was deprecated in API level 24.
replaced by close().

Returns
boolean

uncanonicalize

Added in API level 19
public final Uri uncanonicalize (Uri url)

See ContentProvider#uncanonicalize

Parameters
url Uri: This value cannot be null.

Returns
Uri This value may be null.

Throws
RemoteException

update

Added in API level 30
public int update (Uri url, 
                ContentValues values, 
                Bundle extras)

See ContentProvider.update

Parameters
url Uri: This value cannot be null.

values ContentValues: This value may be null.

extras Bundle: This value may be null.

Returns
int

Throws
RemoteException

update

Added in API level 5
public int update (Uri url, 
                ContentValues values, 
                String selection, 
                String[] selectionArgs)

See ContentProvider.update

Parameters
url Uri: This value cannot be null.

values ContentValues: This value may be null.

selection String: This value may be null.

selectionArgs String: This value may be null.

Returns
int

Throws
RemoteException

Protected methods

finalize

Added in API level 5
protected void finalize ()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the Java virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

Throws
Throwable