Deprecate many of the accidentally-published APIs in dalvik.system.

See bug 2021674 for discussion. I searched Google Code Search to
sample which of these APIs are being used. None of these APIs
were used by applications, so I'm quite confident that removing
them will not break applications or upset developers.

These APIs were neither formerly documented, nor intended for use
by application developers. I am deprecating them now to discourage
their use going forward. We should remove them in a future release.

9 files changed, 33 insertions, 22 deletions

diff --git a/dalvik/src/main/java/dalvik/system/AllocationLimitError.java b/dalvik/src/main/java/dalvik/system/AllocationLimitError.java
index 85f7de6..9118199 100644
--- a/dalvik/src/main/java/dalvik/system/AllocationLimitError.java
+++ b/dalvik/src/main/java/dalvik/system/AllocationLimitError.java
@@ -18,8 +18,9 @@ package dalvik.system;
 
 /**
  * Is thrown when an allocation limit is exceeded.
- * 
- * @since Android 1.0
+ *
+ * @deprecated this is an internal Dalvik class that is not appropriate for
+ *      general use. It will be removed from the public API in a future release.
  */
 public class AllocationLimitError extends VirtualMachineError {
     /**
diff --git a/dalvik/src/main/java/dalvik/system/PotentialDeadlockError.java b/dalvik/src/main/java/dalvik/system/PotentialDeadlockError.java
index c85caee..938a5cd 100644
--- a/dalvik/src/main/java/dalvik/system/PotentialDeadlockError.java
+++ b/dalvik/src/main/java/dalvik/system/PotentialDeadlockError.java
@@ -18,8 +18,9 @@ package dalvik.system;
 
 /**
  * Is thrown when the VM identifies a potential deadlock.
- * 
- * @since Android 1.0
+ *
+ * @deprecated this is an internal Dalvik class that is not appropriate for
+ *      general use. It will be removed from the public API in a future release.
  */
 public class PotentialDeadlockError extends VirtualMachineError {
     /**
diff --git a/dalvik/src/main/java/dalvik/system/StaleDexCacheError.java b/dalvik/src/main/java/dalvik/system/StaleDexCacheError.java
index 44a40a5..ffde7cb 100644
--- a/dalvik/src/main/java/dalvik/system/StaleDexCacheError.java
+++ b/dalvik/src/main/java/dalvik/system/StaleDexCacheError.java
@@ -19,6 +19,9 @@ package dalvik.system;
 /**
  * Is thrown when the VM determines that a DEX file's cache is out of date, and
  * that there is no way to recreate it.
+ *
+ * @deprecated this is an internal Dalvik class that is not appropriate for
+ *      general use. It will be removed from the public API in a future release.
  */
 public class StaleDexCacheError extends VirtualMachineError {
     /**
diff --git a/dalvik/src/main/java/dalvik/system/TemporaryDirectory.java b/dalvik/src/main/java/dalvik/system/TemporaryDirectory.java
index 2f909ac..0e26a70 100644
--- a/dalvik/src/main/java/dalvik/system/TemporaryDirectory.java
+++ b/dalvik/src/main/java/dalvik/system/TemporaryDirectory.java
@@ -25,8 +25,9 @@ import java.util.logging.Logger;
  * call into this class with an appropriate base directory during its
  * startup, as a reasonably easy way to get the standard property
  * <code>java.io.tmpdir</code> to point at something useful.
- * 
- * @since Android 1.0
+ *
+ * @deprecated this is an internal Dalvik class that is not appropriate for
+ *      general use. It will be removed from the public API in a future release.
  */
 public class TemporaryDirectory {
     /** system property name for the temporary directory */
diff --git a/dalvik/src/main/java/dalvik/system/TouchDex.java b/dalvik/src/main/java/dalvik/system/TouchDex.java
index 2dbc3ea..04c6546 100644
--- a/dalvik/src/main/java/dalvik/system/TouchDex.java
+++ b/dalvik/src/main/java/dalvik/system/TouchDex.java
@@ -25,13 +25,8 @@ import java.io.FilenameFilter;
 /**
  * Induces optimization/verification of a set of DEX files.
  *
- * TODO: This class is public, so SystemServer can access it.  This is NOT
- * the correct long-term solution; once we have a real installer and/or
- * dalvik-cache manager, this class should be removed.
- * 
- * @cts See to-do about removing this class...
- * 
- * @since Android 1.0
+ * @deprecated this is an internal Dalvik class that is not appropriate for
+ *      general use. It will be removed from the public API in a future release.
  */
 public class TouchDex {
 
diff --git a/dalvik/src/main/java/dalvik/system/VMDebug.java b/dalvik/src/main/java/dalvik/system/VMDebug.java
index bcc8b61..365388a 100644
--- a/dalvik/src/main/java/dalvik/system/VMDebug.java
+++ b/dalvik/src/main/java/dalvik/system/VMDebug.java
@@ -27,8 +27,9 @@ import java.io.IOException;
  * <code>android.os.Debug</code>.
  * 
  * @cts Please complete the spec.
- * 
- * @since Android 1.0
+ *
+ * @deprecated this is an internal Dalvik class that is not appropriate for
+ *      general use. It will be removed from the public API in a future release.
  */
 public final class VMDebug {
     /**
diff --git a/dalvik/src/main/java/dalvik/system/VMRuntime.java b/dalvik/src/main/java/dalvik/system/VMRuntime.java
index 5d5e600..7ac0849 100644
--- a/dalvik/src/main/java/dalvik/system/VMRuntime.java
+++ b/dalvik/src/main/java/dalvik/system/VMRuntime.java
@@ -20,7 +20,10 @@ package dalvik.system;
  * Provides an interface to VM-global, Dalvik-specific features.
  * An application cannot create its own Runtime instance, and must obtain
  * one from the getRuntime method.
- * 
+ *
+ * @deprecated this is an internal Dalvik class that is not appropriate for
+ *      general use. It will be removed from the public API in a future release.
+ *
  * @since Android 1.0
  */
 public final class VMRuntime {
@@ -62,6 +65,8 @@ public final class VMRuntime {
      * be resized so that (size of live objects) / (size of heap) is
      * equal to this number.
      *
+     * <p>This is only a hint to the garbage collector and may be ignored.
+     *
      * @param newTarget the new suggested ideal heap utilization.
      *                  This value may be adjusted internally.
      * @return the previous ideal heap utilization
@@ -98,7 +103,9 @@ public final class VMRuntime {
      * size, the maximum size will be used.  If size is zero
      * or negative, the minimum size constraint will be removed.
      *
-     * Synchronized to make the order of the exchange reliable.
+     * <p>Synchronized to make the order of the exchange reliable.
+     *
+     * <p>This is only a hint to the garbage collector and may be ignored.
      *
      * @param size the new suggested minimum heap size, in bytes
      * @return the old minimum heap size value
@@ -175,7 +182,7 @@ public final class VMRuntime {
     /**
      * Returns the number of externally-allocated bytes being tracked by
      * trackExternalAllocation/Free().
-     * 
+     *
      * @return the number of bytes
      */
     public native long getExternalBytesAllocated();
diff --git a/dalvik/src/main/java/dalvik/system/VMStack.java b/dalvik/src/main/java/dalvik/system/VMStack.java
index 365613e..b049962 100644
--- a/dalvik/src/main/java/dalvik/system/VMStack.java
+++ b/dalvik/src/main/java/dalvik/system/VMStack.java
@@ -19,8 +19,9 @@ package dalvik.system;
 /**
  * Provides a limited interface to the Dalvik VM stack. This class is mostly
  * used for implementing security checks.
- * 
- * @since Android 1.0
+ *
+ * @deprecated this is an internal Dalvik class that is not appropriate for
+ *      general use. It will be removed from the public API in a future release.
  */
 public final class VMStack {
     /**
diff --git a/dalvik/src/main/java/dalvik/system/Zygote.java b/dalvik/src/main/java/dalvik/system/Zygote.java
index 9d98bb2..13e7561 100644
--- a/dalvik/src/main/java/dalvik/system/Zygote.java
+++ b/dalvik/src/main/java/dalvik/system/Zygote.java
@@ -20,8 +20,9 @@ package dalvik.system;
  * Provides access to the Dalvik "zygote" feature, which allows a VM instance to
  * be partially initialized and then fork()'d from the partially initialized
  * state.
- * 
- * @since Android 1.0
+ *
+ * @deprecated this is an internal Dalvik class that is not appropriate for
+ *      general use. It will be removed from the public API in a future release.
  */
 public class Zygote {
     /*