Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 85e90d09 authored by Jeff Sharkey's avatar Jeff Sharkey
Browse files

New argument to hint at locale to use for sorting. 

We've heard that some developers want more detailed influence over
the sort order applied internally inside of a ContentProvider.  For
example, when the locale is "zh", the caller may want to sort using
either "pinyin" or "zhuyin" style collations.

Thankfully ICU already supports this type of collation control when
creating a ULocale object, and it also supports other useful types
such as "de@collation=phonebook".  Thus this CL adds a new
QUERY_ARG_SORT_LOCALE that can be used to pass an ICU locale string
into a ContentProvider.

Similar to the other existing query arguments, we know that only
certain providers may support this new option, so we document that
it should be included in EXTRA_HONORED_ARGS when applied.

Bug: 140248907
Test: atest cts/tests/tests/content/src/android/content/cts/ContentResolverTest.java
Change-Id: I3277725ecd21a58680f2b8a5cc62514184d9e179
parent 74ccee9f

api/current.txt

+1 −0
Original line number Diff line number Diff line
@@ -9678,6 +9678,7 @@ package android.content { 
    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_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";

core/java/android/content/ContentResolver.java

+41 −13
Original line number Diff line number Diff line
@@ -265,6 +265,7 @@ public abstract class ContentResolver implements ContentInterface { 
     * @see #QUERY_ARG_SORT_COLUMNS

     * @see #QUERY_ARG_SORT_DIRECTION

     * @see #QUERY_ARG_SORT_COLLATION

     * @see #QUERY_ARG_SORT_LOCALE

     */

    public static final String QUERY_ARG_SQL_SELECTION = "android:query-arg-sql-selection";
@@ -282,6 +283,7 @@ public abstract class ContentResolver implements ContentInterface { 
     * @see #QUERY_ARG_SORT_COLUMNS

     * @see #QUERY_ARG_SORT_DIRECTION

     * @see #QUERY_ARG_SORT_COLLATION

     * @see #QUERY_ARG_SORT_LOCALE

     */

    public static final String QUERY_ARG_SQL_SELECTION_ARGS =

            "android:query-arg-sql-selection-args";
@@ -297,6 +299,7 @@ public abstract class ContentResolver implements ContentInterface { 
     * @see #QUERY_ARG_SORT_COLUMNS

     * @see #QUERY_ARG_SORT_DIRECTION

     * @see #QUERY_ARG_SORT_COLLATION

     * @see #QUERY_ARG_SORT_LOCALE

     */

    public static final String QUERY_ARG_SQL_SORT_ORDER = "android:query-arg-sql-sort-order";
@@ -351,20 +354,22 @@ public abstract class ContentResolver implements ContentInterface { 


    /**

     * Allows client to specify a hint to the provider declaring which collation

     * to use when sorting text values.

     *

     * <p>Providers may support custom collators. When specifying a custom collator

     * to use when sorting values.

     * <p>

     * Providers may support custom collators. When specifying a custom collator

     * the value is determined by the Provider.

     *

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

     *

     * <li>When querying a provider, where no QUERY_ARG_SQL* otherwise exists in the

     * arguments {@link Bundle}, the Content framework will attempt to synthesize

     * a QUERY_ARG_SQL* argument using the corresponding QUERY_ARG_SORT* values.

     * <p>

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

     * arguments {@link Bundle}, the Content framework will attempt to

     * synthesize a QUERY_ARG_SQL* argument using the corresponding

     * QUERY_ARG_SORT* values.

     *

     * @see java.text.Collator#PRIMARY

     * @see java.text.Collator#SECONDARY
@@ -373,6 +378,28 @@ public abstract class ContentResolver implements ContentInterface { 
     */

    public static final String QUERY_ARG_SORT_COLLATION = "android:query-arg-sort-collation";



    /**

     * Allows client to specify a hint to the provider declaring which locale to

     * use when sorting values.

     * <p>

     * The value is defined as a RFC 3066 locale ID followed by an optional

     * keyword list, which is the locale format used to configure ICU through

     * classes like {@link android.icu.util.ULocale}. This supports requesting

     * advanced sorting options, such as {@code de@collation=phonebook},

     * {@code zh@collation=pinyin}, etc.

     * <p>

     * {@link ContentProvider} implementations: When preparing data in

     * {@link ContentProvider#query(Uri, String[], Bundle, CancellationSignal)},

     * if sort locale is reflected in the returned Cursor, it is strongly

     * recommended that {@link #QUERY_ARG_SORT_LOCALE} then be included in the

     * array of honored arguments reflected in {@link Cursor} extras

     * {@link Bundle} under {@link #EXTRA_HONORED_ARGS}.

     *

     * @see java.util.Locale#Locale(String)

     * @see android.icu.util.ULocale#ULocale(String)

     */

    public static final String QUERY_ARG_SORT_LOCALE = "android:query-arg-sort-locale";



    /**

     * Allows provider to report back to client which query keys are honored in a Cursor.

     *
@@ -386,6 +413,7 @@ public abstract class ContentResolver implements ContentInterface { 
     * @see #QUERY_ARG_SORT_COLUMNS

     * @see #QUERY_ARG_SORT_DIRECTION

     * @see #QUERY_ARG_SORT_COLLATION

     * @see #QUERY_ARG_SORT_LOCALE

     */

    public static final String EXTRA_HONORED_ARGS = "android.content.extra.HONORED_ARGS";