Merge "Fix issue #3152415: Various confusions in docs about Application" into gingerbread

core/java/android/app/Application.java

@@ -27,6 +27,14 @@ import android.content.res.Configuration;
  * AndroidManifest.xml's <application> tag, which will cause that class
  * to be instantiated for you when the process for your application/package is
  * created.
+ * 
+ * <p class="note">There is normally no need to subclass Application.  In
+ * most situation, static singletons can provide the same functionality in a
+ * more modular way.  If your singleton needs a global context (for example
+ * to register broadcast receivers), the function to retrieve it can be
+ * given a {@link android.content.Context} which internally uses
+ * {@link android.content.Context#getApplicationContext() Context.getApplicationContext()}
+ * when first constructing the singleton.</p>
  */
 public class Application extends ContextWrapper implements ComponentCallbacks {
     
@@ -46,12 +54,10 @@ public class Application extends ContextWrapper implements ComponentCallbacks {
     }
 
     /**
-     * Called when the application is stopping.  There are no more application
+     * This method is for use in emulated process environments.  It will
-     * objects running and the process will exit.  <em>Note: never depend on
+     * never be called on a production Android device, where processes are
-     * this method being called; in many cases an unneeded application process
+     * removed by simply killing them; no user code (including this callback)
-     * will simply be killed by the kernel without executing any application
+     * is executed when doing so.
-     * code.</em>
-     * If you override this method, be sure to call super.onTerminate().
      */
     public void onTerminate() {
     }

docs/html/guide/topics/resources/providing-resources.jd

@@ -129,9 +129,8 @@ Menu. See <a href="menu-resource.html">Menu Resource</a>.</td>
 
   <tr>
     <td><code>raw/</code></td>
-    <td><p>Arbitrary files to save in their raw form. Files in here are not compressed by the
+    <td><p>Arbitrary files to save in their raw form. To open these resources with a raw
-system. To open these resources with a raw {@link java.io.InputStream}, call {@link
+{@link java.io.InputStream}, call {@link android.content.res.Resources#openRawResource(int)
-android.content.res.Resources#openRawResource(int)
 Resources.openRawResource()} with the resource ID, which is {@code R.raw.<em>filename</em>}.</p>
       <p>However, if you need access to original file names and file hierarchy, you might consider
 saving some resources in the {@code

docs/html/resources/faq/framework.jd

@@ -68,12 +68,17 @@ Preferences</a> storage mechanism.</p>
 <p>For sharing complex non-persistent user-defined objects for short
 duration, the following approaches are recommended:
 </p>
-  <h4>The android.app.Application class</h4>
+  <h4>Singleton class</h4>
-  <p>The android.app.Application is a base class for those who need to
+  <p>You can take advantage of the fact that your application
-maintain global application state. It can be accessed via
+components run in the same process through the use of a singleton.
-getApplication() from any Activity or Service. It has a couple of
+This is a class that is designed to have only one instance.  It
-life-cycle methods and will be instantiated by Android automatically if
+has a static method with a name such as <code>getInstance()</code>
-your register it in AndroidManifest.xml.</p>
+that returns the instance; the first time this method is called,
+it creates the global instance.  Because all callers get the same
+instance, they can use this as a point of interaction.  For
+example activity A may retrieve the instance and call setValue(3);
+later activity B may retrieve the instance and call getValue() to
+retrieve the last set value.</p>
 
   <h4>A public static field/method</h4>
   <p>An alternate way to make data accessible across Activities/Services is to use <em>public static</em>
@@ -90,18 +95,6 @@ Long based on a counter or time stamp) to the recipient activity via
 intent extras. The recipient activity retrieves the object using this
 key.</p>
 
-  <h4>A Singleton class</h4>
-  <p>There are advantages to using a static Singleton, such as you can
-refer to them without casting getApplication() to an
-application-specific class, or going to the trouble of hanging an
-interface on all your Application subclasses so that your various
-modules can refer to that interface instead. </p>
-<p>But, the life cycle of a static is not well under your control; so
-to abide by the life-cycle model, the application class should initiate and
-tear down these static objects in the onCreate() and onTerminate() methods
-of the Application Class</p>
-</p>
-
 <h3>Persistent Objects</h3>
 
 <p>Even while an application appears to continue running, the system
@@ -146,15 +139,11 @@ call.</p>
 <h2>If an Activity starts a remote service, is there any way for the
 Service to pass a message back to the Activity?</h2>
 
-<p>The remote service can define a callback interface and register it with the
+<p>See the {@link android.app.Service} documentation's for examples of
-clients to callback into the clients. The 
+how clients can interact with a service.  You can take advantage of the
-{@link android.os.RemoteCallbackList RemoteCallbackList} class provides methods to
+fact that your components run in the same process to greatly simplify
-register and unregister clients with the service, and send and receive
+service interaction from the generic remote case, as shown by the "Local
-messages.</p>
+Service Sample".  In some cases techniques like singletons may also make sense.
-
-<p>The sample code for remote service callbacks is given in <a
-href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/RemoteService.html">ApiDemos/RemoteService</a></p>
-
 
 
 <a name="6" id="6"></a>