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

Commit c192ca5a authored by Jeff Sharkey's avatar Jeff Sharkey
Browse files

Respond to API council feedback. 

Adjust Exception to more general Throwable, and add docs for
new ContentResolver and ContentProvider overloads.  Also add docs
for default state of strict query options.

Bug: 131598520, 141227540, 147287177
Test: atest --test-mapping packages/providers/MediaProvider
Change-Id: Icb0153b8c8a352db39de301074e948bfaa676ddb
parent 197fe1f9

api/current.txt

+2 −2
Original line number Diff line number Diff line
@@ -9627,13 +9627,13 @@ package android.content { 
    ctor public ContentProviderResult(@NonNull android.net.Uri);

    ctor public ContentProviderResult(int);

    ctor public ContentProviderResult(@NonNull android.os.Bundle);

    ctor public ContentProviderResult(@NonNull Exception);

    ctor public ContentProviderResult(@NonNull Throwable);

    ctor public ContentProviderResult(android.os.Parcel);

    method public int describeContents();

    method public void writeToParcel(android.os.Parcel, int);

    field @NonNull public static final android.os.Parcelable.Creator<android.content.ContentProviderResult> CREATOR;

    field @Nullable public final Integer count;

    field @Nullable public final Exception exception;

    field @Nullable public final Throwable exception;

    field @Nullable public final android.os.Bundle extras;

    field @Nullable public final android.net.Uri uri;

  }

core/java/android/content/ContentProvider.java

+26 −11
Original line number Diff line number Diff line
@@ -1409,8 +1409,11 @@ public abstract class ContentProvider implements ContentInterface, ComponentCall 
     * @param uri The URI to query. This will be the full URI sent by the client.

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

     *            Values in the Bundle may include SQL style arguments.

     * @param queryArgs A Bundle containing additional information necessary for

     *            the operation. Arguments may include SQL style arguments, such

     *            as {@link ContentResolver#QUERY_ARG_SQL_LIMIT}, but note that

     *            the documentation for each individual provider will indicate

     *            which arguments they support.

     * @param cancellationSignal A signal to cancel the operation in progress,

     *            or {@code null}.

     * @return a Cursor or {@code null}.
@@ -1609,9 +1612,14 @@ public abstract class ContentProvider implements ContentInterface, ComponentCall 
     *

     * @param uri The content:// URI of the insertion request.

     * @param values A set of column_name/value pairs to add to the database.

     * @param extras A Bundle containing all additional information necessary

     *            for the insert.

     * @param extras A Bundle containing additional information necessary for

     *            the operation. Arguments may include SQL style arguments, such

     *            as {@link ContentResolver#QUERY_ARG_SQL_LIMIT}, but note that

     *            the documentation for each individual provider will indicate

     *            which arguments they support.

     * @return The URI for the newly inserted item.

     * @throws IllegalArgumentException if the provider doesn't support one of

     *             the requested Bundle arguments.

     */

    @Override

    public @Nullable Uri insert(@NonNull Uri uri, @Nullable ContentValues values,
@@ -1688,10 +1696,13 @@ public abstract class ContentProvider implements ContentInterface, ComponentCall 
     *

     * @param uri The full URI to query, including a row ID (if a specific

     *            record is requested).

     * @param extras A Bundle containing all additional information necessary

     *            for the delete. Values in the Bundle may include SQL style

     *            arguments.

     * @return The number of rows affected.

     * @param extras A Bundle containing additional information necessary for

     *            the operation. Arguments may include SQL style arguments, such

     *            as {@link ContentResolver#QUERY_ARG_SQL_LIMIT}, but note that

     *            the documentation for each individual provider will indicate

     *            which arguments they support.

     * @throws IllegalArgumentException if the provider doesn't support one of

     *             the requested Bundle arguments.

     * @throws SQLException

     */

    @Override
@@ -1734,10 +1745,14 @@ public abstract class ContentProvider implements ContentInterface, ComponentCall 
     * @param uri The URI to query. This can potentially have a record ID if

     *            this is an update request for a specific record.

     * @param values A set of column_name/value pairs to update in the database.

     * @param extras A Bundle containing all additional information necessary

     *            for the update. Values in the Bundle may include SQL style

     *            arguments.

     * @param extras A Bundle containing additional information necessary for

     *            the operation. Arguments may include SQL style arguments, such

     *            as {@link ContentResolver#QUERY_ARG_SQL_LIMIT}, but note that

     *            the documentation for each individual provider will indicate

     *            which arguments they support.

     * @return the number of rows affected.

     * @throws IllegalArgumentException if the provider doesn't support one of

     *             the requested Bundle arguments.

     */

    @Override

    public int update(@NonNull Uri uri, @Nullable ContentValues values,

core/java/android/content/ContentProviderResult.java

+4 −4
Original line number Diff line number Diff line
@@ -36,7 +36,7 @@ public class ContentProviderResult implements Parcelable { 
    public final @Nullable Uri uri;

    public final @Nullable Integer count;

    public final @Nullable Bundle extras;

    public final @Nullable Exception exception;

    public final @Nullable Throwable exception;



    public ContentProviderResult(@NonNull Uri uri) {

        this(Objects.requireNonNull(uri), null, null, null);
@@ -50,12 +50,12 @@ public class ContentProviderResult implements Parcelable { 
        this(null, null, Objects.requireNonNull(extras), null);

    }



    public ContentProviderResult(@NonNull Exception exception) {

    public ContentProviderResult(@NonNull Throwable exception) {

        this(null, null, null, exception);

    }



    /** {@hide} */

    public ContentProviderResult(Uri uri, Integer count, Bundle extras, Exception exception) {

    public ContentProviderResult(Uri uri, Integer count, Bundle extras, Throwable exception) {

        this.uri = uri;

        this.count = count;

        this.extras = extras;
@@ -79,7 +79,7 @@ public class ContentProviderResult implements Parcelable { 
            extras = null;

        }

        if (source.readInt() != 0) {

            exception = (Exception) ParcelableException.readFromParcel(source);

            exception = ParcelableException.readFromParcel(source);

        } else {

            exception = null;

        }

core/java/android/content/ContentResolver.java

+26 −6
Original line number Diff line number Diff line
@@ -984,7 +984,11 @@ public abstract class ContentResolver implements ContentInterface { 
     *         retrieve.

     * @param projection A list of which columns to return. Passing null will

     *         return all columns, which is inefficient.

     * @param queryArgs A Bundle containing any arguments to the query.

     * @param queryArgs A Bundle containing additional information necessary for

     *            the operation. Arguments may include SQL style arguments, such

     *            as {@link ContentResolver#QUERY_ARG_SQL_LIMIT}, but note that

     *            the documentation for each individual provider will indicate

     *            which arguments they support.

     * @param cancellationSignal A signal to cancel the operation in progress, or null if none.

     * If the operation is canceled, then {@link OperationCanceledException} will be thrown

     * when the query is executed.
@@ -1925,9 +1929,15 @@ public abstract class ContentResolver implements ContentInterface { 
     * @param url The URL of the table to insert into.

     * @param values The initial values for the newly inserted row. The key is the column name for

     *               the field. Passing an empty ContentValues will create an empty row.

     * @param extras A Bundle containing all additional information necessary for the insert.

     * @param extras A Bundle containing additional information necessary for

     *            the operation. Arguments may include SQL style arguments, such

     *            as {@link ContentResolver#QUERY_ARG_SQL_LIMIT}, but note that

     *            the documentation for each individual provider will indicate

     *            which arguments they support.

     * @return the URL of the newly created row. May return <code>null</code> if the underlying

     *         content provider returns <code>null</code>, or if it crashes.

     * @throws IllegalArgumentException if the provider doesn't support one of

     *             the requested Bundle arguments.

     */

    @Override

    public final @Nullable Uri insert(@RequiresPermission.Write @NonNull Uri url,
@@ -2061,9 +2071,14 @@ public abstract class ContentResolver implements ContentInterface { 
     * If the content provider supports transactions, the deletion will be atomic.

     *

     * @param url The URL of the row to delete.

     * @param extras A Bundle containing all additional information necessary for the delete.

     *            Values in the Bundle may include SQL style arguments.

     * @param extras A Bundle containing additional information necessary for

     *            the operation. Arguments may include SQL style arguments, such

     *            as {@link ContentResolver#QUERY_ARG_SQL_LIMIT}, but note that

     *            the documentation for each individual provider will indicate

     *            which arguments they support.

     * @return The number of rows deleted.

     * @throws IllegalArgumentException if the provider doesn't support one of

     *             the requested Bundle arguments.

     */

    @Override

    public final int delete(@RequiresPermission.Write @NonNull Uri url, @Nullable Bundle extras) {
@@ -2121,10 +2136,15 @@ public abstract class ContentResolver implements ContentInterface { 
     * @param uri The URI to modify.

     * @param values The new field values. The key is the column name for the field.

                     A null value will remove an existing field value.

     * @param extras A Bundle containing all additional information necessary for the update.

     *            Values in the Bundle may include SQL style arguments.

     * @param extras A Bundle containing additional information necessary for

     *            the operation. Arguments may include SQL style arguments, such

     *            as {@link ContentResolver#QUERY_ARG_SQL_LIMIT}, but note that

     *            the documentation for each individual provider will indicate

     *            which arguments they support.

     * @return the number of rows updated.

     * @throws NullPointerException if uri or values are null

     * @throws IllegalArgumentException if the provider doesn't support one of

     *             the requested Bundle arguments.

     */

    @Override

    public final int update(@RequiresPermission.Write @NonNull Uri uri,

core/java/android/database/sqlite/SQLiteQueryBuilder.java

+19 −11
Original line number Diff line number Diff line
@@ -240,25 +240,27 @@ public class SQLiteQueryBuilder { 
    }



    /**

     * When set, the selection is verified against malicious arguments.

     * When using this class to create a statement using

     * When set, the selection is verified against malicious arguments. When

     * using this class to create a statement using

     * {@link #buildQueryString(boolean, String, String[], String, String, String, String, String)},

     * non-numeric limits will raise an exception. If a projection map is specified, fields

     * not in that map will be ignored.

     * If this class is used to execute the statement directly using

     * non-numeric limits will raise an exception. If a projection map is

     * specified, fields not in that map will be ignored. If this class is used

     * to execute the statement directly using

     * {@link #query(SQLiteDatabase, String[], String, String[], String, String, String)}

     * or

     * {@link #query(SQLiteDatabase, String[], String, String[], String, String, String, String)},

     * additionally also parenthesis escaping selection are caught.

     *

     * To summarize: To get maximum protection against malicious third party apps (for example

     * content provider consumers), make sure to do the following:

     * additionally also parenthesis escaping selection are caught. To

     * summarize: To get maximum protection against malicious third party apps

     * (for example content provider consumers), make sure to do the following:

     * <ul>

     * <li>Set this value to true</li>

     * <li>Use a projection map</li>

     * <li>Use one of the query overloads instead of getting the statement as a sql string</li>

     * <li>Use one of the query overloads instead of getting the statement as a

     * sql string</li>

     * </ul>

     * By default, this value is false.

     * <p>

     * This feature is disabled by default on each newly constructed

     * {@link SQLiteQueryBuilder} and needs to be manually enabled.

     */

    public void setStrict(boolean strict) {

        if (strict) {
@@ -283,6 +285,9 @@ public class SQLiteQueryBuilder { 
     * This enforcement applies to {@link #insert}, {@link #query}, and

     * {@link #update} operations. Any enforcement failures will throw an

     * {@link IllegalArgumentException}.

     * <p>

     * This feature is disabled by default on each newly constructed

     * {@link SQLiteQueryBuilder} and needs to be manually enabled.

     */

    public void setStrictColumns(boolean strictColumns) {

        if (strictColumns) {
@@ -319,6 +324,9 @@ public class SQLiteQueryBuilder { 
     * {@link #delete} operations. This enforcement does not apply to trusted

     * inputs, such as those provided by {@link #appendWhere}. Any enforcement

     * failures will throw an {@link IllegalArgumentException}.

     * <p>

     * This feature is disabled by default on each newly constructed

     * {@link SQLiteQueryBuilder} and needs to be manually enabled.

     */

    public void setStrictGrammar(boolean strictGrammar) {

        if (strictGrammar) {