From 7025d8e4b96f14a92f9bb20902732f43d1c93e7b Mon Sep 17 00:00:00 2001 From: Dianne Hackborn Date: Mon, 1 Nov 2010 09:49:37 -0700 Subject: [PATCH] Fix issue #3152415: Various confusions in docs about Application Change-Id: Ie1b480ed7a47a3eb6ffff76bef0dcd7b2b845e83 --- core/java/android/app/Application.java | 18 ++++++--- .../guide/topics/resources/providing-resources.jd | 5 +-- docs/html/resources/faq/framework.jd | 43 ++++++++-------------- 3 files changed, 30 insertions(+), 36 deletions(-) diff --git a/core/java/android/app/Application.java b/core/java/android/app/Application.java index 45ce86015b88..b9ac84838e65 100644 --- a/core/java/android/app/Application.java +++ b/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. + * + *

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.

*/ 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 - * objects running and the process will exit. 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. - * 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() { } diff --git a/docs/html/guide/topics/resources/providing-resources.jd b/docs/html/guide/topics/resources/providing-resources.jd index 1d6ab259c355..d86859905e86 100644 --- a/docs/html/guide/topics/resources/providing-resources.jd +++ b/docs/html/guide/topics/resources/providing-resources.jd @@ -129,9 +129,8 @@ Menu. See Menu Resource. raw/ -

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

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.filename}.

However, if you need access to original file names and file hierarchy, you might consider saving some resources in the {@code diff --git a/docs/html/resources/faq/framework.jd b/docs/html/resources/faq/framework.jd index f4b8db086222..4a7a3fc20e66 100644 --- a/docs/html/resources/faq/framework.jd +++ b/docs/html/resources/faq/framework.jd @@ -68,12 +68,17 @@ Preferences storage mechanism.

For sharing complex non-persistent user-defined objects for short duration, the following approaches are recommended:

-

The android.app.Application class

-

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.

+

Singleton class

+

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 getInstance() +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.

A public static field/method

An alternate way to make data accessible across Activities/Services is to use public static @@ -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.

-

A Singleton class

-

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.

-

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

-

-

Persistent Objects

Even while an application appears to continue running, the system @@ -146,15 +139,11 @@ call.

If an Activity starts a remote service, is there any way for the Service to pass a message back to the Activity?

-

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.

- -

The sample code for remote service callbacks is given in ApiDemos/RemoteService

- +

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