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
(cherry picked from commit 405697458360779a9d7e731b4e8dbe0eeb9b3f0d)
Merged-In: Icbccdb5183edd0b6a052ec905f999f02ac4e61d3

1 files changed, 8 insertions, 4 deletions

diff --git a/graphics/java/android/graphics/ImageDecoder.java b/graphics/java/android/graphics/ImageDecoder.java
index 97b448aa8ff0..c8f065ad094c 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(...);
@@ -1032,7 +1032,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}.