From 09bb615ce1da5e2e9a99f0a2ebf46beb6f71a7a9 Mon Sep 17 00:00:00 2001
From: Jesse Wilson <jessewilson@google.com>
Date: Wed, 29 Jun 2011 10:57:20 -0700
Subject: Use a clear warning in the DexClassLoader docs.

Cherry-pick of I0cc4bb3ec86b1c3c578c548f6fc646bce9e45745
http://b/4609061

Change-Id: I8ef78c4117f67b1b517d4512b28e73533f64645c
---
 .../main/java/dalvik/system/DexClassLoader.java    | 38 ++++++++++++----------
 1 file changed, 20 insertions(+), 18 deletions(-)

(limited to 'dalvik')

diff --git a/dalvik/src/main/java/dalvik/system/DexClassLoader.java b/dalvik/src/main/java/dalvik/system/DexClassLoader.java
index fea65dd..775a38a 100644
--- a/dalvik/src/main/java/dalvik/system/DexClassLoader.java
+++ b/dalvik/src/main/java/dalvik/system/DexClassLoader.java
@@ -23,15 +23,19 @@ import java.net.URL;
 import java.util.zip.ZipFile;
 
 /**
- * Provides a simple {@link ClassLoader} implementation that operates on a
- * list of jar/apk files with classes.dex entries.  The directory that
- * holds the optimized form of the files is specified explicitly.  This
- * can be used to execute code not installed as part of an application.
+ * A class loader that loads classes from {@code .jar} and {@code .apk} files
+ * containing a {@code classes.dex} entry. This can be used to execute code not
+ * installed as part of an application.
  *
- * The best place to put the optimized DEX files is in app-specific
- * storage, so that removal of the app will automatically remove the
- * optimized DEX files.  If other storage is used (e.g. /sdcard), the
- * app may not have an opportunity to remove them.
+ * <p>This class loader requires an application-private, writable directory to
+ * cache optimized classes. Use {@code Context.getDir(String, int)} to create
+ * such a directory: <pre>   {@code
+ *   File dexOutputDir = context.getDir("dex", 0);
+ * }</pre>
+ *
+ * <p><strong>Do not cache optimized classes on external storage.</strong>
+ * External storage does not provide access controls necessary to protect your
+ * application from code injection attacks.
  */
 public class DexClassLoader extends ClassLoader {
     // TODO: Factor out commonality between this class and PathClassLoader.
@@ -63,17 +67,15 @@ public class DexClassLoader extends ClassLoader {
      * code.  Interpreted classes are found in a set of DEX files contained
      * in Jar or APK files.
      *
-     * The path lists are separated using the character specified by
-     * the "path.separator" system property, which defaults to ":".
+     * <p>The path lists are separated using the character specified by the
+     * {@code path.separator} system property, which defaults to {@code :}.
      *
-     * @param dexPath
-     *  the list of jar/apk files containing classes and resources
-     * @param dexOutputDir
-     *  directory where optimized DEX files should be written
-     * @param libPath
-     *  the list of directories containing native libraries; may be null
-     * @param parent
-     *  the parent class loader
+     * @param dexPath the list of jar/apk files containing classes and resources
+     * @param dexOutputDir directory where optimized DEX files should be
+     *     written. This should be an application-private, writable directory.
+     * @param libPath the list of directories containing native libraries; may
+     *     be null
+     * @param parent the parent class loader
      */
     public DexClassLoader(String dexPath, String dexOutputDir, String libPath,
             ClassLoader parent) {
-- 
cgit v1.1