From 405697458360779a9d7e731b4e8dbe0eeb9b3f0d Mon Sep 17 00:00:00 2001
From: Leon Scroggins III <scroggo@google.com>
Date: Mon, 11 May 2020 16:49:51 -0400
Subject: [PATCH] Update ImageDecoder docs regarding Files

Bug: 139186570
Test: make docs

As part of enforcing Scoped Storage for the next Android release, we're
encouraging app developers to steer away from using raw file path access
and, instead, use FileDescriptor or Uri to access files.

Update createSource(File)'s docs to suggest why they might want to use a
different method.

Update the top level example to use createSource(ContentResolver, Uri)
instead of createSource(File).

Change-Id: Icbccdb5183edd0b6a052ec905f999f02ac4e61d3
---
 graphics/java/android/graphics/ImageDecoder.java | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/graphics/java/android/graphics/ImageDecoder.java b/graphics/java/android/graphics/ImageDecoder.java
index 1b4b863608011..ca37917f437f3 100644
--- a/graphics/java/android/graphics/ImageDecoder.java
+++ b/graphics/java/android/graphics/ImageDecoder.java
@@ -70,9 +70,9 @@ import java.util.concurrent.atomic.AtomicBoolean;
  *  {@link Bitmap} objects.
  *
  *  <p>To use it, first create a {@link Source Source} using one of the
- *  {@code createSource} overloads. For example, to decode from a {@link File}, call
- *  {@link #createSource(File)} and pass the result to {@link #decodeDrawable(Source)}
- *  or {@link #decodeBitmap(Source)}:
+ *  {@code createSource} overloads. For example, to decode from a {@link Uri}, call
+ *  {@link #createSource(ContentResolver, Uri)} and pass the result to
+ *  {@link #decodeDrawable(Source)} or {@link #decodeBitmap(Source)}:
  *
  *  <pre class="prettyprint">
  *  File file = new File(...);
@@ -1045,7 +1045,11 @@ public final class ImageDecoder implements AutoCloseable {
 
     /**
      * Create a new {@link Source Source} from a {@link java.io.File}.
-     *
+     * <p>
+     * This method should only be used for files that you have direct access to;
+     * if you'd like to work with files hosted outside your app, use an API like
+     * {@link #createSource(Callable)} or
+     * {@link #createSource(ContentResolver, Uri)}.
      * @return a new Source object, which can be passed to
      *      {@link #decodeDrawable decodeDrawable} or
      *      {@link #decodeBitmap decodeBitmap}.