From 76b2770214aaa6868c476273337263f45fa4dc9d Mon Sep 17 00:00:00 2001 From: Steve McKay Date: Mon, 24 Apr 2017 12:07:53 -0700 Subject: Address API Council feedback. Bug: 37422306, 37419881 Test: Build and read docs. Change-Id: Id6c8bad6ad6b311017094ce5dbd66cfd72c477ad (cherry picked from commit d74a3bd7d1d3175856f450a9e77dabb89f2e5060) --- api/current.txt | 18 ++-- api/system-current.txt | 18 ++-- api/test-current.txt | 18 ++-- core/java/android/content/ContentProvider.java | 60 ++++++++++++- 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 7a01e1a874fc..50c1cb756d80 100644 --- a/api/current.txt +++ b/api/current.txt @@ -8719,17 +8719,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 6c5931e8a739..38b93073527a 100644 --- a/api/system-current.txt +++ b/api/system-current.txt @@ -9216,17 +9216,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 c00795db237b..5ac522824a1b 100644 --- a/api/test-current.txt +++ b/api/test-current.txt @@ -8751,17 +8751,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 { *
  • {@link ContentResolver#QUERY_ARG_SQL_SELECTION_ARGS} *
  • {@link ContentResolver#QUERY_ARG_SQL_SORT_ORDER} * + *

    This method can be called from multiple threads, as described in + * Processes + * and Threads. + * + *

    + * Example client call:

    + * 

    // 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.
    + * + * Example implementation:

    + * 

    +
+        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;
    + *

    * @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 { * *

    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. - * 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 { * *

    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. - * 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 { * *

    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. - * 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 { * *

    Apps targeting {@link android.os.Build.VERSION_CODES#O} or higher: * - *

  • 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. + *
  • {@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}. * *
  • 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 { * *

    Apps targeting {@link android.os.Build.VERSION_CODES#O} or higher: * - *

  • 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. + *
  • {@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}. * *
  • 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. * - *

    Providers may provide their own collators. When selecting a custom collator - * the value will be determined by the Provider. + *

    Providers may support custom collators. When specifying a custom collator + * the value is determined by the Provider. * - *

  • 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. + *
  • {@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}. * - *

    When querying a provider, where no QUERY_ARG_SQL* otherwise exists in the + *

  • 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 + *

    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. + *

    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. - * - *

    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. - * - *

    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. * - *

    When full size of the recordset is unknown a provider may return -1 - * to indicate this. + *

    A provider may return -1 that row count of the recordset is unknown. * *

    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 -- cgit v1.2.3-59-g8ed1b