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

 * 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 {

    }

    /**

     * Called when the application is stopping.  There are no more application

     * objects running and the process will exit.  <em>Note: never depend on

     * this method being called; in many cases an unneeded application process

     * will simply be killed by the kernel without executing any application

     * code.</em>

     * If you override this method, be sure to call super.onTerminate().

     * This method is for use in emulated process environments.  It will

     * never be called on a production Android device, where processes are

     * removed by simply killing them; no user code (including this callback)

     * is executed when doing so.

     */

    public void onTerminate() {

    }

  <tr>

    <td><code>raw/</code></td>

    <td><p>Arbitrary files to save in their raw form. Files in here are not compressed by the

system. To open these resources with a raw {@link java.io.InputStream}, call {@link

android.content.res.Resources#openRawResource(int)

    <td><p>Arbitrary files to save in their raw form. To open these resources with a raw

{@link java.io.InputStream}, call {@link 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

<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>

  <p>The android.app.Application is a base class for those who need to

maintain global application state. It can be accessed via

getApplication() from any Activity or Service. It has a couple of

life-cycle methods and will be instantiated by Android automatically if

your register it in AndroidManifest.xml.</p>

  <h4>Singleton class</h4>

  <p>You can take advantage of the fact that your application

components run in the same process through the use of a singleton.

This is a class that is designed to have only one instance.  It

has a static method with a name such as <code>getInstance()</code>

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>

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

<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

clients to callback into the clients. The 

{@link android.os.RemoteCallbackList RemoteCallbackList} class provides methods to

register and unregister clients with the service, and send and receive

messages.</p>

<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>

<p>See the {@link android.app.Service} documentation's for examples of

how clients can interact with a service.  You can take advantage of the

fact that your components run in the same process to greatly simplify

service interaction from the generic remote case, as shown by the "Local

Service Sample".  In some cases techniques like singletons may also make sense.

<a name="6" id="6"></a>