Merge "Address API Council feedback." into oc-dev

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_LIMIT = "android:query-arg-limit";
-    field public static final java.lang.String QUERY_ARG_OFFSET = "android:query-page-offset";
+    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-sort-collation";
+    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-sort-columns";
+    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-sort-direction";
+    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-sql-selection";
+    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-sql-selection-args";
+    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-sql-sort-order";
+    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";

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_LIMIT = "android:query-arg-limit";
-    field public static final java.lang.String QUERY_ARG_OFFSET = "android:query-page-offset";
+    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-sort-collation";
+    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-sort-columns";
+    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-sort-direction";
+    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-sql-selection";
+    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-sql-selection-args";
+    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-sql-sort-order";
+    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";

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_LIMIT = "android:query-arg-limit";
-    field public static final java.lang.String QUERY_ARG_OFFSET = "android:query-page-offset";
+    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-sort-collation";
+    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-sort-columns";
+    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-sort-direction";
+    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-sql-selection";
+    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-sql-selection-args";
+    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-sql-sort-order";
+    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";

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.

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
+     * <li>{@link ContentProvider} implementations: When preparing data in
-     * an entry be included in the {@link Cursor} extras {@link Bundle} under this same key
+     * {@link ContentProvider#query(Uri, String[], Bundle, CancellationSignal)}, if sort columns
-     * (@link QUERY_ARG_SORT_COLUMNS}) to indicate which column sorting was applied
+     * is reflected in the returned Cursor, it is  strongly recommended that
-     * to the recordset, if any.
+     * {@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
+     * <li>{@link ContentProvider} implementations: When preparing data in
-     * an entry be included in the {@link Cursor} extras {@link Bundle} under this same key
+     * {@link ContentProvider#query(Uri, String[], Bundle, CancellationSignal)}, if sort direction
-     * (@link QUERY_ARG_SORT_DIRECTION}) to indicate that sort direction was applied
+     * is reflected in the returned Cursor, it is  strongly recommended that
-     * to the recordset.
+     * {@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
+     * <p>Providers may support custom collators. When specifying a custom collator
-     * the value will be determined by the Provider.
+     * the value is determined by the Provider.
      *
-     * <li>When supplying data using a ContentProvider, it is strongly recommended that
+     * <li>{@link ContentProvider} implementations: When preparing data in
-     * an entry be included in the {@link Cursor} extras {@link Bundle} under this same key
+     * {@link ContentProvider#query(Uri, String[], Bundle, CancellationSignal)}, if sort collation
-     * (@link QUERY_ARG_SORT_COLLATION}) to indicate that sort collation was applied
+     * is reflected in the returned Cursor, it is  strongly recommended that
-     * to the recordset.
+     * {@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,
+     * @see java.text.Collator#PRIMARY
-     *     java.text.Collator#TERTIARY, and java.text.Collator#IDENTICAL.
+     * @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
+     * Specifies the offset row index within a Cursor.
-     * 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.
      */
-    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
+     * Specifies the max number of rows to include in a Cursor.
-     * 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.
      */
-    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
+     * Added to {@link Cursor} extras {@link Bundle} to indicate total row count of
-     * recordset when paging is active. Providers must include this when
+     * 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
+     * <p>A provider may return -1 that row count of the recordset is unknown.
-     * to indicate this.
      *
      * <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