From a34df8a2ba450b2c2ad83ccbbac30b80e2706bb2 Mon Sep 17 00:00:00 2001
From: Chris Tate <>
Date: Thu, 2 Apr 2009 23:15:58 -0700
Subject: [PATCH] AI 144405: am: CL 144307 am: CL 144306 Fix SDK issue 1716562
 - Broadcast mechanism documentation should be improved.   Original author:
 ctate   Merged from: //branches/cupcake/...   Original author: android-build

Automated import of CL 144405
---
 core/java/android/app/AlarmManager.java       | 11 ++++++++++
 .../android/content/BroadcastReceiver.java    | 22 +++++++++++++------
 core/java/android/content/Context.java        | 13 ++++++-----
 .../guide/topics/manifest/receiver-element.jd | 21 +++++++++++++-----
 4 files changed, 48 insertions(+), 19 deletions(-)

diff --git a/core/java/android/app/AlarmManager.java b/core/java/android/app/AlarmManager.java
index b4c0e314cfb62..53c79352d3f4a 100644
--- a/core/java/android/app/AlarmManager.java
+++ b/core/java/android/app/AlarmManager.java
@@ -29,6 +29,17 @@ import android.os.ServiceManager;
  * if it is not already running.  Registered alarms are retained while the
  * device is asleep (and can optionally wake the device up if they go off
  * during that time), but will be cleared if it is turned off and rebooted.
+ * 
+ * <p>The Alarm Manager holds a CPU wake lock as long as the alarm receiver's
+ * onReceive() method is executing. This guarantees that the phone will not sleep
+ * until you have finished handling the broadcast. Once onReceive() returns, the
+ * Alarm Manager releases this wake lock. This means that the phone will in some
+ * cases sleep as soon as your onReceive() method completes.  If your alarm receiver
+ * called {@link android.content.Context#startService Context.startService()}, it
+ * is possible that the phone will sleep before the requested service is launched.
+ * To prevent this, your BroadcastReceiver and Service will need to implement a
+ * separate wake lock policy to ensure that the phone continues running until the
+ * service becomes available.
  *
  * <p><b>Note: The Alarm Manager is intended for cases where you want to have
  * your application code run at a specific time, even if your application is
diff --git a/core/java/android/content/BroadcastReceiver.java b/core/java/android/content/BroadcastReceiver.java
index a41627aa3ab4d..b391c57df5ee6 100644
--- a/core/java/android/content/BroadcastReceiver.java
+++ b/core/java/android/content/BroadcastReceiver.java
@@ -44,14 +44,14 @@ import android.util.Log;
  * <ul>
  * <li> <b>Normal broadcasts</b> (sent with {@link Context#sendBroadcast(Intent)
  * Context.sendBroadcast}) are completely asynchronous.  All receivers of the
- * broadcast are run, in an undefined order, often at the same time.  This is
- * more efficient, but means that receivers can not use the result or abort
+ * broadcast are run in an undefined order, often at the same time.  This is
+ * more efficient, but means that receivers cannot use the result or abort
  * APIs included here.
  * <li> <b>Ordered broadcasts</b> (sent with {@link Context#sendOrderedBroadcast(Intent, String)
  * Context.sendOrderedBroadcast}) are delivered to one receiver at a time.
  * As each receiver executes in turn, it can propagate a result to the next
  * receiver, or it can completely abort the broadcast so that it won't be passed
- * to other receivers.  The order receivers runs in can be controlled with the
+ * to other receivers.  The order receivers run in can be controlled with the
  * {@link android.R.styleable#AndroidManifestIntentFilter_priority
  * android:priority} attribute of the matching intent-filter; receivers with
  * the same priority will be run in an arbitrary order.
@@ -61,8 +61,8 @@ import android.util.Log;
  * situations revert to delivering the broadcast one receiver at a time.  In
  * particular, for receivers that may require the creation of a process, only
  * one will be run at a time to avoid overloading the system with new processes.
- * In this situation, however, the non-ordered semantics hold: these receivers
- * can not return results or abort their broadcast.</p>
+ * In this situation, however, the non-ordered semantics hold: these receivers still
+ * cannot return results or abort their broadcast.</p>
  * 
  * <p>Note that, although the Intent class is used for sending and receiving
  * these broadcasts, the Intent broadcast mechanism here is completely separate
@@ -156,7 +156,7 @@ import android.util.Log;
  * more important processes.
  * 
  * <p>This means that for longer-running operations you will often use
- * an {@link android.app.Service} in conjunction with a BroadcastReceiver to keep
+ * a {@link android.app.Service} in conjunction with a BroadcastReceiver to keep
  * the containing process active for the entire time of your operation.
  */
 public abstract class BroadcastReceiver {
@@ -167,7 +167,7 @@ public abstract class BroadcastReceiver {
      * This method is called when the BroadcastReceiver is receiving an Intent
      * broadcast.  During this time you can use the other methods on
      * BroadcastReceiver to view/modify the current result values.  The function
-     * is normally called from the main thread of its process, so you should
+     * is normally called within the main thread of its process, so you should
      * never perform long-running operations in it (there is a timeout of
      * 10 seconds that the system allows before considering the receiver to
      * be blocked and a candidate to be killed). You cannot launch a popup dialog
@@ -183,6 +183,14 @@ public abstract class BroadcastReceiver {
      * to interact with a service that is already running, you can use
      * {@link #peekService}.
      * 
+     * <p>The Intent filters used in {@link android.content.Context#registerReceiver}
+     * and in application manifests are <em>not</em> guaranteed to be exclusive. They
+     * are hints to the operating system about how to find suitable recipients. It is
+     * possible for senders to force delivery to specific recipients, bypassing filter
+     * resolution.  For this reason, {@link #onReceive(Context, Intent) onReceive()}
+     * implementations should respond only to known actions, ignoring any unexpected
+     * Intents that they may receive.
+     * 
      * @param context The Context in which the receiver is running.
      * @param intent The Intent being received.
      */
diff --git a/core/java/android/content/Context.java b/core/java/android/content/Context.java
index abcc1eaf5a2bd..3d5ed3a87ffcc 100644
--- a/core/java/android/content/Context.java
+++ b/core/java/android/content/Context.java
@@ -738,7 +738,7 @@ public abstract class Context {
     public abstract void removeStickyBroadcast(Intent intent);
 
     /**
-     * Register an BroadcastReceiver to be run in the main activity thread.  The
+     * Register a BroadcastReceiver to be run in the main activity thread.  The
      * <var>receiver</var> will be called with any broadcast Intent that
      * matches <var>filter</var>, in the main application thread.
      *
@@ -762,11 +762,12 @@ public abstract class Context {
      *
      * <p>See {@link BroadcastReceiver} for more information on Intent broadcasts.
      *
-     * <p class="note">Note: this method <em>can not be called from an
-     * {@link BroadcastReceiver} component</em>.  It is okay, however, to use
-     * this method from another BroadcastReceiver that has itself been registered with
-     * {@link #registerReceiver}, since the lifetime of such an BroadcastReceiver
-     * is tied to another object (the one that registered it).</p>
+     * <p class="note">Note: this method <em>cannot be called from a
+     * {@link BroadcastReceiver} component;</em> that is, from a BroadcastReceiver
+     * that is declared in an application's manifest.  It is okay, however, to call
+     * this method from another BroadcastReceiver that has itself been registered
+     * at run time with {@link #registerReceiver}, since the lifetime of such a
+     * registered BroadcastReceiver is tied to the object that registered it.</p>
      *
      * @param receiver The BroadcastReceiver to handle the broadcast.
      * @param filter Selects the Intent broadcasts to be received.
diff --git a/docs/html/guide/topics/manifest/receiver-element.jd b/docs/html/guide/topics/manifest/receiver-element.jd
index 777d016b5da8d..8df6273bbf990 100644
--- a/docs/html/guide/topics/manifest/receiver-element.jd
+++ b/docs/html/guide/topics/manifest/receiver-element.jd
@@ -17,7 +17,7 @@ page.title=&lt;receiver&gt;
 <dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code></dd>
 
 <dt>can contain:</dt>
-<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filer&gt;</a></code>
+<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code>
 <br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data&gt;</a></code></dd>
 
 <dt>description:</dt>
@@ -47,10 +47,16 @@ The <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt
 <code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all 
 application components, including broadcast receivers.  The 
 <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> and
-{@code &lt;receiver&gt;} attributes must both be "{@code true}" for 
-the broadcast receiver to be enabled.  If either is "{@code false}", it is
-disabled; it cannot be instantiated.
-</p></dd>
+{@code &lt;receiver&gt;} elements must both set {@code android:enabled} equal to
+"{@code true}" for the broadcast receiver to be enabled.  If either is "{@code false}",
+the receiver is disabled and cannot be instantiated.
+</p>
+
+<p>
+The default value depends on whether the broadcast receiver contains intent filters.
+If any intent filters are specified, the default value is "{@code true}".  If no
+filters are specified, the default value is "{@code false}".
+</dd>
 
 <dt><a name="exported"></a>{@code android:exported}</dt>
 <dd>Whether or not the broadcast receiver can receive messages from sources 
@@ -117,9 +123,12 @@ it can also be set as a raw string.
 {@link android.content.BroadcastReceiver}.  This should be a fully qualified 
 class name (such as, "{@code com.example.project.ReportReceiver}").  However, 
 as a shorthand, if the first character of the name is a period (for example, 
-"{@code . ReportReceiver}"), it is appended to the package name specified in 
+"{@code .ReportReceiver}"), it is appended to the package name specified in 
 the <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code> element.  
 
+<p>The {@link android.content.BroadcastReceiver} subclass can be a static inner
+class, although it cannot be an ordinary (non-static) inner class.
+
 <p>
 There is no default.  The name must be specified.
 </p></dd>