1/* 2 * Copyright (C) 2013 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.support.v4.content; 18 19import static android.os.Build.VERSION.SDK_INT; 20 21import android.content.ContentResolver; 22import android.database.Cursor; 23import android.net.Uri; 24import android.support.v4.os.CancellationSignal; 25import android.support.v4.os.OperationCanceledException; 26 27/** 28 * Helper for accessing features in {@link android.content.ContentResolver} in a backwards 29 * compatible fashion. 30 */ 31public final class ContentResolverCompat { 32 private ContentResolverCompat() { 33 /* Hide constructor */ 34 } 35 36 /** 37 * Query the given URI, returning a {@link Cursor} over the result set 38 * with optional support for cancellation. 39 * <p> 40 * For best performance, the caller should follow these guidelines: 41 * <ul> 42 * <li>Provide an explicit projection, to prevent 43 * reading data from storage that aren't going to be used.</li> 44 * <li>Use question mark parameter markers such as 'phone=?' instead of 45 * explicit values in the {@code selection} parameter, so that queries 46 * that differ only by those values will be recognized as the same 47 * for caching purposes.</li> 48 * </ul> 49 * </p> 50 * 51 * @param uri The URI, using the content:// scheme, for the content to 52 * retrieve. 53 * @param projection A list of which columns to return. Passing null will 54 * return all columns, which is inefficient. 55 * @param selection A filter declaring which rows to return, formatted as an 56 * SQL WHERE clause (excluding the WHERE itself). Passing null will 57 * return all rows for the given URI. 58 * @param selectionArgs You may include ?s in selection, which will be 59 * replaced by the values from selectionArgs, in the order that they 60 * appear in the selection. The values will be bound as Strings. 61 * @param sortOrder How to order the rows, formatted as an SQL ORDER BY 62 * clause (excluding the ORDER BY itself). Passing null will use the 63 * default sort order, which may be unordered. 64 * @param cancellationSignal A signal to cancel the operation in progress, or null if none. 65 * If the operation is canceled, then {@link OperationCanceledException} will be thrown 66 * when the query is executed. 67 * @return A Cursor object, which is positioned before the first entry, or null 68 * @see Cursor 69 */ 70 public static Cursor query(ContentResolver resolver, 71 Uri uri, String[] projection, String selection, String[] selectionArgs, 72 String sortOrder, CancellationSignal cancellationSignal) { 73 if (SDK_INT >= 16) { 74 try { 75 final android.os.CancellationSignal cancellationSignalObj = 76 (android.os.CancellationSignal) 77 (cancellationSignal != null 78 ? cancellationSignal.getCancellationSignalObject() 79 : null); 80 return resolver.query(uri, projection, selection, selectionArgs, sortOrder, 81 cancellationSignalObj); 82 } catch (Exception e) { 83 if (e instanceof android.os.OperationCanceledException) { 84 // query() can throw a framework OperationCanceledException if it has been 85 // canceled. We catch that and throw the support version instead. 86 throw new OperationCanceledException(); 87 } else { 88 // If it's not a framework OperationCanceledException, re-throw the exception 89 throw e; 90 } 91 } 92 } else { 93 // Note that the cancellation signal cannot cancel the query in progress 94 // prior to Jellybean so we cancel it preemptively here if needed. 95 if (cancellationSignal != null) { 96 cancellationSignal.throwIfCanceled(); 97 } 98 return resolver.query(uri, projection, selection, selectionArgs, sortOrder); 99 } 100 } 101} 102