Update from API review.

Change-Id: I16b1c566f91167aac9615ac59dd297a154c828ea

11 files changed, 79 insertions, 84 deletions

diff --git a/api/current.xml b/api/current.xml
index 1b3b3d9..150f8ed 100644
--- a/api/current.xml
+++ b/api/current.xml
@@ -177,17 +177,6 @@
  visibility="public"
 >
 </field>
-<field name="BIND_WALLPAPER"
- type="java.lang.String"
- transient="false"
- volatile="false"
- value="&quot;android.permission.BIND_WALLPAPER&quot;"
- static="true"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
 <field name="BLUETOOTH"
  type="java.lang.String"
  transient="false"
@@ -42811,25 +42800,6 @@
 >
 </field>
 </class>
-<interface name="RegisteredServicesCacheListener"
- abstract="true"
- static="false"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-<method name="onRegisteredServicesCacheChanged"
- return="void"
- abstract="true"
- native="false"
- synchronized="false"
- static="false"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-</method>
-</interface>
 <class name="ResolveInfo"
  extends="java.lang.Object"
  abstract="false"
@@ -122193,37 +122163,6 @@
 </implements>
 </interface>
 </package>
-<package name="android.service.wallpaper"
->
-<class name="WallpaperSettingsActivity"
- extends="android.preference.PreferenceActivity"
- abstract="false"
- static="false"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-<constructor name="WallpaperSettingsActivity"
- type="android.service.wallpaper.WallpaperSettingsActivity"
- static="false"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-</constructor>
-<field name="EXTRA_PREVIEW_MODE"
- type="java.lang.String"
- transient="false"
- volatile="false"
- value="&quot;android.service.wallpaper.PREVIEW_MODE&quot;"
- static="true"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-</class>
-</package>
 <package name="android.speech"
 >
 <class name="RecognizerIntent"
@@ -155177,7 +155116,20 @@
  visibility="public"
 >
 </method>
-<method name="setOnTop"
+<method name="setZOrderMediaOverlay"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="isMediaOverlay" type="boolean">
+</parameter>
+</method>
+<method name="setZOrderOnTop"
  return="void"
  abstract="false"
  native="false"
@@ -157342,19 +157294,6 @@
  visibility="public"
 >
 </method>
-<method name="onCloseSystemDialogs"
- return="void"
- abstract="false"
- native="false"
- synchronized="false"
- static="false"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-<parameter name="reason" type="java.lang.String">
-</parameter>
-</method>
 <method name="onCreateContextMenu"
  return="void"
  abstract="false"
diff --git a/core/java/android/app/Service.java b/core/java/android/app/Service.java
index a32ad85..30e1712 100644
--- a/core/java/android/app/Service.java
+++ b/core/java/android/app/Service.java
@@ -158,9 +158,9 @@ import java.io.PrintWriter;
  * happens, the system will later try to restart the service.  An important
  * consequence of this is that if you implement {@link #onStartCommand onStartCommand()}
  * to schedule work to be done asynchronously or in another thread, then you
- * may want to write information about that work into persistent storage
- * during the onStartCommand() call so that it does not get lost if the service later
- * gets killed.
+ * may want to use {@link #START_FLAG_REDELIVERY} to have the system
+ * re-deliver an Intent for you so that it does not get lost if your service
+ * is killed while processing it.
  * 
  * <p>Other application components running in the same process as the service
  * (such as an {@link android.app.Activity}) can, of course, increase the
@@ -230,7 +230,10 @@ public abstract class Service extends ContextWrapper implements ComponentCallbac
      * {@link #onStartCommand}), and there are no new start intents to
      * deliver to it, then take the service out of the started state and
      * don't recreate until a future explicit call to
-     * {@link Context#startService Context.startService(Intent)}.
+     * {@link Context#startService Context.startService(Intent)}.  The
+     * service will not receive a {@link #onStartCommand(Intent, int, int)}
+     * call with a null Intent because it will not be re-started if there
+     * are no pending Intents to deliver.
      * 
      * <p>This mode makes sense for things that want to do some work as a
      * result of being started, but can be stopped when under memory pressure
@@ -252,7 +255,11 @@ public abstract class Service extends ContextWrapper implements ComponentCallbac
      * and the last delivered Intent re-delivered to it again via
      * {@link #onStartCommand}.  This Intent will remain scheduled for
      * redelivery until the service calls {@link #stopSelf(int)} with the
-     * start ID provided to {@link #onStartCommand}.
+     * start ID provided to {@link #onStartCommand}.  The
+     * service will not receive a {@link #onStartCommand(Intent, int, int)}
+     * call with a null Intent because it will will only be re-started if
+     * it is not finished processing all Intents sent to it (and any such
+     * pending events will be delivered at the point of restart).
      */
     public static final int START_REDELIVER_INTENT = 3;
     
@@ -402,6 +409,13 @@ public abstract class Service extends ContextWrapper implements ComponentCallbac
      * safely avoid stopping if there is a start request from a client that you 
      * haven't yet seen in {@link #onStart}. 
      * 
+     * <p><em>Be careful about ordering of your calls to this function.</em>.
+     * If you call this function with the most-recently received ID before
+     * you have called it for previously received IDs, the service will be
+     * immediately stopped anyway.  If you may end up processing IDs out
+     * of order (such as by dispatching them on separate threads), then you
+     * are responsible for stopping them in the same order you received them.</p>
+     * 
      * @param startId The most recent start identifier received in {@link 
      *                #onStart}.
      * @return Returns true if the startId matches the last start request
@@ -423,7 +437,15 @@ public abstract class Service extends ContextWrapper implements ComponentCallbac
     
     /**
      * @deprecated This is a now a no-op, use
-     * {@link #startForeground(int, Notification)} instead.
+     * {@link #startForeground(int, Notification)} instead.  This method
+     * has been turned into a no-op rather than simply being deprecated
+     * because analysis of numerous poorly behaving devices has shown that
+     * increasingly often the trouble is being caused in part by applications
+     * that are abusing it.  Thus, given a choice between introducing
+     * problems in existing applications using this API (by allowing them to
+     * be killed when they would like to avoid it), vs allowing the performance
+     * of the entire system to be decreased, this method was deemed less
+     * important.
      */
     @Deprecated
     public final void setForeground(boolean isForeground) {
diff --git a/core/java/android/content/pm/RegisteredServicesCacheListener.java b/core/java/android/content/pm/RegisteredServicesCacheListener.java
index 8cf15e4..c92c86e 100644
--- a/core/java/android/content/pm/RegisteredServicesCacheListener.java
+++ b/core/java/android/content/pm/RegisteredServicesCacheListener.java
@@ -2,6 +2,7 @@ package android.content.pm;
 
 /**
  * Listener for changes to the set of registered services managed by a RegisteredServicesCache.
+ * @hide
  */
 public interface RegisteredServicesCacheListener {
     /**
diff --git a/core/java/android/provider/Contacts.java b/core/java/android/provider/Contacts.java
index d4d3a7e..1a38166 100644
--- a/core/java/android/provider/Contacts.java
+++ b/core/java/android/provider/Contacts.java
@@ -668,12 +668,14 @@ public class Contacts {
 
             /**
              * The directory twig for this sub-table
+             * @deprecated see {@link android.provider.ContactsContract}
              */
             @Deprecated
             public static final String CONTENT_DIRECTORY = "phones";
 
             /**
              * The default sort order for this table
+             * @deprecated see {@link android.provider.ContactsContract}
              */
             @Deprecated
             public static final String DEFAULT_SORT_ORDER = "number ASC";
@@ -1925,6 +1927,9 @@ public class Contacts {
      */
     @Deprecated
     public static final class Intents {
+        /**
+         * @deprecated see {@link android.provider.ContactsContract}
+         */
         @Deprecated
         public Intents() {
         }
diff --git a/core/java/android/service/wallpaper/WallpaperSettingsActivity.java b/core/java/android/service/wallpaper/WallpaperSettingsActivity.java
index 501947d..cde5ab2 100644
--- a/core/java/android/service/wallpaper/WallpaperSettingsActivity.java
+++ b/core/java/android/service/wallpaper/WallpaperSettingsActivity.java
@@ -24,6 +24,7 @@ import android.preference.PreferenceActivity;
  * Base class for activities that will be used to configure the settings of
  * a wallpaper.  You should derive from this class to allow it to select the
  * proper theme of the activity depending on how it is being used.
+ * @hide Live Wallpaper
  */
 public class WallpaperSettingsActivity extends PreferenceActivity {
     /**
diff --git a/core/java/android/view/SurfaceView.java b/core/java/android/view/SurfaceView.java
index 356f55a..ca5e1de 100644
--- a/core/java/android/view/SurfaceView.java
+++ b/core/java/android/view/SurfaceView.java
@@ -289,6 +289,23 @@ public class SurfaceView extends View {
     }
 
     /**
+     * Control whether the surface view's surface is placed on top of another
+     * regular surface view in the window (but still behind the window itself).
+     * This is typically used to place overlays on top of an underlying media
+     * surface view.
+     * 
+     * <p>Note that this must be set before the surface view's containing
+     * window is attached to the window manager.
+     * 
+     * <p>Calling this overrides any previous call to {@link #setZOrderOnTop}.
+     */
+    public void setZOrderMediaOverlay(boolean isMediaOverlay) {
+        mWindowType = isMediaOverlay
+                ? WindowManager.LayoutParams.TYPE_APPLICATION_MEDIA_OVERLAY
+                : WindowManager.LayoutParams.TYPE_APPLICATION_MEDIA;
+    }
+    
+    /**
      * Control whether the surface view's surface is placed on top of its
      * window.  Normally it is placed behind the window, to allow it to
      * (for the most part) appear to composite with the views in the
@@ -298,8 +315,10 @@ public class SurfaceView extends View {
      * 
      * <p>Note that this must be set before the surface view's containing
      * window is attached to the window manager.
+     * 
+     * <p>Calling this overrides any previous call to {@link #setZOrderMediaOverlay}.
      */
-    public void setOnTop(boolean onTop) {
+    public void setZOrderOnTop(boolean onTop) {
         mWindowType = onTop ? WindowManager.LayoutParams.TYPE_APPLICATION_PANEL
                 : WindowManager.LayoutParams.TYPE_APPLICATION_MEDIA;
     }
diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java
index 048f857..7d821b5 100644
--- a/core/java/android/view/View.java
+++ b/core/java/android/view/View.java
@@ -8348,6 +8348,7 @@ public class View implements Drawable.Callback, KeyEvent.Callback, Accessibility
     /**
      * This needs to be a better API (NOT ON VIEW) before it is exposed.  If
      * it is ever exposed at all.
+     * @hide
      */
     public void onCloseSystemDialogs(String reason) {
     }
diff --git a/core/res/AndroidManifest.xml b/core/res/AndroidManifest.xml
index 47807c4..d0621e7 100644
--- a/core/res/AndroidManifest.xml
+++ b/core/res/AndroidManifest.xml
@@ -912,7 +912,8 @@
         android:protectionLevel="signature" />
 
     <!-- Must be required by wallpaper services, to ensure that only the
-         system can bind to them. -->
+         system can bind to them.
+         @hide Live Wallpaper -->
     <permission android:name="android.permission.BIND_WALLPAPER"
         android:label="@string/permlab_bindWallpaper"
         android:description="@string/permdesc_bindWallpaper"
diff --git a/graphics/java/android/graphics/drawable/BitmapDrawable.java b/graphics/java/android/graphics/drawable/BitmapDrawable.java
index f42788e..29e14d2 100644
--- a/graphics/java/android/graphics/drawable/BitmapDrawable.java
+++ b/graphics/java/android/graphics/drawable/BitmapDrawable.java
@@ -115,6 +115,7 @@ public class BitmapDrawable extends Drawable {
      * @deprecated Use {@link #BitmapDrawable(Resources, String)} to ensure
      * that the drawable has correctly set its target density.
      */
+    @Deprecated
     public BitmapDrawable(String filepath) {
         this(new BitmapState(BitmapFactory.decodeFile(filepath)), null);
         if (mBitmap == null) {
@@ -138,6 +139,7 @@ public class BitmapDrawable extends Drawable {
      * @deprecated Use {@link #BitmapDrawable(Resources, java.io.InputStream)} to ensure
      * that the drawable has correctly set its target density.
      */
+    @Deprecated
     public BitmapDrawable(java.io.InputStream is) {
         this(new BitmapState(BitmapFactory.decodeStream(is)), null);
         if (mBitmap == null) {
diff --git a/media/java/android/media/ExifInterface.java b/media/java/android/media/ExifInterface.java
index 29409ab..6cd4b92 100644
--- a/media/java/android/media/ExifInterface.java
+++ b/media/java/android/media/ExifInterface.java
@@ -92,7 +92,7 @@ public class ExifInterface {
     /**
      * Returns the integer value of the specified tag. If there is no such tag
      * in the JPEG file or the value cannot be parsed as integer, return
-     * @{code defaultValue}.
+     * <var>defaultValue</var>.
      *
      * @param tag the name of the tag.
      * @param defaultValue the value to return if the tag is not available.
diff --git a/telephony/java/android/telephony/NeighboringCellInfo.java b/telephony/java/android/telephony/NeighboringCellInfo.java
index d698169..1d69761 100644
--- a/telephony/java/android/telephony/NeighboringCellInfo.java
+++ b/telephony/java/android/telephony/NeighboringCellInfo.java
@@ -75,6 +75,7 @@ public class NeighboringCellInfo implements Parcelable
      * the radio network type at that moment. Its constructor needs radio network
      * type.
      */
+    @Deprecated
     public NeighboringCellInfo() {
         mRssi = UNKNOWN_RSSI;
         mLac = UNKNOWN_CID;
@@ -91,6 +92,7 @@ public class NeighboringCellInfo implements Parcelable
      * the radio network type at that moment. Its constructor needs radio network
      * type.
      */
+    @Deprecated
     public NeighboringCellInfo(int rssi, int cid) {
         mRssi = rssi;
         mCid = cid;
@@ -228,6 +230,7 @@ public class NeighboringCellInfo implements Parcelable
      * the radio network type at that moment. It shouldn't be changed after
      * creation.
      */
+    @Deprecated
     public void setCid(int cid) {
         mCid = cid;
     }
@@ -240,6 +243,7 @@ public class NeighboringCellInfo implements Parcelable
      * the radio network type at that moment. It shouldn't be changed after
      * creation.
      */
+    @Deprecated
     public void setRssi(int rssi) {
         mRssi = rssi;
     }