diff options
| -rw-r--r-- | api/current.txt | 18 | ||||
| -rw-r--r-- | api/system-current.txt | 18 | ||||
| -rw-r--r-- | api/test-current.txt | 18 | ||||
| -rw-r--r-- | core/java/android/content/ContentProvider.java | 60 | ||||
| -rw-r--r-- | core/java/android/content/ContentResolver.java | 116 |
5 files changed, 142 insertions, 88 deletions
diff --git a/api/current.txt b/api/current.txt index 66cf2c61b1e4..4b8acb2b13b3 100644 --- a/api/current.txt +++ b/api/current.txt @@ -8737,17 +8737,17 @@ package android.content { field public static final java.lang.String EXTRA_HONORED_ARGS = "android.content.extra.HONORED_ARGS"; field public static final java.lang.String EXTRA_REFRESH_SUPPORTED = "android.content.extra.REFRESH_SUPPORTED"; field public static final java.lang.String EXTRA_SIZE = "android.content.extra.SIZE"; - field public static final java.lang.String EXTRA_TOTAL_SIZE = "android.content.extra.TOTAL_SIZE"; + field public static final java.lang.String EXTRA_TOTAL_COUNT = "android.content.extra.TOTAL_COUNT"; field public static final int NOTIFY_SKIP_NOTIFY_FOR_DESCENDANTS = 2; // 0x2 field public static final int NOTIFY_SYNC_TO_NETWORK = 1; // 0x1 - field public static final java.lang.String QUERY_ARG_LIMIT = "android:query-page-limit"; - field public static final java.lang.String QUERY_ARG_OFFSET = "android:query-page-offset"; - field public static final java.lang.String QUERY_ARG_SORT_COLLATION = "android:query-sort-collation"; - field public static final java.lang.String QUERY_ARG_SORT_COLUMNS = "android:query-sort-columns"; - field public static final java.lang.String QUERY_ARG_SORT_DIRECTION = "android:query-sort-direction"; - field public static final java.lang.String QUERY_ARG_SQL_SELECTION = "android:query-sql-selection"; - field public static final java.lang.String QUERY_ARG_SQL_SELECTION_ARGS = "android:query-sql-selection-args"; - field public static final java.lang.String QUERY_ARG_SQL_SORT_ORDER = "android:query-sql-sort-order"; + field public static final java.lang.String QUERY_ARG_LIMIT = "android:query-arg-limit"; + field public static final java.lang.String QUERY_ARG_OFFSET = "android:query-arg-offset"; + field public static final java.lang.String QUERY_ARG_SORT_COLLATION = "android:query-arg-sort-collation"; + field public static final java.lang.String QUERY_ARG_SORT_COLUMNS = "android:query-arg-sort-columns"; + field public static final java.lang.String QUERY_ARG_SORT_DIRECTION = "android:query-arg-sort-direction"; + field public static final java.lang.String QUERY_ARG_SQL_SELECTION = "android:query-arg-sql-selection"; + field public static final java.lang.String QUERY_ARG_SQL_SELECTION_ARGS = "android:query-arg-sql-selection-args"; + field public static final java.lang.String QUERY_ARG_SQL_SORT_ORDER = "android:query-arg-sql-sort-order"; field public static final int QUERY_SORT_DIRECTION_ASCENDING = 0; // 0x0 field public static final int QUERY_SORT_DIRECTION_DESCENDING = 1; // 0x1 field public static final java.lang.String SCHEME_ANDROID_RESOURCE = "android.resource"; diff --git a/api/system-current.txt b/api/system-current.txt index 7699cfcc298a..10d8bd653324 100644 --- a/api/system-current.txt +++ b/api/system-current.txt @@ -9236,17 +9236,17 @@ package android.content { field public static final java.lang.String EXTRA_HONORED_ARGS = "android.content.extra.HONORED_ARGS"; field public static final java.lang.String EXTRA_REFRESH_SUPPORTED = "android.content.extra.REFRESH_SUPPORTED"; field public static final java.lang.String EXTRA_SIZE = "android.content.extra.SIZE"; - field public static final java.lang.String EXTRA_TOTAL_SIZE = "android.content.extra.TOTAL_SIZE"; + field public static final java.lang.String EXTRA_TOTAL_COUNT = "android.content.extra.TOTAL_COUNT"; field public static final int NOTIFY_SKIP_NOTIFY_FOR_DESCENDANTS = 2; // 0x2 field public static final int NOTIFY_SYNC_TO_NETWORK = 1; // 0x1 - field public static final java.lang.String QUERY_ARG_LIMIT = "android:query-page-limit"; - field public static final java.lang.String QUERY_ARG_OFFSET = "android:query-page-offset"; - field public static final java.lang.String QUERY_ARG_SORT_COLLATION = "android:query-sort-collation"; - field public static final java.lang.String QUERY_ARG_SORT_COLUMNS = "android:query-sort-columns"; - field public static final java.lang.String QUERY_ARG_SORT_DIRECTION = "android:query-sort-direction"; - field public static final java.lang.String QUERY_ARG_SQL_SELECTION = "android:query-sql-selection"; - field public static final java.lang.String QUERY_ARG_SQL_SELECTION_ARGS = "android:query-sql-selection-args"; - field public static final java.lang.String QUERY_ARG_SQL_SORT_ORDER = "android:query-sql-sort-order"; + field public static final java.lang.String QUERY_ARG_LIMIT = "android:query-arg-limit"; + field public static final java.lang.String QUERY_ARG_OFFSET = "android:query-arg-offset"; + field public static final java.lang.String QUERY_ARG_SORT_COLLATION = "android:query-arg-sort-collation"; + field public static final java.lang.String QUERY_ARG_SORT_COLUMNS = "android:query-arg-sort-columns"; + field public static final java.lang.String QUERY_ARG_SORT_DIRECTION = "android:query-arg-sort-direction"; + field public static final java.lang.String QUERY_ARG_SQL_SELECTION = "android:query-arg-sql-selection"; + field public static final java.lang.String QUERY_ARG_SQL_SELECTION_ARGS = "android:query-arg-sql-selection-args"; + field public static final java.lang.String QUERY_ARG_SQL_SORT_ORDER = "android:query-arg-sql-sort-order"; field public static final int QUERY_SORT_DIRECTION_ASCENDING = 0; // 0x0 field public static final int QUERY_SORT_DIRECTION_DESCENDING = 1; // 0x1 field public static final java.lang.String SCHEME_ANDROID_RESOURCE = "android.resource"; diff --git a/api/test-current.txt b/api/test-current.txt index c8829b01013c..5deec6f8d3d1 100644 --- a/api/test-current.txt +++ b/api/test-current.txt @@ -8769,17 +8769,17 @@ package android.content { field public static final java.lang.String EXTRA_HONORED_ARGS = "android.content.extra.HONORED_ARGS"; field public static final java.lang.String EXTRA_REFRESH_SUPPORTED = "android.content.extra.REFRESH_SUPPORTED"; field public static final java.lang.String EXTRA_SIZE = "android.content.extra.SIZE"; - field public static final java.lang.String EXTRA_TOTAL_SIZE = "android.content.extra.TOTAL_SIZE"; + field public static final java.lang.String EXTRA_TOTAL_COUNT = "android.content.extra.TOTAL_COUNT"; field public static final int NOTIFY_SKIP_NOTIFY_FOR_DESCENDANTS = 2; // 0x2 field public static final int NOTIFY_SYNC_TO_NETWORK = 1; // 0x1 - field public static final java.lang.String QUERY_ARG_LIMIT = "android:query-page-limit"; - field public static final java.lang.String QUERY_ARG_OFFSET = "android:query-page-offset"; - field public static final java.lang.String QUERY_ARG_SORT_COLLATION = "android:query-sort-collation"; - field public static final java.lang.String QUERY_ARG_SORT_COLUMNS = "android:query-sort-columns"; - field public static final java.lang.String QUERY_ARG_SORT_DIRECTION = "android:query-sort-direction"; - field public static final java.lang.String QUERY_ARG_SQL_SELECTION = "android:query-sql-selection"; - field public static final java.lang.String QUERY_ARG_SQL_SELECTION_ARGS = "android:query-sql-selection-args"; - field public static final java.lang.String QUERY_ARG_SQL_SORT_ORDER = "android:query-sql-sort-order"; + field public static final java.lang.String QUERY_ARG_LIMIT = "android:query-arg-limit"; + field public static final java.lang.String QUERY_ARG_OFFSET = "android:query-arg-offset"; + field public static final java.lang.String QUERY_ARG_SORT_COLLATION = "android:query-arg-sort-collation"; + field public static final java.lang.String QUERY_ARG_SORT_COLUMNS = "android:query-arg-sort-columns"; + field public static final java.lang.String QUERY_ARG_SORT_DIRECTION = "android:query-arg-sort-direction"; + field public static final java.lang.String QUERY_ARG_SQL_SELECTION = "android:query-arg-sql-selection"; + field public static final java.lang.String QUERY_ARG_SQL_SELECTION_ARGS = "android:query-arg-sql-selection-args"; + field public static final java.lang.String QUERY_ARG_SQL_SORT_ORDER = "android:query-arg-sql-sort-order"; field public static final int QUERY_SORT_DIRECTION_ASCENDING = 0; // 0x0 field public static final int QUERY_SORT_DIRECTION_DESCENDING = 1; // 0x1 field public static final java.lang.String SCHEME_ANDROID_RESOURCE = "android.resource"; diff --git a/core/java/android/content/ContentProvider.java b/core/java/android/content/ContentProvider.java index d75c2ee0eddd..9d46da16965e 100644 --- a/core/java/android/content/ContentProvider.java +++ b/core/java/android/content/ContentProvider.java @@ -46,6 +46,7 @@ import android.os.RemoteException; import android.os.UserHandle; import android.text.TextUtils; import android.util.Log; +import android.util.MathUtils; import java.io.File; import java.io.FileDescriptor; @@ -1066,14 +1067,65 @@ public abstract class ContentProvider implements ComponentCallbacks2 { * <li>{@link ContentResolver#QUERY_ARG_SQL_SELECTION_ARGS} * <li>{@link ContentResolver#QUERY_ARG_SQL_SORT_ORDER} * + * <p>This method can be called from multiple threads, as described in + * <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html#Threads">Processes + * and Threads</a>. + * + * <p> + * Example client call:<p> + * <pre>// Request 20 records starting at row index 30. + Bundle queryArgs = new Bundle(); + queryArgs.putInt(ContentResolver.QUERY_ARG_OFFSET, 30); + queryArgs.putInt(ContentResolver.QUERY_ARG_LIMIT, 20); + + Cursor cursor = getContentResolver().query( + contentUri, // Content Uri is specific to individual content providers. + projection, // String[] describing which columns to return. + queryArgs, // Query arguments. + null); // Cancellation signal.</pre> + * + * Example implementation:<p> + * <pre> + + int recordsetSize = 0x1000; // Actual value is implementation specific. + queryArgs = queryArgs != null ? queryArgs : Bundle.EMPTY; // ensure queryArgs is non-null + + int offset = queryArgs.getInt(ContentResolver.QUERY_ARG_OFFSET, 0); + int limit = queryArgs.getInt(ContentResolver.QUERY_ARG_LIMIT, Integer.MIN_VALUE); + + MatrixCursor c = new MatrixCursor(PROJECTION, limit); + + // Calculate the number of items to include in the cursor. + int numItems = MathUtils.constrain(recordsetSize - offset, 0, limit); + + // Build the paged result set.... + for (int i = offset; i < offset + numItems; i++) { + // populate row from your data. + } + + Bundle extras = new Bundle(); + c.setExtras(extras); + + // Any QUERY_ARG_* key may be included if honored. + // In an actual implementation, include only keys that are both present in queryArgs + // and reflected in the Cursor output. For example, if QUERY_ARG_OFFSET were included + // in queryArgs, but was ignored because it contained an invalid value (like –273), + // then QUERY_ARG_OFFSET should be omitted. + extras.putStringArray(ContentResolver.EXTRA_HONORED_ARGS, new String[] { + ContentResolver.QUERY_ARG_OFFSET, + ContentResolver.QUERY_ARG_LIMIT + }); + + extras.putInt(ContentResolver.EXTRA_TOTAL_COUNT, recordsetSize); + + cursor.setNotificationUri(getContext().getContentResolver(), uri); + + return cursor;</pre> + * <p> * @see #query(Uri, String[], String, String[], String, CancellationSignal) for * implementation details. * * @param uri The URI to query. This will be the full URI sent by the client. - * TODO: Me wonders about this use case, and how we adapt it. - * 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. * @param projection The list of columns to put into the cursor. * If {@code null} provide a default set of columns. * @param queryArgs A Bundle containing all additional information necessary for the query. diff --git a/core/java/android/content/ContentResolver.java b/core/java/android/content/ContentResolver.java index 98ae132d9ed7..28cfd331cd27 100644 --- a/core/java/android/content/ContentResolver.java +++ b/core/java/android/content/ContentResolver.java @@ -214,10 +214,12 @@ public abstract class ContentResolver { * * <p><b>Apps targeting {@link android.os.Build.VERSION_CODES#O} or higher are strongly * encourage to use structured query arguments in lieu of opaque SQL query clauses.</b> - * See: {@link #QUERY_ARG_SORT_COLUMNS}, {@link #QUERY_ARG_SORT_DIRECTION}, and - * {@link #QUERY_ARG_SORT_COLLATION}. + * + * @see #QUERY_ARG_SORT_COLUMNS + * @see #QUERY_ARG_SORT_DIRECTION + * @see #QUERY_ARG_SORT_COLLATION */ - public static final String QUERY_ARG_SQL_SELECTION = "android:query-sql-selection"; + public static final String QUERY_ARG_SQL_SELECTION = "android:query-arg-sql-selection"; /** * Key for SQL selection string arguments list. @@ -229,10 +231,13 @@ public abstract class ContentResolver { * * <p><b>Apps targeting {@link android.os.Build.VERSION_CODES#O} or higher are strongly * encourage to use structured query arguments in lieu of opaque SQL query clauses.</b> - * See: {@link #QUERY_ARG_SORT_COLUMNS}, {@link #QUERY_ARG_SORT_DIRECTION}, and - * {@link #QUERY_ARG_SORT_COLLATION}. + * + * @see #QUERY_ARG_SORT_COLUMNS + * @see #QUERY_ARG_SORT_DIRECTION + * @see #QUERY_ARG_SORT_COLLATION */ - public static final String QUERY_ARG_SQL_SELECTION_ARGS = "android:query-sql-selection-args"; + public static final String QUERY_ARG_SQL_SELECTION_ARGS = + "android:query-arg-sql-selection-args"; /** * Key for an SQL style sort string that may be present in the query Bundle argument @@ -241,10 +246,12 @@ public abstract class ContentResolver { * * <p><b>Apps targeting {@link android.os.Build.VERSION_CODES#O} or higher are strongly * encourage to use structured query arguments in lieu of opaque SQL query clauses.</b> - * See: {@link #QUERY_ARG_SORT_COLUMNS}, {@link #QUERY_ARG_SORT_DIRECTION}, and - * {@link #QUERY_ARG_SORT_COLLATION}. + * + * @see #QUERY_ARG_SORT_COLUMNS + * @see #QUERY_ARG_SORT_DIRECTION + * @see #QUERY_ARG_SORT_COLLATION */ - public static final String QUERY_ARG_SQL_SORT_ORDER = "android:query-sql-sort-order"; + public static final String QUERY_ARG_SQL_SORT_ORDER = "android:query-arg-sql-sort-order"; /** * Specifies the list of columns against which to sort results. When first column values @@ -255,16 +262,17 @@ public abstract class ContentResolver { * * <p>Apps targeting {@link android.os.Build.VERSION_CODES#O} or higher: * - * <li>When supplying data using a ContentProvider, it is strongly recommended that - * an entry be included in the {@link Cursor} extras {@link Bundle} under this same key - * (@link QUERY_ARG_SORT_COLUMNS}) to indicate which column sorting was applied - * to the recordset, if any. + * <li>{@link ContentProvider} implementations: When preparing data in + * {@link ContentProvider#query(Uri, String[], Bundle, CancellationSignal)}, if sort columns + * is reflected in the returned Cursor, it is strongly recommended that + * {@link #QUERY_ARG_SORT_COLUMNS} then be included in the array of honored arguments + * reflected in {@link Cursor} extras {@link Bundle} under {@link #EXTRA_HONORED_ARGS}. * * <li>When querying a provider, where no QUERY_ARG_SQL* otherwise exists in the * arguments {@link Bundle}, the Content framework will attempt to synthesize * an QUERY_ARG_SQL* argument using the corresponding QUERY_ARG_SORT* values. */ - public static final String QUERY_ARG_SORT_COLUMNS = "android:query-sort-columns"; + public static final String QUERY_ARG_SORT_COLUMNS = "android:query-arg-sort-columns"; /** * Specifies desired sort order. When unspecified a provider may provide a default @@ -272,50 +280,58 @@ public abstract class ContentResolver { * * <p>Apps targeting {@link android.os.Build.VERSION_CODES#O} or higher: * - * <li>When supplying data using a ContentProvider, it is strongly recommended that - * an entry be included in the {@link Cursor} extras {@link Bundle} under this same key - * (@link QUERY_ARG_SORT_DIRECTION}) to indicate that sort direction was applied - * to the recordset. + * <li>{@link ContentProvider} implementations: When preparing data in + * {@link ContentProvider#query(Uri, String[], Bundle, CancellationSignal)}, if sort direction + * is reflected in the returned Cursor, it is strongly recommended that + * {@link #QUERY_ARG_SORT_DIRECTION} then be included in the array of honored arguments + * reflected in {@link Cursor} extras {@link Bundle} under {@link #EXTRA_HONORED_ARGS}. * * <li>When querying a provider, where no QUERY_ARG_SQL* otherwise exists in the * arguments {@link Bundle}, the Content framework will attempt to synthesize - * an QUERY_ARG_SQL* argument using the corresponding QUERY_ARG_SORT* values. + * a QUERY_ARG_SQL* argument using the corresponding QUERY_ARG_SORT* values. * * @see #QUERY_SORT_DIRECTION_ASCENDING * @see #QUERY_SORT_DIRECTION_DESCENDING */ - public static final String QUERY_ARG_SORT_DIRECTION = "android:query-sort-direction"; + public static final String QUERY_ARG_SORT_DIRECTION = "android:query-arg-sort-direction"; /** - * Allows client to specify a hint to the provider as to which collation + * Allows client to specify a hint to the provider declaring which collation * to use when sorting text values. * - * <p>Providers may provide their own collators. When selecting a custom collator - * the value will be determined by the Provider. + * <p>Providers may support custom collators. When specifying a custom collator + * the value is determined by the Provider. * - * <li>When supplying data using a ContentProvider, it is strongly recommended that - * an entry be included in the {@link Cursor} extras {@link Bundle} under this same key - * (@link QUERY_ARG_SORT_COLLATION}) to indicate that sort collation was applied - * to the recordset. + * <li>{@link ContentProvider} implementations: When preparing data in + * {@link ContentProvider#query(Uri, String[], Bundle, CancellationSignal)}, if sort collation + * is reflected in the returned Cursor, it is strongly recommended that + * {@link #QUERY_ARG_SORT_COLLATION} then be included in the array of honored arguments + * reflected in {@link Cursor} extras {@link Bundle} under {@link #EXTRA_HONORED_ARGS}. * - * <p>When querying a provider, where no QUERY_ARG_SQL* otherwise exists in the + * <li>When querying a provider, where no QUERY_ARG_SQL* otherwise exists in the * arguments {@link Bundle}, the Content framework will attempt to synthesize - * an QUERY_ARG_SQL* argument using the corresponding QUERY_ARG_SORT* values. + * a QUERY_ARG_SQL* argument using the corresponding QUERY_ARG_SORT* values. * - * @see java.text.Collator#PRIMARY, java.text.Collator#SECONDARY, - * java.text.Collator#TERTIARY, and java.text.Collator#IDENTICAL. + * @see java.text.Collator#PRIMARY + * @see java.text.Collator#SECONDARY + * @see java.text.Collator#TERTIARY + * @see java.text.Collator#IDENTICAL */ - public static final String QUERY_ARG_SORT_COLLATION = "android:query-sort-collation"; + public static final String QUERY_ARG_SORT_COLLATION = "android:query-arg-sort-collation"; /** - * Allows provider to report back to client which keys were honored. + * Allows provider to report back to client which query keys are honored in a Cursor. * - * Key identifying a {@code String[]} containing all QUERY_ARG_SORT* arguments + * <p>Key identifying a {@code String[]} containing all QUERY_ARG_SORT* arguments * honored by the provider. Include this in {@link Cursor} extras {@link Bundle} * when any QUERY_ARG_SORT* value was honored during the preparation of the * results {@link Cursor}. * - * @see #QUERY_ARG_SORT_COLUMNS, #QUERY_ARG_SORT_DIRECTION, #QUERY_ARG_SORT_COLLATION. + * <p>If present, ALL honored arguments are enumerated in this extra’s payload. + * + * @see #QUERY_ARG_SORT_COLUMNS + * @see #QUERY_ARG_SORT_DIRECTION + * @see #QUERY_ARG_SORT_COLLATION */ public static final String EXTRA_HONORED_ARGS = "android.content.extra.HONORED_ARGS"; @@ -343,41 +359,27 @@ public abstract class ContentResolver { public @interface QueryCollator {} /** - * Specifies the offset from which to load a recordset. Records prior to this - * position should be omitted from results. - * - * <p>Providers are recommended to create a content notification Uri - * that encapsulates QUERY_ARG_OFFSET and QUERY_ARG_LIMITS values reflected - * in the recordset. This will allow a provider to notify clients of changes - * to an individual recordset. + * Specifies the offset row index within a Cursor. */ - public static final String QUERY_ARG_OFFSET = "android:query-page-offset"; + public static final String QUERY_ARG_OFFSET = "android:query-arg-offset"; /** - * Specifies the max number of records to include in a recordset with respect - * to the starting offset, which by default is 0. Records beyond starting offset + limit - * should be omitted from results. - * - * <p>Providers are recommended to create a content notification Uri - * that encapsulates QUERY_ARG_OFFSET and QUERY_ARG_LIMITS values reflected - * in the recordset. This will allow a provider to notify clients of changes - * to an individual recordset. + * Specifies the max number of rows to include in a Cursor. */ - public static final String QUERY_ARG_LIMIT = "android:query-page-limit"; + public static final String QUERY_ARG_LIMIT = "android:query-arg-limit"; /** - * Added to {@link Cursor} extras {@link Bundle} to indicate total size of - * recordset when paging is active. Providers must include this when + * Added to {@link Cursor} extras {@link Bundle} to indicate total row count of + * recordset when paging is supported. Providers must include this when * implementing paging support. * - * <p>When full size of the recordset is unknown a provider may return -1 - * to indicate this. + * <p>A provider may return -1 that row count of the recordset is unknown. * * <p>Providers having returned -1 in a previous query are recommended to * send content change notification once (if) full recordset size becomes * known. */ - public static final String EXTRA_TOTAL_SIZE = "android.content.extra.TOTAL_SIZE"; + public static final String EXTRA_TOTAL_COUNT = "android.content.extra.TOTAL_COUNT"; /** * This is the Android platform's base MIME type for a content: URI |