diff --git a/api/current.txt b/api/current.txt index 5d2a1bd9b05bf..667f5d2f1d60c 100644 --- a/api/current.txt +++ b/api/current.txt @@ -9695,12 +9695,16 @@ package android.content { field public static final 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 String QUERY_ARG_GROUP_COLUMNS = "android:query-arg-group-columns"; field public static final String QUERY_ARG_LIMIT = "android:query-arg-limit"; field public static final String QUERY_ARG_OFFSET = "android:query-arg-offset"; field public static final String QUERY_ARG_SORT_COLLATION = "android:query-arg-sort-collation"; field public static final String QUERY_ARG_SORT_COLUMNS = "android:query-arg-sort-columns"; field public static final String QUERY_ARG_SORT_DIRECTION = "android:query-arg-sort-direction"; field public static final String QUERY_ARG_SORT_LOCALE = "android:query-arg-sort-locale"; + field public static final String QUERY_ARG_SQL_GROUP_BY = "android:query-arg-sql-group-by"; + field public static final String QUERY_ARG_SQL_HAVING = "android:query-arg-sql-having"; + field public static final String QUERY_ARG_SQL_LIMIT = "android:query-arg-sql-limit"; field public static final String QUERY_ARG_SQL_SELECTION = "android:query-arg-sql-selection"; field public static final String QUERY_ARG_SQL_SELECTION_ARGS = "android:query-arg-sql-selection-args"; field public static final String QUERY_ARG_SQL_SORT_ORDER = "android:query-arg-sql-sort-order"; diff --git a/core/java/android/content/ContentResolver.java b/core/java/android/content/ContentResolver.java index 61c8db5db124a..a93c6d25c38fd 100644 --- a/core/java/android/content/ContentResolver.java +++ b/core/java/android/content/ContentResolver.java @@ -304,31 +304,61 @@ public abstract class ContentResolver implements ContentInterface { */ public static final String QUERY_ARG_SQL_SORT_ORDER = "android:query-arg-sql-sort-order"; - /** {@hide} */ + /** + * Key for an SQL style {@code GROUP BY} string that may be present in the + * query Bundle argument passed to + * {@link ContentProvider#query(Uri, String[], Bundle, CancellationSignal)}. + * + *

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 #QUERY_ARG_GROUP_COLUMNS + */ public static final String QUERY_ARG_SQL_GROUP_BY = "android:query-arg-sql-group-by"; - /** {@hide} */ + + /** + * Key for an SQL style {@code HAVING} string that may be present in the + * query Bundle argument passed to + * {@link ContentProvider#query(Uri, String[], Bundle, CancellationSignal)}. + * + *

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. + */ public static final String QUERY_ARG_SQL_HAVING = "android:query-arg-sql-having"; - /** {@hide} */ + + /** + * Key for an SQL style {@code LIMIT} string that may be present in the + * query Bundle argument passed to + * {@link ContentProvider#query(Uri, String[], Bundle, CancellationSignal)}. + * + *

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 #QUERY_ARG_LIMIT + * @see #QUERY_ARG_OFFSET + */ public static final String QUERY_ARG_SQL_LIMIT = "android:query-arg-sql-limit"; /** - * Specifies the list of columns against which to sort results. When first column values - * are identical, records are then sorted based on second column values, and so on. - * - *

Columns present in this list must also be included in the projection - * supplied to {@link ContentResolver#query(Uri, String[], Bundle, CancellationSignal)}. - * - *

Apps targeting {@link android.os.Build.VERSION_CODES#O} or higher: - * + * Specifies the list of columns (stored as a {@code String[]}) against + * which to sort results. When first column values are identical, records + * are then sorted based on second column values, and so on. + *

+ * Columns present in this list must also be included in the projection + * supplied to + * {@link ContentResolver#query(Uri, String[], Bundle, CancellationSignal)}. + *

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

  • {@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. + * {@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-arg-sort-columns"; @@ -401,6 +431,29 @@ public abstract class ContentResolver implements ContentInterface { */ public static final String QUERY_ARG_SORT_LOCALE = "android:query-arg-sort-locale"; + /** + * Specifies the list of columns (stored as a {@code String[]}) against + * which to group results. When column values are identical, multiple + * records are collapsed together into a single record. + *

    + * Columns present in this list must also be included in the projection + * supplied to + * {@link ContentResolver#query(Uri, String[], Bundle, CancellationSignal)}. + *

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

  • {@link ContentProvider} implementations: When preparing data in + * {@link ContentProvider#query(Uri, String[], Bundle, CancellationSignal)}, + * if group 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_GROUP_COLUMNS = "android:query-arg-group-columns"; + /** * Allows provider to report back to client which query keys are honored in a Cursor. * @@ -415,6 +468,7 @@ public abstract class ContentResolver implements ContentInterface { * @see #QUERY_ARG_SORT_DIRECTION * @see #QUERY_ARG_SORT_COLLATION * @see #QUERY_ARG_SORT_LOCALE + * @see #QUERY_ARG_GROUP_COLUMNS */ public static final String EXTRA_HONORED_ARGS = "android.content.extra.HONORED_ARGS";