Merge "SDK only: now that support lib is in SDK, we can link to it." into ics-mr1

Author: Dianne Hackborn

core/java/android/app/Fragment.java

@@ -181,7 +181,8 @@ public FragmentState[] newArray(int size) {
  *
  * While the Fragment API was introduced in
  * {@link android.os.Build.VERSION_CODES#HONEYCOMB}, a version of the API
- * is also available for use on older platforms.  See the blog post
+ * at is also available for use on older platforms through
+ * {@link android.support.v4.app.FragmentActivity}.  See the blog post
  * <a href="http://android-developers.blogspot.com/2011/03/fragments-for-all.html">
  * Fragments For All</a> for more details.
  *

core/java/android/app/FragmentManager.java

@@ -51,6 +51,13 @@
  * <p>For more information about using fragments, read the
  * <a href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a> developer guide.</p>
  * </div>
+ *
+ * While the FragmentManager API was introduced in
+ * {@link android.os.Build.VERSION_CODES#HONEYCOMB}, a version of the API
+ * at is also available for use on older platforms through
+ * {@link android.support.v4.app.FragmentActivity}.  See the blog post
+ * <a href="http://android-developers.blogspot.com/2011/03/fragments-for-all.html">
+ * Fragments For All</a> for more details.
  */
 public abstract class FragmentManager {
     /**

core/java/android/app/LoaderManager.java

@@ -36,7 +36,8 @@
  *
  * While the LoaderManager API was introduced in
  * {@link android.os.Build.VERSION_CODES#HONEYCOMB}, a version of the API
- * is also available for use on older platforms.  See the blog post
+ * at is also available for use on older platforms through
+ * {@link android.support.v4.app.FragmentActivity}.  See the blog post
  * <a href="http://android-developers.blogspot.com/2011/03/fragments-for-all.html">
  * Fragments For All</a> for more details.
  *

core/java/android/content/BroadcastReceiver.java

@@ -28,11 +28,21 @@
 
 /**
  * Base class for code that will receive intents sent by sendBroadcast().
- * You can either dynamically register an instance of this class with
+ *
+ * <p>If you don't need to send broadcasts across applications, consider using
+ * this class with {@link android.support.v4.content.LocalBroadcastManager} instead
+ * of the more general facilities described below.  This will give you a much
+ * more efficient implementation (no cross-process communication needed) and allow
+ * you to avoid thinking about any security issues related to other applications
+ * being able to receive or send your broadcasts.
+ *
+ * <p>You can either dynamically register an instance of this class with
  * {@link Context#registerReceiver Context.registerReceiver()}
  * or statically publish an implementation through the
  * {@link android.R.styleable#AndroidManifestReceiver &lt;receiver&gt;}
- * tag in your <code>AndroidManifest.xml</code>. <em><strong>Note:</strong></em>
+ * tag in your <code>AndroidManifest.xml</code>.
+ * 
+ * <p><em><strong>Note:</strong></em>
  * &nbsp;&nbsp;&nbsp;If registering a receiver in your
  * {@link android.app.Activity#onResume() Activity.onResume()}
  * implementation, you should unregister it in 
@@ -86,8 +96,8 @@
  * 
  * <p>Topics covered here:
  * <ol>
+ * <li><a href="#Security">Security</a>
  * <li><a href="#ReceiverLifecycle">Receiver Lifecycle</a>
- * <li><a href="#Permissions">Permissions</a>
  * <li><a href="#ProcessLifecycle">Process Lifecycle</a>
  * </ol>
  *
@@ -98,32 +108,39 @@
  * developer guide.</p>
  * </div>
  *
- * <a name="ReceiverLifecycle"></a>
- * <h3>Receiver Lifecycle</h3>
- * 
- * <p>A BroadcastReceiver object is only valid for the duration of the call
- * to {@link #onReceive}.  Once your code returns from this function,
- * the system considers the object to be finished and no longer active.
- * 
- * <p>This has important repercussions to what you can do in an
- * {@link #onReceive} implementation: anything that requires asynchronous
- * operation is not available, because you will need to return from the
- * function to handle the asynchronous operation, but at that point the
- * BroadcastReceiver is no longer active and thus the system is free to kill
- * its process before the asynchronous operation completes.
- * 
- * <p>In particular, you may <i>not</i> show a dialog or bind to a service from
- * within a BroadcastReceiver.  For the former, you should instead use the
- * {@link android.app.NotificationManager} API.  For the latter, you can
- * use {@link android.content.Context#startService Context.startService()} to
- * send a command to the service.
- * 
- * <a name="Permissions"></a>
- * <h3>Permissions</h3>
- * 
+ * <a name="Security"></a>
+ * <h3>Security</h3>
+ *
+ * <p>Receivers used with the {@link Context} APIs are by their nature a
+ * cross-application facility, so you must consider how other applications
+ * may be able to abuse your use of them.  Some things to consider are:
+ *
+ * <ul>
+ * <li><p>The Intent namespace is global.  Make sure that Intent action names and
+ * other strings are written in a namespace you own, or else you may inadvertantly
+ * conflict with other applications.
+ * <li><p>When you use {@link Context#registerReceiver(BroadcastReceiver, IntentFilter)},
+ * <em>any</em> application may send broadcasts to that registered receiver.  You can
+ * control who can send broadcasts to it through permissions described below.
+ * <li><p>When you publish a receiver in your application's manifest and specify
+ * intent-filters for it, any other application can send broadcasts to it regardless
+ * of the filters you specify.  To prevent others from sending to it, make it
+ * unavailable to them with <code>android:exported="false"</code>.
+ * <li><p>When you use {@link Context#sendBroadcast(Intent)} or related methods,
+ * normally any other application can receive these broadcasts.  You can control who
+ * can receive such broadcasts through permissions described below.  Alternatively,
+ * starting with {@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH}, you
+ * can also safely restrict the broadcast to a single application with
+ * {@link Intent#setPackage(String) Intent.setPackage}
+ * </ul>
+ *
+ * <p>None of these issues exist when using
+ * {@link android.support.v4.content.LocalBroadcastManager}, since intents
+ * broadcast it never go outside of the current process.
+ *
  * <p>Access permissions can be enforced by either the sender or receiver
- * of an Intent.
- * 
+ * of a broadcast.
+ *
  * <p>To enforce a permission when sending, you supply a non-null
  * <var>permission</var> argument to
  * {@link Context#sendBroadcast(Intent, String)} or
@@ -133,7 +150,7 @@
  * {@link android.R.styleable#AndroidManifestUsesPermission &lt;uses-permission&gt;}
  * tag in their <code>AndroidManifest.xml</code>) will be able to receive
  * the broadcast.
- * 
+ *
  * <p>To enforce a permission when receiving, you supply a non-null
  * <var>permission</var> when registering your receiver -- either when calling
  * {@link Context#registerReceiver(BroadcastReceiver, IntentFilter, String, android.os.Handler)}
@@ -144,10 +161,30 @@
  * {@link android.R.styleable#AndroidManifestUsesPermission &lt;uses-permission&gt;}
  * tag in their <code>AndroidManifest.xml</code>) will be able to send an
  * Intent to the receiver.
- * 
+ *
  * <p>See the <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>
  * document for more information on permissions and security in general.
+ *
+ * <a name="ReceiverLifecycle"></a>
+ * <h3>Receiver Lifecycle</h3>
+ * 
+ * <p>A BroadcastReceiver object is only valid for the duration of the call
+ * to {@link #onReceive}.  Once your code returns from this function,
+ * the system considers the object to be finished and no longer active.
+ * 
+ * <p>This has important repercussions to what you can do in an
+ * {@link #onReceive} implementation: anything that requires asynchronous
+ * operation is not available, because you will need to return from the
+ * function to handle the asynchronous operation, but at that point the
+ * BroadcastReceiver is no longer active and thus the system is free to kill
+ * its process before the asynchronous operation completes.
  * 
+ * <p>In particular, you may <i>not</i> show a dialog or bind to a service from
+ * within a BroadcastReceiver.  For the former, you should instead use the
+ * {@link android.app.NotificationManager} API.  For the latter, you can
+ * use {@link android.content.Context#startService Context.startService()} to
+ * send a command to the service.
+ *
  * <a name="ProcessLifecycle"></a>
  * <h3>Process Lifecycle</h3>
  * 

core/java/android/content/Loader.java

@@ -58,6 +58,13 @@ public class Loader<D> {
     boolean mReset = true;
     boolean mContentChanged = false;
 
+    /**
+     * An implementation of a ContentObserver that takes care of connecting
+     * it to the Loader to have the loader re-load its data when the observer
+     * is told it has changed.  You do not normally need to use this yourself;
+     * it is used for you by {@link CursorLoader} to take care of executing
+     * an update when the cursor's backing data changes.
+     */
     public final class ForceLoadContentObserver extends ContentObserver {
         public ForceLoadContentObserver() {
             super(new Handler());
@@ -74,6 +81,14 @@ public void onChange(boolean selfChange) {
         }
     }
 
+    /**
+     * Interface that is implemented to discover when a Loader has finished
+     * loading its data.  You do not normally need to implement this yourself;
+     * it is used in the implementation of {@link android.app.LoaderManager}
+     * to find out when a Loader it is managing has completed so that this can
+     * be reported to its client.  This interface should only be used if a
+     * Loader is not being used in conjunction with LoaderManager.
+     */
     public interface OnLoadCompleteListener<D> {
         /**
          * Called on the thread that created the Loader when the load is complete.