ContentProviderClient.java revision a7771df3696954f0e279407e8894a916a7cb26cc 
1/*
2 * Copyright (C) 2009 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.content;
18
19import android.database.Cursor;
20import android.net.Uri;
21import android.os.Bundle;
22import android.os.CancellationSignal;
23import android.os.ICancellationSignal;
24import android.os.RemoteException;
25import android.os.ParcelFileDescriptor;
26import android.content.res.AssetFileDescriptor;
27
28import java.io.FileNotFoundException;
29import java.util.ArrayList;
30
31/**
32 * The public interface object used to interact with a {@link ContentProvider}. This is obtained by
33 * calling {@link ContentResolver#acquireContentProviderClient}. This object must be released
34 * using {@link #release} in order to indicate to the system that the {@link ContentProvider} is
35 * no longer needed and can be killed to free up resources.
36 */
37public class ContentProviderClient {
38    private final IContentProvider mContentProvider;
39    private final ContentResolver mContentResolver;
40
41    /**
42     * @hide
43     */
44    ContentProviderClient(ContentResolver contentResolver, IContentProvider contentProvider) {
45        mContentProvider = contentProvider;
46        mContentResolver = contentResolver;
47    }
48
49    /** See {@link ContentProvider#query ContentProvider.query} */
50    public Cursor query(Uri url, String[] projection, String selection,
51            String[] selectionArgs, String sortOrder) throws RemoteException {
52        return query(url, projection, selection,  selectionArgs, sortOrder, null);
53    }
54
55    /** See {@link ContentProvider#query ContentProvider.query} */
56    public Cursor query(Uri url, String[] projection, String selection,
57            String[] selectionArgs, String sortOrder, CancellationSignal cancellationSignal)
58                    throws RemoteException {
59        ICancellationSignal remoteCancellationSignal = null;
60        if (cancellationSignal != null) {
61            remoteCancellationSignal = mContentProvider.createCancellationSignal();
62            cancellationSignal.setRemote(remoteCancellationSignal);
63        }
64        return mContentProvider.query(url, projection, selection,  selectionArgs, sortOrder,
65                remoteCancellationSignal);
66    }
67
68    /** See {@link ContentProvider#getType ContentProvider.getType} */
69    public String getType(Uri url) throws RemoteException {
70        return mContentProvider.getType(url);
71    }
72
73    /** See {@link ContentProvider#getStreamTypes ContentProvider.getStreamTypes} */
74    public String[] getStreamTypes(Uri url, String mimeTypeFilter) throws RemoteException {
75        return mContentProvider.getStreamTypes(url, mimeTypeFilter);
76    }
77
78    /** See {@link ContentProvider#insert ContentProvider.insert} */
79    public Uri insert(Uri url, ContentValues initialValues)
80            throws RemoteException {
81        return mContentProvider.insert(url, initialValues);
82    }
83
84    /** See {@link ContentProvider#bulkInsert ContentProvider.bulkInsert} */
85    public int bulkInsert(Uri url, ContentValues[] initialValues) throws RemoteException {
86        return mContentProvider.bulkInsert(url, initialValues);
87    }
88
89    /** See {@link ContentProvider#delete ContentProvider.delete} */
90    public int delete(Uri url, String selection, String[] selectionArgs)
91            throws RemoteException {
92        return mContentProvider.delete(url, selection, selectionArgs);
93    }
94
95    /** See {@link ContentProvider#update ContentProvider.update} */
96    public int update(Uri url, ContentValues values, String selection,
97            String[] selectionArgs) throws RemoteException {
98        return mContentProvider.update(url, values, selection, selectionArgs);
99    }
100
101    /**
102     * See {@link ContentProvider#openFile ContentProvider.openFile}.  Note that
103     * this <em>does not</em>
104     * take care of non-content: URIs such as file:.  It is strongly recommended
105     * you use the {@link ContentResolver#openFileDescriptor
106     * ContentResolver.openFileDescriptor} API instead.
107     */
108    public ParcelFileDescriptor openFile(Uri url, String mode)
109            throws RemoteException, FileNotFoundException {
110        return mContentProvider.openFile(url, mode);
111    }
112
113    /**
114     * See {@link ContentProvider#openAssetFile ContentProvider.openAssetFile}.
115     * Note that this <em>does not</em>
116     * take care of non-content: URIs such as file:.  It is strongly recommended
117     * you use the {@link ContentResolver#openAssetFileDescriptor
118     * ContentResolver.openAssetFileDescriptor} API instead.
119     */
120    public AssetFileDescriptor openAssetFile(Uri url, String mode)
121            throws RemoteException, FileNotFoundException {
122        return mContentProvider.openAssetFile(url, mode);
123    }
124
125    /** See {@link ContentProvider#openTypedAssetFile ContentProvider.openTypedAssetFile} */
126    public final AssetFileDescriptor openTypedAssetFileDescriptor(Uri uri,
127            String mimeType, Bundle opts)
128            throws RemoteException, FileNotFoundException {
129        return mContentProvider.openTypedAssetFile(uri, mimeType, opts);
130    }
131
132    /** See {@link ContentProvider#applyBatch ContentProvider.applyBatch} */
133    public ContentProviderResult[] applyBatch(ArrayList<ContentProviderOperation> operations)
134            throws RemoteException, OperationApplicationException {
135        return mContentProvider.applyBatch(operations);
136    }
137
138    /**
139     * Call this to indicate to the system that the associated {@link ContentProvider} is no
140     * longer needed by this {@link ContentProviderClient}.
141     * @return true if this was release, false if it was already released
142     */
143    public boolean release() {
144        return mContentResolver.releaseProvider(mContentProvider);
145    }
146
147    /**
148     * Get a reference to the {@link ContentProvider} that is associated with this
149     * client. If the {@link ContentProvider} is running in a different process then
150     * null will be returned. This can be used if you know you are running in the same
151     * process as a provider, and want to get direct access to its implementation details.
152     *
153     * @return If the associated {@link ContentProvider} is local, returns it.
154     * Otherwise returns null.
155     */
156    public ContentProvider getLocalContentProvider() {
157        return ContentProvider.coerceToLocalContentProvider(mContentProvider);
158    }
159}
160