1 page.title=Application Fundamentals
7 <h2>In this document</h2>
9 <li><a href="#appcomp">Application Components</a>
11 <li><a href="#actcomp">Activating components: intents</a></li>
12 <li><a href="#endcomp">Shutting down components</a></li>
13 <li><a href="#manfile">The manifest file</a></li>
14 <li><a href="#ifilters">Intent filters</a></li>
16 <li><a href="#acttask">Activities and Tasks</a>
18 <li><a href="#afftask">Affinities and new tasks</a></li>
19 <li><a href="#lmodes">Launch modes</a></li>
20 <li><a href="#clearstack">Clearing the stack</a></li>
21 <li><a href="#starttask">Starting tasks</a></li>
23 <li><a href="#procthread">Processes and Threads</a>
25 <li><a href="#procs">Processes</a></li>
26 <li><a href="#threads">Threads</a></li>
27 <li><a href="#rpc">Remote procedure calls</a></li>
28 <li><a href="#tsafe">Thread-safe methods</a></li>
30 <li><a href="#lcycles">Component Lifecycles</a>
32 <li><a href="#actlife">Activity lifecycle</a></li>
33 <li><a href="#servlife">Service lifecycle</a></li>
34 <li><a href="#broadlife">Broadcast receiver lifecycle</a></li>
35 <li><a href="#proclife">Processes and lifecycles</a></li>
41 <li>{@link android.app.Activity}</li>
42 <li>{@link android.app.Service}</li>
43 <li>{@link android.content.BroadcastReceiver}</li>
44 <li>{@link android.content.ContentProvider}</li>
45 <li>{@link android.content.Intent}</li>
52 Android applications are written in the Java programming language.
53 The compiled Java code — along with any data and resource
54 files required by the application — is bundled by the
55 <a href="{@docRoot}guide/developing/tools/aapt.html"><code>aapt</code>
56 tool</a> into an <i>Android package</i>, an archive file
57 marked by an {@code .apk} suffix. This file is the vehicle
58 for distributing the application and installing it on mobile devices;
59 it's the file users download to their devices. All the code in a
60 single {@code .apk} file is considered to be one <i>application</i>.
64 In many ways, each Android application lives in its own world:
68 <li>By default, every application runs in its own Linux process.
69 Android starts the process when any of the application's code needs to be
70 executed, and shuts down the process when it's no longer needed and system
71 resources are required by other applications.</li>
73 <li>Each process has its own virtual machine (VM), so application code
74 runs in isolation from the code of all other applications.</li>
76 <li>By default, each application is assigned a unique Linux user ID.
77 Permissions are set so that the application's files are visible only to
78 that user and only to the application itself — although there are ways
79 to export them to other applications as well.</li>
83 It's possible to arrange for two applications to share the same user ID,
84 in which case they will be able to see each other's files. To conserve
85 system resources, applications with the same ID can also arrange to run
86 in the same Linux process, sharing the same VM.
90 <h2 id="appcomp">Application Components</h2>
93 A central feature of Android is that one application can make use of elements
94 of other applications (provided those applications permit it). For example,
95 if your application needs to display a scrolling list of images and another
96 application has developed a suitable scroller and made it available to others,
97 you can call upon that scroller to do the work, rather than develop your own.
98 Your application doesn't incorporate the code of the other application or
99 link to it. Rather, it simply starts up that piece of the other application
100 when the need arises.
104 For this to work, the system must be able to start an application process
105 when any part of it is needed, and instantiate the Java objects for that part.
106 Therefore, unlike applications on most other systems, Android applications don't
107 have a single entry point for everything in the application (no {@code main()}
108 function, for example). Rather, they have essential <i>components</i> that
109 the system can instantiate and run as needed. There are four types of components:
114 <dt><b>Activities</b></dt>
115 <dd>An <i>activity</i> presents a visual user interface for one focused endeavor
116 the user can undertake. For example, an activity might present a list of
117 menu items users can choose from or it might display photographs along
118 with their captions. A text messaging application might have one activity
119 that shows a list of contacts to send messages to, a second activity to write
120 the message to the chosen contact, and other activities to review old messages
121 or change settings. Though they work together to form a cohesive user interface,
122 each activity is independent of the others.
123 Each one is implemented as a subclass of the {@link android.app.Activity} base class.
126 An application might consist of just one activity or, like the text messaging
127 application just mentioned, it may contain several.
128 What the activities are, and how many there are depends, of course, on the
129 application and its design. Typically, one of the activities is marked
130 as the first one that should be presented to the user when the application is
131 launched. Moving from one activity to another is accomplished by having the
132 current activity start the next one.
136 Each activity is given a default window to draw in. Typically, the window
137 fills the screen, but it might be smaller than the screen and float on top
138 of other windows. An activity can also make use of additional windows —
139 for example, a pop-up dialog that calls for a user response in the midst of
140 the activity, or a window that presents users with vital information when they
141 select a particular item on-screen.
145 The visual content of the window is provided by a hierarchy of views —
146 objects derived from the base {@link android.view.View} class. Each view
147 controls a particular rectangular space within the window. Parent views
148 contain and organize the layout of their children. Leaf views (those at the
149 bottom of the hierarchy) draw in the rectangles they control and respond to
150 user actions directed at that space. Thus, views are where the activity's
151 interaction with the user takes place. For example, a view might display
152 a small image and initiate an action when the user taps that image. Android
153 has a number of ready-made views that you can use — including buttons,
154 text fields, scroll bars, menu items, check boxes, and more.
158 A view hierarchy is placed within an activity's window by the
159 <code>{@link android.app.Activity#setContentView Activity.setContentView()}</code>
160 method. The <i>content view</i> is the View object at the root of the hierarchy.
161 (See the separate <a href="{@docRoot}guide/topics/ui/index.html">User Interface</a>
162 document for more information on views and the hierarchy.)
165 <p><dt><b>Services</b></dt>
166 <dd>A <i>service</i> doesn't have a visual user interface, but rather runs in
167 the background for an indefinite period of time. For example, a service might
168 play background music as the user attends to other matters, or it might fetch
169 data over the network or calculate something and provide the result to activities
170 that need it. Each service extends the {@link android.app.Service} base class.
173 A prime example is a media player playing songs from a play list. The player
174 application would probably have one or more activities that allow the user to
175 choose songs and start playing them. However, the music playback itself would
176 not be handled by an activity because users will expect the music to keep
177 playing even after they leave the player and begin something different.
178 To keep the music going, the media player activity could start a service to run
179 in the background. The system would then keep the music playback service running
180 even after the activity that started it leaves the screen.
184 It's possible to connect to (bind to) an ongoing service (and start the service
185 if it's not already running). While connected, you can communicate with the
186 service through an interface that the service exposes. For the music service,
187 this interface might allow users to pause, rewind, stop, and restart the playback.
191 Like activities and the other components, services run in the main thread of
192 the application process. So that they won't block other components or the
193 user interface, they often spawn another thread for time-consuming tasks
194 (like music playback). See <a href="#procthread">Processes and Threads</a>, later.
197 <dt><b>Broadcast receivers</b></dt>
198 <dd>A <i>broadcast receiver</i> is a component that does nothing but
199 receive and react to broadcast announcements. Many broadcasts originate in
200 system code — for example, announcements that the timezone has changed,
201 that the battery is low, that a picture has been taken, or that the user
202 changed a language preference. Applications can also initiate broadcasts
203 — for example, to let other applications know that some data has been
204 downloaded to the device and is available for them to use.
207 An application can have any number of broadcast receivers to respond to any
208 announcements it considers important. All receivers extend the {@link
209 android.content.BroadcastReceiver} base class.
213 Broadcast receivers do not display a user interface. However, they may start
214 an activity in response to the information they receive, or they may use
215 the {@link android.app.NotificationManager} to alert the user. Notifications
216 can get the user's attention in various ways — flashing
217 the backlight, vibrating the device, playing a sound, and so on. They
218 typically place a persistent icon in the status bar, which users can open to
222 <dt><b>Content providers</b></dt>
223 <dd>A <i>content provider</i> makes a specific set of the application's data
224 available to other applications. The data can be stored in the file system,
225 in an SQLite database, or in any other manner that makes sense.
226 The content provider extends the {@link android.content.ContentProvider} base
227 class to implement a standard set of methods that enable other applications
228 to retrieve and store data of the type it controls. However, applications
229 do not call these methods directly. Rather they use a {@link
230 android.content.ContentResolver} object and call its methods instead.
231 A ContentResolver can talk to any content provider; it cooperates with the
232 provider to manage any interprocess communication that's involved.
236 <a href="{@docRoot}guide/topics/providers/content-providers.html">Content
237 Providers</a> document for more information on using content providers.
243 Whenever there's a request that should be handled by a particular component,
244 Android makes sure that the application process of the component is running,
245 starting it if necessary, and that an appropriate instance of the component
246 is available, creating the instance if necessary.
250 <h3 id="actcomp">Activating components: intents</h3>
253 Content providers are activated when they're targeted by a request from a
254 ContentResolver. The other three components — activities, services,
255 and broadcast receivers — are activated by asynchronous messages
256 called <i>intents</i>. An intent is an {@link android.content.Intent}
257 object that holds the content of the message. For activities and services,
258 it names the action being requested and specifies the URI of the data to
259 act on, among other things. For example, it might convey a request for
260 an activity to present an image to the user or let the user edit some
261 text. For broadcast receivers, the Intent object names the action being
262 announced. For example, it might announce to interested parties that the
263 camera button has been pressed.
267 There are separate methods for activating each type of component:
272 <li>An activity is launched (or given something new to do) by passing an
273 Intent object to <code>{@link android.content.Context#startActivity
274 Context.startActivity()}</code> or <code>{@link
275 android.app.Activity#startActivityForResult
276 Activity.startActivityForResult()}</code>. The responding activity can
277 look at the initial intent that caused it to be launched by calling its
278 <code>{@link android.app.Activity#getIntent getIntent()}</code> method.
279 Android calls the activity's <code>{@link
280 android.app.Activity#onNewIntent onNewIntent()}</code> method to pass
281 it any subsequent intents.
284 One activity often starts the next one. If it expects a result back from
285 the activity it's starting, it calls {@code startActivityForResult()}
286 instead of {@code startActivity()}. For example, if it starts an activity
287 that lets the user pick a photo, it might expect to be returned the chosen
288 photo. The result is returned in an Intent object that's passed to the
289 calling activity's <code>{@link android.app.Activity#onActivityResult
290 onActivityResult()}</code> method.
294 <li><p>A service is started (or new instructions are given to an ongoing
295 service) by passing an Intent object to <code>{@link
296 android.content.Context#startService Context.startService()}</code>.
297 Android calls the service's <code>{@link android.app.Service#onStart
298 onStart()}</code> method and passes it the Intent object.</p>
301 Similarly, an intent can be passed to <code>{@link
302 android.content.Context#bindService Context.bindService()}</code> to
303 establish an ongoing connection between the calling component and a
304 target service. The service receives the Intent object in
305 an <code>{@link android.app.Service#onBind onBind()}</code> call.
306 (If the service is not already running, {@code bindService()} can
307 optionally start it.) For example, an activity might establish a connection
308 with the music playback service mentioned earlier so that it can provide
309 the user with the means (a user interface) for controlling the playback.
310 The activity would call {@code bindService()} to set up that connection,
311 and then call methods defined by the service to affect the playback.
315 A later section, <a href="#rpc">Remote procedure calls</a>, has more details
316 about binding to a service.
320 <li><p>An application can initiate a broadcast by passing an Intent object to
321 methods like <code>{@link
322 android.content.Context#sendBroadcast(Intent) Context.sendBroadcast()}</code>,
323 <code>{@link android.content.Context#sendOrderedBroadcast(Intent, String)
324 Context.sendOrderedBroadcast()}</code>, and <code>{@link
325 android.content.Context#sendStickyBroadcast Context.sendStickyBroadcast()}</code>
326 in any of their variations. Android delivers the intent to all interested
327 broadcast receivers by calling their <code>{@link
328 android.content.BroadcastReceiver#onReceive onReceive()}</code> methods.</p></li>
333 For more on intent messages, see the separate article,
334 <a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents
335 and Intent Filters</a>.
339 <h3 id="endcomp">Shutting down components</h3>
342 A content provider is active only while it's responding to a request from
343 a ContentResolver. And a broadcast receiver is active only while it's
344 responding to a broadcast message. So there's no need to explicitly shut
345 down these components.
349 Activities, on the other hand, provide the user interface. They're
350 in a long-running conversation with the user and may remain active,
351 even when idle, as long as the conversation continues. Similarly, services
352 may also remain running for a long time. So Android has methods to shut
353 down activities and services in an orderly way:
357 <li>An activity can be shut down by calling its
358 <code>{@link android.app.Activity#finish finish()}</code> method. One activity can
359 shut down another activity (one it started with {@code startActivityForResult()}) by
360 calling <code>{@link android.app.Activity#finishActivity finishActivity()}</code>.</li>
362 <li>A service can be stopped by calling its
363 <code>{@link android.app.Service#stopSelf stopSelf()}</code> method, or by calling
364 <code>{@link android.content.Context#stopService Context.stopService()}</code>.</li>
368 Components might also be shut down by the system when they are no longer being
369 used or when Android must reclaim memory for more active components. A later
370 section, <a href="#lcycles">Component Lifecycles</a>, discusses this
371 possibility and its ramifications in more detail.
375 <h3 id="manfile">The manifest file</h3>
378 Before Android can start an application component, it must learn that
379 the component exists. Therefore, applications declare their components
380 in a manifest file that's bundled into the Android package, the {@code .apk}
381 file that also holds the application's code, files, and resources.
385 The manifest is a structured XML file and is always named AndroidManifest.xml
386 for all applications. It does a number of things in addition to declaring the
387 application's components, such as naming any libraries the application needs
388 to be linked against (besides the default Android library) and identifying
389 any permissions the application expects to be granted.
393 But the principal task of the manifest is to inform Android about the application's
394 components. For example, an activity might be declared as follows:
397 <pre><?xml version="1.0" encoding="utf-8"?>
398 <manifest . . . >
399 <application . . . >
400 <activity android:name="com.example.project.FreneticActivity"
401 android:icon="@drawable/small_pic.png"
402 android:label="@string/freneticLabel"
407 </manifest></pre>
410 The {@code name} attribute of the
411 <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>
412 element names the {@link android.app.Activity} subclass that implements the
413 activity. The {@code icon} and {@code label} attributes point to
414 resource files containing an icon and label that can be displayed
415 to users to represent the activity.
419 The other components are declared in a similar way —
420 <code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>
421 elements for services,
422 <code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code>
423 elements for broadcast receivers, and
424 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code>
425 elements for content providers. Activities, services, and content providers
426 that are not declared in the manifest are not visible to the system and are
427 consequently never run. However, broadcast receivers can either be
428 declared in the manifest, or they can be created dynamically in code
429 (as {@link android.content.BroadcastReceiver} objects)
430 and registered with the system by calling
431 <code>{@link android.content.Context#registerReceiver Context.registerReceiver()}</code>.
435 For more on how to structure a manifest file for your application, see
436 <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The
437 AndroidManifest.xml File</a>.
441 <h3 id="ifilters">Intent filters</h3>
444 An Intent object can explicitly name a target component. If it does,
445 Android finds that component (based on the declarations in the manifest
446 file) and activates it. But if a target is not explicitly named,
447 Android must locate the best component to respond to the intent.
448 It does so by comparing the Intent object to the <i>intent filters</i>
449 of potential targets. A component's intent filters inform Android of
450 the kinds of intents the component is able to handle. Like other
451 essential information about the component, they're declared in the
452 manifest file. Here's an extension of the previous example that adds
453 two intent filters to the activity:
456 <pre><?xml version="1.0" encoding="utf-8"?>
457 <manifest . . . >
458 <application . . . >
459 <activity android:name="com.example.project.FreneticActivity"
460 android:icon="@drawable/small_pic.png"
461 android:label="@string/freneticLabel"
463 <intent-filter . . . >
464 <action android:name="android.intent.action.MAIN" />
465 <category android:name="android.intent.category.LAUNCHER" />
466 </intent-filter>
467 <intent-filter . . . >
468 <action android:name="com.example.project.BOUNCE" />
469 <data android:mimeType="image/jpeg" />
470 <category android:name="android.intent.category.DEFAULT" />
471 </intent-filter>
475 </manifest></pre>
478 The first filter in the example — the combination of the action
479 "{@code android.intent.action.MAIN}" and the category
480 "{@code android.intent.category.LAUNCHER}" — is a common one.
481 It marks the activity as one that should be represented in the
482 application launcher, the screen listing applications users can launch
483 on the device. In other words, the activity is the entry point for
484 the application, the initial one users would see when they choose
485 the application in the launcher.
489 The second filter declares an action that the activity can perform on
490 a particular type of data.
494 A component can have any number of intent filters, each one declaring a
495 different set of capabilities. If it doesn't have any filters, it can
496 be activated only by intents that explicitly name the component as the
501 For a broadcast receiver that's created and registered in code, the
502 intent filter is instantiated directly as an {@link android.content.IntentFilter}
503 object. All other filters are set up in the manifest.
507 For more on intent filters, see a separate document,
508 <a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents
509 and Intent Filters</a>.
513 <h2 id="acttask">Activities and Tasks</h2>
516 As noted earlier, one activity can start another, including one defined
517 in a different application. Suppose, for example, that you'd like
518 to let users display a street map of some location. There's already an
519 activity that can do that, so all your activity needs to do is put together
520 an Intent object with the required information and pass it to
521 {@code startActivity()}. The map viewer will display the map. When the user
522 hits the BACK key, your activity will reappear on screen.
526 To the user, it will seem as if the map viewer is part of the same application
527 as your activity, even though it's defined in another application and runs in
528 that application's process. Android maintains this user experience by keeping
529 both activities in the same <i>task</i>. Simply put, a task is what the user
530 experiences as an "application." It's a group of related activities, arranged
531 in a stack. The root activity in the stack is the one that began the task
532 — typically, it's an activity the user selected in the application launcher.
533 The activity at the top of the stack is one that's currently running —
534 the one that is the focus for user actions. When one activity starts another,
535 the new activity is pushed on the stack; it becomes the running activity.
536 The previous activity remains in the stack. When the user presses the BACK key,
537 the current activity is popped from the stack, and the previous one resumes as
538 the running activity.
542 The stack contains objects, so if a task has more than one instance of the same
543 Activity subclass open — multiple map viewers, for example — the
544 stack has a separate entry for each instance. Activities in the stack are never
545 rearranged, only pushed and popped.
549 A task is a stack of activities, not a class or an element in the manifest file.
550 So there's no way to set values for a task independently of its activities.
551 Values for the task as a whole are set in the root activity. For example, the
552 next section will talk about the "affinity of a task"; that value is read from
553 the affinity set for the task's root activity.
557 All the activities in a task move together as a unit. The entire task (the entire
558 activity stack) can be brought to the foreground or sent to the background.
559 Suppose, for instance, that the current task has four activities in its stack
560 — three under the current activity. The user presses the HOME key, goes
561 to the application launcher, and selects a new application (actually, a new <i>task</i>).
562 The current task goes into the background and the root activity for the new task is displayed.
563 Then, after a short period, the user goes back to the home screen and again selects
564 the previous application (the previous task). That task, with all four
565 activities in the stack, comes forward. When the user presses the BACK
566 key, the screen does not display the activity the user just left (the root
567 activity of the previous task). Rather, the activity on the top of the stack
568 is removed and the previous activity in the same task is displayed.
572 The behavior just described is the default behavior for activities and tasks.
573 But there are ways to modify almost all aspects of it. The association of
574 activities with tasks, and the behavior of an activity within a task, is
575 controlled by the interaction between flags set in the Intent object that
576 started the activity and attributes set in the activity's
577 <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>
578 element in the manifest. Both requester and respondent have a say in what happens.
582 In this regard, the principal Intent flags are:
584 <p style="margin-left: 2em">{@code FLAG_ACTIVITY_NEW_TASK}
585 <br/>{@code FLAG_ACTIVITY_CLEAR_TOP}
586 <br/>{@code FLAG_ACTIVITY_RESET_TASK_IF_NEEDED}
587 <br/>{@code FLAG_ACTIVITY_SINGLE_TOP}</p>
590 The principal {@code <activity>} attributes are:
592 <p style="margin-left: 2em">{@code taskAffinity}
593 <br/>{@code launchMode}
594 <br/>{@code allowTaskReparenting}
595 <br/>{@code clearTaskOnLaunch}
596 <br/>{@code alwaysRetainTaskState}
597 <br/>{@code finishOnTaskLaunch}</p>
600 The following sections describe what some of these flags and attributes do,
601 how they interact, and what considerations should govern their use.
605 <h3 id="afftask">Affinities and new tasks</h3>
608 By default, all the activities in an application have an <i>affinity</i> for each
609 other — that is, there's a preference for them all to belong to the
610 same task. However, an individual affinity can be set for each activity
611 with the {@code taskAffinity} attribute of the {@code <activity>} element.
612 Activities defined in different applications can share an affinity, or activities
613 defined in the same application can be assigned different affinities.
614 The affinity comes into play in two circumstances: When the Intent object
615 that launches an activity contains the {@code FLAG_ACTIVITY_NEW_TASK} flag,
616 and when an activity has its {@code allowTaskReparenting} attribute set
621 <dt>The <code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code> flag</dt>
622 <dd>As described earlier, a new activity is, by default, launched into
623 the task of the activity that called {@code startActivity()}. It's pushed
624 onto the same stack as the caller. However, if the Intent object passed
625 to {@code startActivity()} contains the {@code FLAG_ACTIVITY_NEW_TASK}
626 flag, the system looks for a different task to house the new activity.
627 Often, as the name of the flag implies, it's a new task. However, it
628 doesn't have to be. If there's already an existing task with the same
629 affinity as the new activity, the activity is launched into that task. If
630 not, it begins a new task.</dd>
633 href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code>
635 <dd>If an activity has its {@code allowTaskReparenting} attribute set
636 to "{@code true}", it can move from the task it starts in to the task
637 it has an affinity for when that task comes to the fore. For example,
638 suppose that an activity that reports weather conditions in selected
639 cities is defined as part of a travel application. It has the same
640 affinity as other activities in the same application (the default
641 affinity) and it allows reparenting. One of your activities
642 starts the weather reporter, so it initially belongs to the same task as
643 your activity. However, when the travel application next comes forward,
644 the weather reporter will be reassigned to and displayed with that task.</dd>
648 If an {@code .apk} file contains more than one "application"
649 from the user's point of view, you will probably want to assign different
650 affinities to the activities associated with each of them.
654 <h3 id="lmodes">Launch modes</h3>
657 There are four different launch modes that can be assigned to an {@code
658 <activity>} element's
659 <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">launchMode</a></code>
663 <p style="margin-left: 2em">"{@code standard}" (the default mode)
664 <br>"{@code singleTop}"
665 <br>"{@code singleTask}"
666 <br>"{@code singleInstance}"</p>
669 The modes differ from each other on these four points:
674 <li><b>Which task will hold the activity that responds to the intent</b>.
675 For the "{@code standard}" and "{@code singleTop}" modes, it's the task that
676 originated the intent (and called
677 <code>{@link android.content.Context#startActivity startActivity()}</code>)
678 — unless the Intent object contains the
679 <code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code> flag.
680 In that case, a different task is chosen as described in the previous
681 section, <a href="#afftask">Affinities and new tasks</a>.
684 In contrast, the "{@code singleTask}" and "{@code singleInstance}" modes mark
685 activities that are always at the root of a task. They define a task; they're
686 never launched into another task.
689 <li><p><b>Whether there can be multiple instances of the activity</b>.
690 A "{@code standard}" or "{@code singleTop}" activity can be instantiated
691 many times. They can belong to multiple tasks, and a given task can have
692 multiple instances of the same activity.
696 In contrast, "{@code singleTask}" and "{@code singleInstance}" activities
697 are limited to just one instance. Since these activities are at the root
698 of a task, this limitation means that there is never more than a single
699 instance of the task on the device at one time.
702 <li><p><b>Whether the instance can have other activities in its task</b>.
703 A "{@code singleInstance}" activity stands alone as the only activity in its
704 task. If it starts another activity, that activity will be launched into a
705 different task regardless of its launch mode — as if {@code
706 FLAG_ACTIVITY_NEW_TASK} was in the intent. In all other respects, the
707 "{@code singleInstance}" mode is identical to "{@code singleTask}".</p>
710 The other three modes permit multiple activities to belong to the task.
711 A "{@code singleTask}" activity will always be the root activity of the task,
712 but it can start other activities that will be assigned to its
713 task. Instances of "{@code standard}" and "{@code singleTop}"
714 activities can appear anywhere in a stack.
717 <li><b>Whether a new instance of the class will be launched
718 to handle a new intent</b>. For the default "{@code standard}" mode, a
719 new instance is created to respond to every new intent. Each instance
720 handles just one intent. For the "{@code singleTop}" mode, an existing
721 instance of the class is re-used to handle a new intent if it resides
722 at the top of the activity stack of the target task. If it does not
723 reside at the top, it is not re-used. Instead, a new instance
724 is created for the new intent and pushed on the stack.
727 For example, suppose a task's activity stack consists of root activity A with
728 activities B, C, and D on top in that order, so the stack is A-B-C-D. An intent
729 arrives for an activity of type D. If D has the default "{@code standard}" launch
730 mode, a new instance of the class is launched and the stack becomes A-B-C-D-D.
731 However, if D's launch mode is "{@code singleTop}", the existing instance is
732 expected to handle the new intent (since it's at the top of the stack) and the
733 stack remains A-B-C-D.
737 If, on the other hand, the arriving intent is for an activity of type B, a new
738 instance of B would be launched no matter whether B's mode is "{@code standard}"
739 or "{@code singleTop}" (since B is not at the top of the stack), so the resulting
740 stack would be A-B-C-D-B.
744 As noted above, there's never more than one instance of a "{@code singleTask}"
745 or "{@code singleInstance}" activity, so that instance is expected to handle
746 all new intents. A "{@code singleInstance}" activity is always at the top of
747 the stack (since it is the only activity in the task), so it is always in
748 position to handle the intent. However, a "{@code singleTask}" activity may
749 or may not have other activities above it in the stack. If it does, it is not
750 in position to handle the intent, and the intent is dropped. (Even though the
751 intent is dropped, its arrival would have caused the task to come to the
752 foreground, where it would remain.)
759 When an existing activity is asked to handle a new intent, the Intent
760 object is passed to the activity in an
761 <code>{@link android.app.Activity#onNewIntent onNewIntent()}</code> call.
762 (The intent object that originally started the activity can be retrieved by
763 calling <code>{@link android.app.Activity#getIntent getIntent()}</code>.)
767 Note that when a new instance of an Activity is created to handle a new
768 intent, the user can always press the BACK key to return to the previous state
769 (to the previous activity). But when an existing instance of an
770 Activity handles a new intent, the user cannot press the BACK key to
771 return to what that instance was doing before the new intent arrived.
775 For more on launch modes, see the description of the <code><a
776 href="{@docRoot}guide/topics/manifest/activity-element.html#lmode"><activity></a></code>
781 <h3 id="clearstack">Clearing the stack</h3>
784 If the user leaves a task for a long time, the system clears the task of all
785 activities except the root activity. When the user returns to the task again,
786 it's as the user left it, except that only the initial activity is present.
787 The idea is that, after
788 a time, users will likely have abandoned what they were doing before and are
789 returning to the task to begin something new.
793 That's the default. There are some activity attributes that can be used to
794 control this behavior and modify it:
799 href="{@docRoot}guide/topics/manifest/activity-element.html#always">alwaysRetainTaskState</a></code>
801 <dd>If this attribute is set to "{@code true}" in the root activity of a task,
802 the default behavior just described does not happen.
803 The task retains all activities in its stack even after a long period.</dd>
806 href="{@docRoot}guide/topics/manifest/activity-element.html#clear">clearTaskOnLaunch</a></code>
808 <dd>If this attribute is set to "{@code true}" in the root activity of a task,
809 the stack is cleared down to the root activity whenever the user leaves the task
810 and returns to it. In other words, it's the polar opposite of
811 {@code alwaysRetainTaskState}. The user always returns to the task in its
812 initial state, even after a momentary absence.</dd>
815 href="{@docRoot}guide/topics/manifest/activity-element.html#finish">finishOnTaskLaunch</a></code>
817 <dd>This attribute is like {@code clearTaskOnLaunch}, but it operates on a
818 single activity, not an entire task. And it can cause any activity to go
819 away, including the root activity. When it's set to "{@code true}", the
820 activity remains part of the task only for the current session. If the user
821 leaves and then returns to the task, it no longer is present.</dd>
825 There's another way to force activities to be removed from the stack.
826 If an Intent object includes the <code>{@link
827 android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP FLAG_ACTIVITY_CLEAR_TOP}</code>
828 flag, and the target task already has an instance of the type of activity that
829 should handle the intent in its stack, all activities above that instance
830 are cleared away so that it stands at the top of the stack and can respond
832 If the launch mode of the designated activity is "{@code standard}", it too
833 will be removed from the stack, and a new instance will be launched to handle
834 the incoming intent. That's because a new instance is always created for
835 a new intent when the launch mode is "{@code standard}".
839 {@code FLAG_ACTIVITY_CLEAR_TOP} is most often used in conjunction
840 with {@code FLAG_ACTIVITY_NEW_TASK}. When used together, these flags are
841 a way of locating an existing activity in another task and putting it in
842 a position where it can respond to the intent.
846 <h3 id="starttask">Starting tasks</h3>
849 An activity is set up as the entry point for a task by giving it
850 an intent filter with "{@code android.intent.action.MAIN}" as the
851 specified action and "{@code android.intent.category.LAUNCHER}" as
852 the specified category. (There's an example of this type of filter
853 in the earlier <a href="#ifilters">Intent Filters</a> section.)
854 A filter of this kind causes an icon and label for the activity to be
855 displayed in the application launcher, giving users a way both to
856 launch the task and to return to it at any time after it has been
861 This second ability is important: Users must be able to leave a task
862 and then come back to it later. For this reason, the two launch modes
863 that mark activities as always initiating a task, "{@code singleTask}"
864 and "{@code singleInstance}", should be used only when the activity has
865 a {@code MAIN} and {@code LAUNCHER} filter.
866 Imagine, for example, what could happen if the filter is missing:
867 An intent launches a "{@code singleTask}" activity, initiating a new task,
868 and the user spends some time working in that task. The user then presses
869 the HOME key. The task is now ordered behind and obscured by the home
870 screen. And, because it is not represented in the application launcher,
871 the user has no way to return to it.
875 A similar difficulty attends the {@code FLAG_ACTIVITY_NEW_TASK} flag.
876 If this flag causes an activity to
877 begin a new task and the user presses the HOME key to leave it, there
878 must be some way for the user to navigate back to it again. Some
879 entities (such as the notification manager) always start activities
880 in an external task, never as part of their own, so they always put
881 {@code FLAG_ACTIVITY_NEW_TASK} in the intents they pass to
882 {@code startActivity()}. If you have an activity that can be invoked
883 by an external entity that might use this flag, take care that the user
884 has a independent way to get back to the task that's started.
888 For those cases where you don't want the user to be able to return
889 to an activity, set the {@code <activity>} element's {@code
890 finishOnTaskLaunch} to "{@code true}".
891 See <a href="#clearstack">Clearing the stack</a>, earlier.
895 <h2 id="procthread">Processes and Threads</h2>
898 When the first of an application's components needs to be run, Android
899 starts a Linux process for it with a single thread of execution. By default,
900 all components of the application run in that process and thread.
904 However, you can arrange for components to run in other processes, and you
905 can spawn additional threads for any process.
909 <h3 id="procs">Processes</h3>
912 The process where a component runs is controlled by the manifest file.
913 The component elements — {@code <activity>},
914 {@code <service>}, {@code <receiver>}, and {@code <provider>}
915 — each have a {@code process} attribute that can specify a process
916 where that component should run. These attributes can be set so that each
917 component runs in its own process, or so that some components share a process
918 while others do not. They can also be set so that components of
919 different applications run in the same process — provided that the
920 applications share the same Linux user ID and are signed by the same authorities.
921 The {@code <application>} element also has a {@code process} attribute,
922 for setting a default value that applies to all components.
926 All components are instantiated in the main thread of the specified
927 process, and system calls to the component are dispatched from that
928 thread. Separate threads are not created for each instance. Consequently,
929 methods that respond to those calls — methods like
930 <code>{@link android.view.View#onKeyDown View.onKeyDown()}</code> that report
931 user actions and the lifecycle notifications discussed later in the
932 <a href="#lcycles">Component Lifecycles</a> section — always run in the
933 main thread of the process. This means
934 that no component should perform long or blocking operations (such as networking
935 operations or computation loops) when called by the system, since this will block
936 any other components also in the process. You can spawn separate threads for
937 long operations, as discussed under <a href="#threads">Threads</a>, next.
941 Android may decide to shut down a process at some point, when memory is
942 low and required by other processes that are more immediately serving
943 the user. Application components running in the process are consequently
944 destroyed. A process is restarted for those components when there's again
949 When deciding which processes to terminate, Android weighs their relative
950 importance to the user. For example, it more readily shuts down a process
951 with activities that are no longer visible on screen than a process with
953 The decision whether to terminate a process, therefore, depends on the state
954 of the components running in that process. Those states are the subject of
955 a later section, <a href="#lcycles">Component Lifecycles</a>.
959 <h3 id="threads">Threads</h3>
962 Even though you may confine your application to a single process, there will
963 likely be times when you will need to spawn a thread to do some background
964 work. Since the user interface must always be quick to respond to user actions,
965 the thread that hosts an activity should not also host time-consuming operations
966 like network downloads. Anything that may not be completed quickly should be
967 assigned to a different thread.
971 Threads are created in code using standard Java {@link java.lang.Thread}
972 objects. Android provides a number of convenience classes for managing
973 threads — {@link android.os.Looper} for running a message loop within
974 a thread, {@link android.os.Handler} for processing messages, and
975 {@link android.os.HandlerThread} for setting up a thread with a message loop.
979 <h3 id="rpc">Remote procedure calls</h3>
982 Android has a lightweight mechanism for remote procedure calls (RPCs)
983 — where a method is called locally, but executed remotely (in another
984 process), with any result returned back to the caller.
985 This entails decomposing the method call and all its attendant data to a
986 level the operating system can understand, transmitting it from the local
987 process and address space to the remote process and address space, and
988 reassembling and reenacting the call there. Return values have to be
989 transmitted in the opposite direction. Android provides all the code
990 to do that work, so that you can concentrate on defining and implementing
991 the RPC interface itself.
995 An RPC interface can include only methods. By default,
996 all methods are executed synchronously (the local method blocks until the
997 remote method finishes), even if there is no return value.
1001 In brief, the mechanism works as follows: You'd begin by declaring the
1002 RPC interface you want to implement using a simple IDL (interface definition
1003 language). From that declaration, the
1004 <code><a href="{@docRoot}guide/developing/tools/aidl.html">aidl</a></code>
1005 tool generates a Java interface definition that must be made available to
1006 both the local and the remote process. It contains two inner class, as shown
1007 in the following diagram:
1010 <p style="margin-left: 2em">
1011 <img src="{@docRoot}images/binder_rpc.png" alt="RPC mechanism." />
1015 The inner classes have all the code needed to administer remote procedure
1016 calls for the interface you declared with the IDL.
1017 Both inner classes implement the {@link android.os.IBinder}
1018 interface. One of them is used locally and internally by the system;
1019 the code you write can ignore it.
1020 The other, called Stub, extends the {@link android.os.Binder}
1021 class. In addition to internal code for effectuating the IPC calls, it
1022 contains declarations for the methods in the RPC interface you declared.
1023 You would subclass Stub to implement those methods, as indicated in the
1028 Typically, the remote process would be managed by a service (because a
1029 service can inform the system about the process and its connections to
1030 other processes). It would have both the interface file generated by
1031 the {@code aidl} tool and the Stub subclass implementing the
1032 RPC methods. Clients of the service would have only the interface file
1033 generated by the {@code aidl} tool.
1037 Here's how a connection between a service and its clients is set up:
1041 <li>Clients of the service (on the local side) would implement
1042 <code>{@link android.content.ServiceConnection#onServiceConnected
1043 onServiceConnected()}</code> and
1044 <code>{@link android.content.ServiceConnection#onServiceDisconnected
1045 onServiceDisconnected()}</code> methods so they can be notified
1046 when a successful connection to the remote service is established, and
1047 when it goes away. They would then call
1048 <code>{@link android.content.Context#bindService bindService()}</code>
1049 to set up the connection.
1053 The service's <code>{@link android.app.Service#onBind onBind()}</code>
1054 method would be implemented to either accept or reject the connection,
1055 depending on the intent it receives (the intent passed to
1056 {@code bindService()}). If the connection is accepted, it returns
1057 an instance of the Stub subclass.
1060 <li>If the service accepts the connection, Android calls the
1061 client's {@code onServiceConnected()} method and passes it an IBinder
1062 object, a proxy for the Stub subclass managed by the service. Through
1063 the proxy, the client can make calls on the remote service.
1068 This brief description omits some details of the RPC mechanism. For more
1070 <a href="{@docRoot}guide/developing/tools/aidl.html">Designing a Remote
1071 Interface Using AIDL</a> and the {@link android.os.IBinder IBinder} class
1076 <h3 id="tsafe">Thread-safe methods</h3>
1079 In a few contexts, the methods you implement may be called from more
1080 than one thread, and therefore must be written to be thread-safe.
1084 This is primarily true for methods that can be called remotely —
1085 as in the RPC mechanism discussed in the previous section.
1086 When a call on a method implemented in an IBinder object originates
1087 in the same process as the IBinder, the method is executed in the
1088 caller's thread. However, when the call originates in another process,
1089 the method is executed in a thread chosen from a pool of threads that
1090 Android maintains in the same process as the IBinder; it's not executed
1091 in the main thread of the process. For example, whereas a service's
1092 {@code onBind()} method would be called from the main thread of the
1093 service's process, methods implemented in the object that {@code onBind()}
1094 returns (for example, a Stub subclass that implements RPC methods) would
1095 be called from threads in the pool.
1096 Since services can have more than one client, more than one pool thread
1097 can engage the same IBinder method at the same time. IBinder methods
1098 must, therefore, be implemented to be thread-safe.
1102 Similarly, a content provider can receive data requests that originate in
1103 other processes. Although the ContentResolver and ContentProvider classes
1104 hide the details of how the interprocess communication is managed,
1105 ContentProvider methods that respond to those requests — the methods
1106 <code>{@link android.content.ContentProvider#query query()}</code>,
1107 <code>{@link android.content.ContentProvider#insert insert()}</code>,
1108 <code>{@link android.content.ContentProvider#delete delete()}</code>,
1109 <code>{@link android.content.ContentProvider#update update()}</code>, and
1110 <code>{@link android.content.ContentProvider#getType getType()}</code>
1111 — are called from a pool of threads in the content provider's
1112 process, not the main thread of the process. Since these methods
1113 may be called from any number of threads at the same time, they too must
1114 be implemented to be thread-safe.
1118 <h2 id="lcycles">Component Lifecycles</h2>
1121 Application components have a lifecycle — a beginning when
1122 Android instantiates them to respond to intents through to an end when
1123 the instances are destroyed. In between, they may sometimes be active
1124 or inactive,or, in the case of activities, visible to the user or
1125 invisible. This section discusses the lifecycles of activities,
1126 services, and broadcast receivers — including the states that they
1127 can be in during their lifetimes, the methods that notify you of transitions
1128 between states, and the effect of those states on the possibility that
1129 the process hosting them might be terminated and the instances destroyed.
1133 <h3 id="actlife">Activity lifecycle</h3>
1135 <p>An activity has essentially three states:</p>
1138 <li> It is <em>active</em> or <em>running</em> when it is in the foreground of the
1139 screen (at the top of the activity stack for the current task). This is the
1140 activity that is the focus for the user's actions.</li>
1142 <li><p>It is <em>paused</em> if it has lost focus but is still visible to the user.
1143 That is, another activity lies on top of it and that activity either is transparent
1144 or doesn't cover the full screen, so some of the paused activity can show through.
1145 A paused activity is completely alive (it maintains all state and member information
1146 and remains attached to the window manager), but can be killed by the system in
1147 extreme low memory situations.</p></li>
1149 <li><p>It is <em>stopped</em> if it is completely obscured by another activity.
1150 It still retains all state and member information. However, it is no longer
1151 visible to the user so its window is hidden and it will often be killed by the
1152 system when memory is needed elsewhere.</p></li>
1156 If an activity is paused or stopped, the system can drop it from memory either
1157 by asking it to finish (calling its {@link android.app.Activity#finish finish()}
1158 method), or simply killing its process. When it is displayed again
1159 to the user, it must be completely restarted and restored to its previous state.
1163 As an activity transitions from state to state, it is notified of the change
1164 by calls to the following protected methods:
1167 <p style="margin-left: 2em">{@code void onCreate(Bundle <i>savedInstanceState</i>)}
1168 <br/>{@code void onStart()}
1169 <br/>{@code void onRestart()}
1170 <br/>{@code void onResume()}
1171 <br/>{@code void onPause()}
1172 <br/>{@code void onStop()}
1173 <br/>{@code void onDestroy()}</p>
1176 All of these methods are hooks that you can override to do appropriate work
1177 when the state changes. All activities must implement
1178 <code>{@link android.app.Activity#onCreate onCreate()}</code> to do the
1179 initial setup when the object is first instantiated.
1180 Many will also implement <code>{@link android.app.Activity#onPause onPause()}</code>
1181 to commit data changes and otherwise prepare to stop interacting with the user.
1184 <div class="sidebox-wrapper">
1185 <div class="sidebox">
1186 <h2>Calling into the superclass</h2>
1188 An implementation of any activity lifecycle method should always first
1189 call the superclass version. For example:
1192 <pre>protected void onPause() {
1201 Taken together, these seven methods define the entire lifecycle of an
1202 activity. There are three nested loops that you can monitor by
1207 <li>The <b>entire lifetime</b> of an activity happens between the first call
1208 to <code>{@link android.app.Activity#onCreate onCreate()}</code> through to a
1209 single final call to <code>{@link android.app.Activity#onDestroy}</code>.
1210 An activity does all its initial setup of "global" state in {@code onCreate()},
1211 and releases all remaining resources in {@code onDestroy()}. For example,
1212 if it has a thread running in the background to download data from the network,
1213 it may create that thread in {@code onCreate()} and then stop the thread in
1214 {@code onDestroy()}.</li>
1216 <li><p>The <b>visible lifetime</b> of an activity happens between a call to
1217 <code>{@link android.app.Activity#onStart onStart()}</code> until a
1218 corresponding call to <code>{@link android.app.Activity#onStop onStop()}</code>.
1219 During this time, the user can see the activity on-screen, though it may not
1220 be in the foreground and interacting with the user. Between these two methods,
1221 you can maintain resources that are needed to show the activity to the user.
1222 For example, you can register a {@link android.content.BroadcastReceiver} in
1223 {@code onStart()} to monitor for changes that impact your UI, and unregister
1224 it in {@code onStop()} when the user can no longer see what you are displaying.
1225 The {@code onStart()} and {@code onStop()} methods can be called multiple times,
1226 as the activity alternates between being visible and hidden to the user.</p></li>
1228 <li><p>The <b>foreground lifetime</b> of an activity happens between a call
1229 to <code>{@link android.app.Activity#onResume onResume()}</code> until a
1230 corresponding call to <code>{@link android.app.Activity#onPause onPause()}</code>.
1231 During this time, the activity is in front of all other activities on screen and
1232 is interacting with the user. An activity can frequently transition between the
1233 resumed and paused states — for example, {@code onPause()} is called when
1234 the device goes to sleep or when a new activity is started, {@code onResume()}
1235 is called when an activity result or a new intent is delivered. Therefore, the
1236 code in these two methods should be fairly lightweight.</p></li>
1240 The following diagram illustrates these loops and the paths an activity
1241 may take between states. The colored ovals are major states the activity
1242 can be in. The square rectangles represent the callback methods you can implement
1243 to perform operations when the activity transitions between states.
1246 <p style="margin-left: 2em"><img src="{@docRoot}images/activity_lifecycle.png"
1247 alt="State diagram for an Android activity lifecycle." /></p>
1250 The following table describes each of these methods in more detail and
1251 locates it within the activity's overall lifecycle:
1254 <table border="2" width="85%" frame="hsides" rules="rows">
1255 <colgroup align="left" span="3"></colgroup>
1256 <colgroup align="left"></colgroup>
1257 <colgroup align="center"></colgroup>
1258 <colgroup align="center"></colgroup>
1261 <tr><th colspan="3">Method</th> <th>Description</th> <th>Killable?</th> <th>Next</th></tr>
1266 <td colspan="3" align="left"><code>{@link android.app.Activity#onCreate onCreate()}</code></td>
1267 <td>Called when the activity is first created.
1268 This is where you should do all of your normal static set up —
1269 create views, bind data to lists, and so on. This method is passed
1270 a Bundle object containing the activity's previous state, if that
1271 state was captured (see <a href="#actstate">Saving Activity State</a>,
1273 <p>Always followed by {@code onStart()}.</p></td>
1274 <td align="center">No</td>
1275 <td align="center">{@code onStart()}</td>
1279 <td rowspan="5" style="border-left: none; border-right: none;"> </td>
1280 <td colspan="2" align="left"><code>{@link android.app.Activity#onRestart
1281 onRestart()}</code></td>
1282 <td>Called after the activity has been stopped, just prior to it being
1284 <p>Always followed by {@code onStart()}</p></td>
1285 <td align="center">No</td>
1286 <td align="center">{@code onStart()}</td>
1290 <td colspan="2" align="left"><code>{@link android.app.Activity#onStart onStart()}</code></td>
1291 <td>Called just before the activity becomes visible to the user.
1292 <p>Followed by {@code onResume()} if the activity comes
1293 to the foreground, or {@code onStop()} if it becomes hidden.</p></td>
1294 <td align="center">No</td>
1295 <td align="center">{@code onResume()} <br/>or<br/> {@code onStop()}</td>
1299 <td rowspan="2" style="border-left: none;"> </td>
1300 <td align="left"><code>{@link android.app.Activity#onResume onResume()}</code></td>
1301 <td>Called just before the activity starts
1302 interacting with the user. At this point the activity is at
1303 the top of the activity stack, with user input going to it.
1304 <p>Always followed by {@code onPause()}.</p></td>
1305 <td align="center">No</td>
1306 <td align="center">{@code onPause()}</td>
1310 <td align="left"><code>{@link android.app.Activity#onPause onPause()}</code></td>
1311 <td>Called when the system is about to start resuming another
1312 activity. This method is typically used to commit unsaved changes to
1313 persistent data, stop animations and other things that may be consuming
1314 CPU, and so on. It should do whatever it does very quickly, because
1315 the next activity will not be resumed until it returns.
1316 <p>Followed either by {@code onResume()} if the activity
1317 returns back to the front, or by {@code onStop()} if it becomes
1318 invisible to the user.</td>
1319 <td align="center"><strong style="color:#800000">Yes</strong></td>
1320 <td align="center">{@code onResume()} <br/>or<br/> {@code onStop()}</td>
1324 <td colspan="2" align="left"><code>{@link android.app.Activity#onStop onStop()}</code></td>
1325 <td>Called when the activity is no longer visible to the user. This
1326 may happen because it is being destroyed, or because another activity
1327 (either an existing one or a new one) has been resumed and is covering it.
1328 <p>Followed either by {@code onRestart()} if
1329 the activity is coming back to interact with the user, or by
1330 {@code onDestroy()} if this activity is going away.</p></td>
1331 <td align="center"><strong style="color:#800000">Yes</strong></td>
1332 <td align="center">{@code onRestart()} <br/>or<br/> {@code onDestroy()}</td>
1336 <td colspan="3" align="left"><code>{@link android.app.Activity#onDestroy
1337 onDestroy()}</code></td>
1338 <td>Called before the activity is destroyed. This is the final call
1339 that the activity will receive. It could be called either because the
1340 activity is finishing (someone called <code>{@link android.app.Activity#finish
1341 finish()}</code> on it), or because the system is temporarily destroying this
1342 instance of the activity to save space. You can distinguish
1343 between these two scenarios with the <code>{@link
1344 android.app.Activity#isFinishing isFinishing()}</code> method.</td>
1345 <td align="center"><strong style="color:#800000">Yes</strong></td>
1346 <td align="center"><em>nothing</em></td>
1352 Note the <b>Killable</b> column in the table above. It indicates
1353 whether or not the system can kill the process hosting the activity
1354 <em>at any time after the method returns, without executing another
1355 line of the activity's code</em>. Three methods ({@code onPause()},
1356 {@code onStop()}, and {@code onDestroy()}) are marked "Yes." Because
1357 {@code onPause()} is the first of the three, it's the only one that's
1358 guaranteed to be called before the process is killed —
1359 {@code onStop()} and {@code onDestroy()} may not be. Therefore, you
1360 should use {@code onPause()} to write any persistent data (such as user
1365 Methods that are marked "No" in the <b>Killable</b> column protect the
1366 process hosting the activity from being killed from the moment they are
1367 called. Thus an activity is in a killable state, for example, from the
1368 time {@code onPause()} returns to the time {@code onResume()} is called.
1369 It will not again be killable until {@code onPause()} again returns.
1373 As noted in a later section, <a href="#proclife">Processes and lifecycle</a>,
1374 an activity that's not technically "killable" by this definition might
1375 still be killed by the system — but that would happen only in
1376 extreme and dire circumstances when there is no other recourse.
1380 <h4 id="actstate">Saving activity state</h4>
1383 When the system, rather than the user, shuts down an activity to conserve
1384 memory, the user may expect to return to the activity and find it in its
1389 To capture that state before the activity is killed, you can implement
1390 an <code>{@link android.app.Activity#onSaveInstanceState
1391 onSaveInstanceState()}</code> method for the activity. Android calls this
1392 method before making the activity vulnerable to being destroyed —
1393 that is, before {@code onPause()} is called. It
1394 passes the method a {@link android.os.Bundle} object where you can record
1395 the dynamic state of the activity as name-value pairs. When the activity is
1396 again started, the Bundle is passed both to {@code onCreate()} and to a
1397 method that's called after {@code onStart()}, <code>{@link
1398 android.app.Activity#onRestoreInstanceState onRestoreInstanceState()}</code>,
1399 so that either or both of them can recreate the captured state.
1403 Unlike {@code onPause()} and the other methods discussed earlier,
1404 {@code onSaveInstanceState()} and {@code onRestoreInstanceState()} are
1405 not lifecycle methods. They are not always called. For example, Android
1406 calls {@code onSaveInstanceState()} before the activity becomes
1407 vulnerable to being destroyed by the system, but does not bother
1408 calling it when the instance is actually being destroyed by a user action
1409 (such as pressing the BACK key). In that case, the user won't expect to
1410 return to the activity, so there's no reason to save its state.
1414 Because {@code onSaveInstanceState()} is not always called, you should
1415 use it only to record the transient state of the activity, not to store
1416 persistent data. Use {@code onPause()} for that purpose instead.
1420 <h4 id="coordact">Coordinating activities</h4>
1423 When one activity starts another, they both experience lifecycle
1424 transitions. One pauses and may stop, while the other starts up.
1425 On occasion, you may need to coordinate these activities, one with
1430 The order of lifecycle callbacks is well defined,
1431 particularly when the two activities are in the same process:
1435 <li>The current activity's {@code onPause()} method is called.</li>
1437 <li>Next, the starting activity's {@code onCreate()}, {@code onStart()},
1438 and {@code onResume()} methods are called in sequence.</li>
1440 <li>Then, if the starting activity is no longer visible
1441 on screen, its {@code onStop()} method is called.</li>
1445 <h3 id="servlife">Service lifecycle</h3>
1448 A service can be used in two ways:
1452 <li>It can be started and allowed to run until someone stops it or
1453 it stops itself. In this mode, it's started by calling
1454 <code>{@link android.content.Context#startService Context.startService()}</code>
1455 and stopped by calling
1456 <code>{@link android.content.Context#stopService Context.stopService()}</code>.
1457 It can stop itself by calling
1458 <code>{@link android.app.Service#stopSelf() Service.stopSelf()}</code> or
1459 <code>{@link android.app.Service#stopSelfResult Service.stopSelfResult()}</code>.
1460 Only one {@code stopService()} call is needed to stop the service, no matter how
1461 many times {@code startService()} was called.</li>
1463 <li><p>It can be operated programmatically using an interface that
1464 it defines and exports. Clients establish a connection to the Service
1465 object and use that connection to call into the service. The connection is
1466 established by calling
1467 <code>{@link android.content.Context#bindService Context.bindService()}</code>,
1468 and is closed by calling
1469 <code>{@link android.content.Context#unbindService Context.unbindService()}</code>.
1470 Multiple clients can bind to the same service.
1471 If the service has not already been launched, {@code bindService()} can optionally
1477 The two modes are not entirely separate. You can bind to a service that
1478 was started with {@code startService()}. For example, a background music
1479 service could be started by calling {@code startService()} with an Intent
1480 object that identifies the music to play. Only later, possibly when the
1481 user wants to exercise some control over the player or get information
1482 about the current song, would an activity
1483 establish a connection to the service by calling {@code bindService()}.
1484 In cases like this, {@code stopService()}
1485 will not actually stop the service until the last binding is closed.
1489 Like an activity, a service has lifecycle methods that you can implement
1490 to monitor changes in its state. But they are fewer than the activity
1491 methods — only three — and they are public, not protected:
1494 <p style="margin-left: 2em">{@code void onCreate()}
1495 <br/>{@code void onStart(Intent <i>intent</i>)}
1496 <br/>{@code void onDestroy()}</p>
1499 By implementing these methods, you can monitor two nested loops of the
1500 service's lifecycle:
1504 <li>The <b>entire lifetime</b> of a service happens between the time
1505 <code>{@link android.app.Service#onCreate onCreate()}</code> is called and
1506 the time <code>{@link android.app.Service#onDestroy}</code> returns.
1507 Like an activity, a service does its initial setup in {@code onCreate()},
1508 and releases all remaining resources in {@code onDestroy()}. For example,
1509 a music playback service could create the thread where the music will be played
1510 in {@code onCreate()}, and then stop the thread in {@code onDestroy()}.</li>
1512 <li><p>The <b>active lifetime</b> of a service begins with a call to
1513 <code>{@link android.app.Service#onStart onStart()}</code>. This method
1514 is handed the Intent object that was passed to {@code startService()}.
1515 The music service would open the Intent to discover which music to
1516 play, and begin the playback.</p>
1519 There's no equivalent callback for when the service stops — no
1520 {@code onStop()} method.
1525 The {@code onCreate()} and {@code onDestroy()} methods are called for all
1526 services, whether they're started by
1527 <code>{@link android.content.Context#startService Context.startService()}</code>
1529 <code>{@link android.content.Context#bindService Context.bindService()}</code>.
1530 However, {@code onStart()} is called only for services started by {@code
1535 If a service permits others to
1536 bind to it, there are additional callback methods for it to implement:
1539 <p style="margin-left: 2em">{@code IBinder onBind(Intent <i>intent</i>)}
1540 <br/>{@code boolean onUnbind(Intent <i>intent</i>)}
1541 <br/>{@code void onRebind(Intent <i>intent</i>)}</p>
1544 The <code>{@link android.app.Service#onBind onBind()}</code> callback is passed
1545 the Intent object that was passed to {@code bindService} and
1546 <code>{@link android.app.Service#onUnbind onUnbind()}</code> is handed
1547 the intent that was passed to {@code unbindService()}.
1548 If the service permits the binding, {@code onBind()}
1549 returns the communications channel that clients use to interact with the service.
1550 The {@code onUnbind()} method can ask for
1551 <code>{@link android.app.Service#onRebind onRebind()}</code>
1552 to be called if a new client connects to the service.
1556 The following diagram illustrates the callback methods for a service.
1557 Although, it separates services that are created via {@code startService}
1558 from those created by {@code bindService()}, keep in mind that any service,
1559 no matter how it's started, can potentially allow clients to bind to it,
1560 so any service may receive {@code onBind()} and {@code onUnbind()} calls.
1563 <p style="margin-left: 2em"><img src="{@docRoot}images/service_lifecycle.png"
1564 alt="State diagram for Service callbacks." /></p>
1567 <h3 id="broadlife">Broadcast receiver lifecycle</h3>
1570 A broadcast receiver has single callback method:
1573 <p style="margin-left: 2em">{@code void onReceive(Context <i>curContext</i>, Intent <i>broadcastMsg</i>)}</p>
1576 When a broadcast message arrives for the receiver, Android calls its
1577 <code>{@link android.content.BroadcastReceiver#onReceive onReceive()}</code>
1578 method and passes it the Intent object containing the message. The broadcast
1579 receiver is considered to be active only while it is executing this method.
1580 When {@code onReceive()} returns, it is inactive.
1584 A process with an active broadcast receiver is protected from being killed.
1585 But a process with only inactive components can be killed by the system at
1586 any time, when the memory it consumes is needed by other processes.
1590 This presents a problem when the response to a broadcast message is time
1591 consuming and, therefore, something that should be done in a separate thread,
1592 away from the main thread where other components of the user interface run.
1593 If {@code onReceive()} spawns the thread and then returns, the entire process,
1594 including the new thread, is judged to be inactive (unless other application
1595 components are active in the process), putting it in jeopardy of being killed.
1596 The solution to this problem is for {@code onReceive()} to start a service
1597 and let the service do the job, so the
1598 system knows that there is still active work being done in the process.
1602 The next section has more on the vulnerability of processes to being killed.
1606 <h3 id="proclife">Processes and lifecycles</h3>
1608 <p>The Android system tries to maintain an application process for as
1609 long as possible, but eventually it will need to remove old processes when
1610 memory runs low. To determine which processes to keep and which to kill,
1611 Android places each process into an "importance hierarchy" based on the
1612 components running in it and the state of those components. Processes
1613 with the lowest importance are eliminated first, then those with the next
1614 lowest, and so on. There are five levels in the hierarchy. The following
1615 list presents them in order of importance:
1620 <li>A <b>foreground process</b> is one that is required for
1621 what the user is currently doing. A process is considered to be
1622 in the foreground if any of the following conditions hold:
1625 <li>It is running an activity that the user is interacting with
1626 (the Activity object's <code>{@link android.app.Activity#onResume
1627 onResume()}</code> method has been called).</li>
1629 <li><p>It hosts a service that's bound
1630 to the activity that the user is interacting with.</p></li>
1632 <li><p>It has a {@link android.app.Service} object that's executing
1633 one of its lifecycle callbacks (<code>{@link android.app.Service#onCreate
1634 onCreate()}</code>, <code>{@link android.app.Service#onStart onStart()}</code>,
1635 or <code>{@link android.app.Service#onDestroy onDestroy()}</code>).</p></li>
1637 <li><p>It has a {@link android.content.BroadcastReceiver} object that's
1638 executing its <code>{@link android.content.BroadcastReceiver#onReceive
1639 onReceive()}</code> method.</p></li>
1643 Only a few foreground processes will exist at any given time. They
1644 are killed only as a last resort — if memory is so low that
1645 they cannot all continue to run. Generally, at that point, the device has
1646 reached a memory paging state, so killing some foreground processes is
1647 required to keep the user interface responsive.
1650 <li><p>A <b>visible process</b> is one that doesn't have any foreground
1651 components, but still can affect what the user sees on screen.
1652 A process is considered to be visible if either of the following conditions
1656 <li>It hosts an activity that is not in the foreground, but is still visible
1657 to the user (its <code>{@link android.app.Activity#onPause onPause()}</code>
1658 method has been called). This may occur, for example, if the foreground
1659 activity is a dialog that allows the previous activity to be seen behind it.</li>
1661 <li><p>It hosts a service that's bound to a visible activity.</p></li>
1665 A visible process is considered extremely important and will not be killed
1666 unless doing so is required to keep all foreground processes running.
1669 <li><p>A <b>service process</b> is one that is running a service that
1670 has been started with the
1671 <code>{@link android.content.Context#startService startService()}</code>
1672 method and that does not fall into either of the two higher categories.
1673 Although service processes are not directly tied to anything the
1674 user sees, they are generally doing things that the user cares about (such
1675 as playing an mp3 in the background or downloading data on the network),
1676 so the system keeps them running unless there's not enough
1677 memory to retain them along with all foreground and visible processes.
1680 <li><p>A <b>background process</b> is one holding an activity
1681 that's not currently visible to the user (the Activity object's
1682 <code>{@link android.app.Activity#onStop onStop()}</code> method has been called).
1683 These processes have no direct impact on the user experience, and can be killed
1684 at any time to reclaim memory for a foreground, visible, or service process.
1685 Usually there are many background processes running, so they are kept in an
1686 LRU (least recently used) list to ensure that the process with the activity that
1687 was most recently seen by the user is the last to be killed.
1688 If an activity implements its lifecycle methods correctly, and captures its current
1689 state, killing its process will not have a deleterious effect on the user experience.
1692 <li><p>An <b>empty process</b> is one that doesn't hold any active application
1693 components. The only reason to keep such a process around is as a cache to
1694 improve startup time the next time a component needs to run in it. The system
1695 often kills these processes in order to balance overall system resources between
1696 process caches and the underlying kernel caches.</p></li>
1701 Android ranks a process at the highest level it can, based upon the
1702 importance of the components currently active in the process. For example,
1703 if a process hosts a service and a visible activity, the process will be
1704 ranked as a visible process, not a service process.
1708 In addition, a process's ranking may be increased because other processes are
1709 dependent on it. A process that is serving another process can never be
1710 ranked lower than the process it is serving. For example, if a content
1711 provider in process A is serving a client in process B, or if a service in
1712 process A is bound to a component in process B, process A will always be
1713 considered at least as important as process B.
1717 Because a process running a service is ranked higher than one with background
1718 activities, an activity that initiates a long-running operation might do
1719 well to start a service for that operation, rather than simply spawn a thread
1720 — particularly if the operation will likely outlast the activity.
1721 Examples of this are playing music in the background
1722 and uploading a picture taken by the camera to a web site. Using a service
1723 guarantees that the operation will have at least "service process" priority,
1724 regardless of what happens to the activity. As noted in the
1725 <a href="#broadlife">Broadcast receiver lifecycle</a> section earlier, this
1726 is the same reason that broadcast receivers should employ services rather
1727 than simply put time-consuming operations in a thread.