<div id="qv-wrapper">
<div id="qv">
+<h2>Quickview</h2>
+<ul>
+ <li>Android applications are composed of one or more application components (activities,
+services, content providers, and broadcast receivers)</li>
+ <li>Each component performs a different role in the overall application behavior, and each
+one can be activated individually (even by other applications)</li>
+ <li>The manifest file must declare all components in the application and should also declare
+all application requirements, such as the minimum version of Android required and any hardware
+configurations required</li>
+ <li>Non-code application resources (images, strings, layout files, etc.) should include
+alternatives for different device configurations (such as different strings for different
+languages and different layouts for different screen sizes)</li>
+</ul>
+
+
<h2>In this document</h2>
<ol>
-<li><a href="#appcomp">Application Components</a>
- <ol>
- <li><a href="#actcomp">Activating components: intents</a></li>
- <li><a href="#endcomp">Shutting down components</a></li>
- <li><a href="#manfile">The manifest file</a></li>
- <li><a href="#ifilters">Intent filters</a></li>
- </ol></li>
-<li><a href="#acttask">Activities and Tasks</a>
+<li><a href="#Components">Application Components</a>
<ol>
- <li><a href="#afftask">Affinities and new tasks</a></li>
- <li><a href="#lmodes">Launch modes</a></li>
- <li><a href="#clearstack">Clearing the stack</a></li>
- <li><a href="#starttask">Starting tasks</a></li>
- <li><a href="#commonpatterns">Common patterns</a></li>
- </ol></li>
-<li><a href="#procthread">Processes and Threads</a>
- <ol>
- <li><a href="#procs">Processes</a></li>
- <li><a href="#threads">Threads</a></li>
- <li><a href="#rpc">Remote procedure calls</a></li>
- <li><a href="#tsafe">Thread-safe methods</a></li>
- </ol></li>
-<li><a href="#lcycles">Component Lifecycles</a>
+ <li><a href="#ActivatingComponents">Activating components</a></li>
+ </ol>
+</li>
+<li><a href="#Manifest">The Manifest File</a>
<ol>
- <li><a href="#actlife">Activity lifecycle</a></li>
- <li><a href="#servlife">Service lifecycle</a></li>
- <li><a href="#broadlife">Broadcast receiver lifecycle</a></li>
- <li><a href="#proclife">Processes and lifecycles</a></li>
- </ol></li>
-</ol>
-
-<h2>Key classes</h2>
-<ol>
-<li>{@link android.app.Activity}</li>
-<li>{@link android.app.Service}</li>
-<li>{@link android.content.BroadcastReceiver}</li>
-<li>{@link android.content.ContentProvider}</li>
-<li>{@link android.content.Intent}</li>
+ <li><a href="#DeclaringComponents">Declaring components</a></li>
+ <li><a href="#DeclaringRequirements">Declaring application requirements</a></li>
+ </ol>
+</li>
+<li><a href="#Resources">Application Resources</a></li>
</ol>
-
</div>
</div>
-<p>
-Android applications are written in the Java programming language.
-The compiled Java code — along with any data and resource
-files required by the application — is bundled into an
-<i>Android package</i>, an archive file
-marked by an {@code .apk} suffix. This file is the vehicle
-for distributing the application and installing it on mobile devices;
-it's the file users download to their devices. All the code in a
-single {@code .apk} file is considered to be one <i>application</i>.
-</p>
-
-<p>
-In many ways, each Android application lives in its own world:
-</p>
-
-<ul>
-<li>By default, every application runs in its own Linux process.
-Android starts the process when any of the application's code needs to be
-executed, and shuts down the process when it's no longer needed and system
-resources are required by other applications.</li>
-
-<li>Each process has its own virtual machine (VM), so application code
-runs in isolation from the code of all other applications.</li>
-
-<li>By default, each application is assigned a unique Linux user ID.
-Permissions are set so that the application's files are visible only to
-that user and only to the application itself — although there are ways
-to export them to other applications as well.</li>
-</ul>
-
-<p>
-It's possible to arrange for two applications to share the same user ID,
-in which case they will be able to see each other's files. To conserve
-system resources, applications with the same ID can also arrange to run
-in the same Linux process, sharing the same VM.
-</p>
-
-
-<h2 id="appcomp">Application Components</h2>
-
-<p>
-A central feature of Android is that one application can make use of elements
-of other applications (provided those applications permit it). For example,
-if your application needs to display a scrolling list of images and another
-application has developed a suitable scroller and made it available to others,
-you can call upon that scroller to do the work, rather than develop your own.
-Your application doesn't incorporate the code of the other application or
-link to it. Rather, it simply starts up that piece of the other application
-when the need arises.
-</p>
-
-<p>
-For this to work, the system must be able to start an application process
-when any part of it is needed, and instantiate the Java objects for that part.
-Therefore, unlike applications on most other systems, Android applications don't
-have a single entry point for everything in the application (no {@code main()}
-function, for example). Rather, they have essential <i>components</i> that
-the system can instantiate and run as needed. There are four types of components:
-</p>
-
-<dl>
-
-<dt><b>Activities</b></dt>
-<dd>An <i>activity</i> presents a visual user interface for one focused endeavor
-the user can undertake. For example, an activity might present a list of
-menu items users can choose from or it might display photographs along
-with their captions. A text messaging application might have one activity
-that shows a list of contacts to send messages to, a second activity to write
-the message to the chosen contact, and other activities to review old messages
-or change settings. Though they work together to form a cohesive user interface,
-each activity is independent of the others.
-Each one is implemented as a subclass of the {@link android.app.Activity} base class.
-
-<p>
-An application might consist of just one activity or, like the text messaging
-application just mentioned, it may contain several.
-What the activities are, and how many there are depends, of course, on the
-application and its design. Typically, one of the activities is marked
-as the first one that should be presented to the user when the application is
-launched. Moving from one activity to another is accomplished by having the
-current activity start the next one.
-</p>
-
-<p>
-Each activity is given a default window to draw in. Typically, the window
-fills the screen, but it might be smaller than the screen and float on top
-of other windows. An activity can also make use of additional windows —
-for example, a pop-up dialog that calls for a user response in the midst of
-the activity, or a window that presents users with vital information when they
-select a particular item on-screen.
-</p>
-
-<p>
-The visual content of the window is provided by a hierarchy of views —
-objects derived from the base {@link android.view.View} class. Each view
-controls a particular rectangular space within the window. Parent views
-contain and organize the layout of their children. Leaf views (those at the
-bottom of the hierarchy) draw in the rectangles they control and respond to
-user actions directed at that space. Thus, views are where the activity's
-interaction with the user takes place. For example, a view might display
-a small image and initiate an action when the user taps that image. Android
-has a number of ready-made views that you can use — including buttons,
-text fields, scroll bars, menu items, check boxes, and more.
-</p>
-
-<p>
-A view hierarchy is placed within an activity's window by the
-<code>{@link android.app.Activity#setContentView Activity.setContentView()}</code>
-method. The <i>content view</i> is the View object at the root of the hierarchy.
-(See the separate <a href="{@docRoot}guide/topics/ui/index.html">User Interface</a>
-document for more information on views and the hierarchy.)
-</p>
-
-<p><dt><b>Services</b></dt>
-<dd>A <i>service</i> doesn't have a visual user interface, but rather runs in
-the background for an indefinite period of time. For example, a service might
-play background music as the user attends to other matters, or it might fetch
-data over the network or calculate something and provide the result to activities
-that need it. Each service extends the {@link android.app.Service} base class.
-
-<p>
-A prime example is a media player playing songs from a play list. The player
-application would probably have one or more activities that allow the user to
-choose songs and start playing them. However, the music playback itself would
-not be handled by an activity because users will expect the music to keep
-playing even after they leave the player and begin something different.
-To keep the music going, the media player activity could start a service to run
-in the background. The system would then keep the music playback service running
-even after the activity that started it leaves the screen.
-</p>
-
-<p>
-It's possible to connect to (bind to) an ongoing service (and start the service
-if it's not already running). While connected, you can communicate with the
-service through an interface that the service exposes. For the music service,
-this interface might allow users to pause, rewind, stop, and restart the playback.
-</p>
-
-<p>
-Like activities and the other components, services run in the main thread of
-the application process. So that they won't block other components or the
-user interface, they often spawn another thread for time-consuming tasks
-(like music playback). See <a href="#procthread">Processes and Threads</a>, later.
-</p></dd>
-
-<dt><b>Broadcast receivers</b></dt>
-<dd>A <i>broadcast receiver</i> is a component that does nothing but
-receive and react to broadcast announcements. Many broadcasts originate in
-system code — for example, announcements that the timezone has changed,
-that the battery is low, that a picture has been taken, or that the user
-changed a language preference. Applications can also initiate broadcasts
-— for example, to let other applications know that some data has been
-downloaded to the device and is available for them to use.
-
-<p>
-An application can have any number of broadcast receivers to respond to any
-announcements it considers important. All receivers extend the {@link
-android.content.BroadcastReceiver} base class.
-</p>
-
-<p>
-Broadcast receivers do not display a user interface. However, they may start
-an activity in response to the information they receive, or they may use
-the {@link android.app.NotificationManager} to alert the user. Notifications
-can get the user's attention in various ways — flashing
-the backlight, vibrating the device, playing a sound, and so on. They
-typically place a persistent icon in the status bar, which users can open to
-get the message.
-</p></dd>
+<p>Android applications are written in the Java programming language. The Android SDK tools compile
+the code—along with any data and resource files—into an <i>Android package</i>, an
+archive file with an {@code .apk} suffix. All the code in a single {@code .apk} file is considered
+to be one application and is the file that Android-powered devices use to install the
+application.</p>
-<dt><b>Content providers</b></dt>
-<dd>A <i>content provider</i> makes a specific set of the application's data
-available to other applications. The data can be stored in the file system,
-in an SQLite database, or in any other manner that makes sense.
-The content provider extends the {@link android.content.ContentProvider} base
-class to implement a standard set of methods that enable other applications
-to retrieve and store data of the type it controls. However, applications
-do not call these methods directly. Rather they use a {@link
-android.content.ContentResolver} object and call its methods instead.
-A ContentResolver can talk to any content provider; it cooperates with the
-provider to manage any interprocess communication that's involved.
-
-<p>
-See the separate
-<a href="{@docRoot}guide/topics/providers/content-providers.html">Content
-Providers</a> document for more information on using content providers.
-</p></dd>
-
-</dl>
-
-<p>
-Whenever there's a request that should be handled by a particular component,
-Android makes sure that the application process of the component is running,
-starting it if necessary, and that an appropriate instance of the component
-is available, creating the instance if necessary.
-</p>
-
-
-<h3 id="actcomp">Activating components: intents</h3>
-
-<p>
-Content providers are activated when they're targeted by a request from a
-ContentResolver. The other three components — activities, services,
-and broadcast receivers — are activated by asynchronous messages
-called <i>intents</i>. An intent is an {@link android.content.Intent}
-object that holds the content of the message. For activities and services,
-it names the action being requested and specifies the URI of the data to
-act on, among other things. For example, it might convey a request for
-an activity to present an image to the user or let the user edit some
-text. For broadcast receivers, the Intent object names the action being
-announced. For example, it might announce to interested parties that the
-camera button has been pressed.
-</p>
-
-<p>
-There are separate methods for activating each type of component:
-</p>
+<p>Once installed on a device, each Android application lives in its own security sandbox: </p>
<ul>
+ <li>The Android operating system is a multi-user Linux system in which each application is a
+different user.</li>
-<li>An activity is launched (or given something new to do) by passing an
-Intent object to <code>{@link android.content.Context#startActivity
-Context.startActivity()}</code> or <code>{@link
-android.app.Activity#startActivityForResult
-Activity.startActivityForResult()}</code>. The responding activity can
-look at the initial intent that caused it to be launched by calling its
-<code>{@link android.app.Activity#getIntent getIntent()}</code> method.
-Android calls the activity's <code>{@link
-android.app.Activity#onNewIntent onNewIntent()}</code> method to pass
-it any subsequent intents.
-
-<p>
-One activity often starts the next one. If it expects a result back from
-the activity it's starting, it calls {@code startActivityForResult()}
-instead of {@code startActivity()}. For example, if it starts an activity
-that lets the user pick a photo, it might expect to be returned the chosen
-photo. The result is returned in an Intent object that's passed to the
-calling activity's <code>{@link android.app.Activity#onActivityResult
-onActivityResult()}</code> method.
-</p>
-</li>
+<li>By default, the system assigns each application a unique Linux user ID (the ID is used only by
+the system and is unknown to the application). The system sets permissions for all the files in an
+application so that only the user ID assigned to that application can access them. </li>
-<li><p>A service is started (or new instructions are given to an ongoing
-service) by passing an Intent object to <code>{@link
-android.content.Context#startService Context.startService()}</code>.
-Android calls the service's <code>{@link android.app.Service#onStartCommand
-onStartCommand()}</code> method and passes it the Intent object.</p>
-
-<p>
-Similarly, an intent can be passed to <code>{@link
-android.content.Context#bindService Context.bindService()}</code> to
-establish an ongoing connection between the calling component and a
-target service. The service receives the Intent object in
-an <code>{@link android.app.Service#onBind onBind()}</code> call.
-(If the service is not already running, {@code bindService()} can
-optionally start it.) For example, an activity might establish a connection
-with the music playback service mentioned earlier so that it can provide
-the user with the means (a user interface) for controlling the playback.
-The activity would call {@code bindService()} to set up that connection,
-and then call methods defined by the service to affect the playback.
-</p>
-
-<p>
-A later section, <a href="#rpc">Remote procedure calls</a>, has more details
-about binding to a service.
-</p>
-</li>
-
-<li><p>An application can initiate a broadcast by passing an Intent object to
-methods like <code>{@link
-android.content.Context#sendBroadcast(Intent) Context.sendBroadcast()}</code>,
-<code>{@link android.content.Context#sendOrderedBroadcast(Intent, String)
-Context.sendOrderedBroadcast()}</code>, and <code>{@link
-android.content.Context#sendStickyBroadcast Context.sendStickyBroadcast()}</code>
-in any of their variations. Android delivers the intent to all interested
-broadcast receivers by calling their <code>{@link
-android.content.BroadcastReceiver#onReceive onReceive()}</code> methods.</p></li>
+<li>Each process has its own virtual machine (VM), so an application's code runs in isolation from
+other applications.</li>
+<li>By default, every application runs in its own Linux process. Android starts the process when any
+of the application's components need to be executed, then shuts down the process when it's no longer
+needed or when the system must recover memory for other applications.</li>
</ul>
-<p>
-For more on intent messages, see the separate article,
-<a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents
-and Intent Filters</a>.
-</p>
-
-
-<h3 id="endcomp">Shutting down components</h3>
+<p>In this way, the Android system implements the <em>principle of least privilege</em>. That is,
+each application, by default, has access only to the components that it requires to do its work and
+no more. This creates a very secure environment in which an application cannot access parts of
+the system for which it is not given permission.</p>
-<p>
-A content provider is active only while it's responding to a request from
-a ContentResolver. And a broadcast receiver is active only while it's
-responding to a broadcast message. So there's no need to explicitly shut
-down these components.
-</p>
-
-<p>
-Activities, on the other hand, provide the user interface. They're
-in a long-running conversation with the user and may remain active,
-even when idle, as long as the conversation continues. Similarly, services
-may also remain running for a long time. So Android has methods to shut
-down activities and services in an orderly way:
-</p>
+<p>However, there are ways for an application to share data with other applications and for an
+application to access system services:</p>
<ul>
-<li>An activity can be shut down by calling its
-<code>{@link android.app.Activity#finish finish()}</code> method. One activity can
-shut down another activity (one it started with {@code startActivityForResult()}) by
-calling <code>{@link android.app.Activity#finishActivity finishActivity()}</code>.</li>
-
-<li>A service can be stopped by calling its
-<code>{@link android.app.Service#stopSelf stopSelf()}</code> method, or by calling
-<code>{@link android.content.Context#stopService Context.stopService()}</code>.</li>
+ <li>It's possible to arrange for two applications to share the same Linux user ID, in which case
+they are able to access each other's files. To conserve system resources, applications with the
+same user ID can also arrange to run in the same Linux process and share the same VM (the
+applications must also be signed with the same certificate).</li>
+ <li>An application can request permission to access device data such as the user's
+contacts, SMS messages, the mountable storage (SD card), camera, Bluetooth, and more. All
+application permissions must be granted by the user at install time.</li>
</ul>
-<p>
-Components might also be shut down by the system when they are no longer being
-used or when Android must reclaim memory for more active components. A later
-section, <a href="#lcycles">Component Lifecycles</a>, discusses this
-possibility and its ramifications in more detail.
-</p>
-
-
-<h3 id="manfile">The manifest file</h3>
-
-<p>
-Before Android can start an application component, it must learn that
-the component exists. Therefore, applications declare their components
-in a manifest file that's bundled into the Android package, the {@code .apk}
-file that also holds the application's code, files, and resources.
-</p>
-
-<p>
-The manifest is a structured XML file and is always named AndroidManifest.xml
-for all applications. It does a number of things in addition to declaring the
-application's components, such as naming any libraries the application needs
-to be linked against (besides the default Android library) and identifying
-any permissions the application expects to be granted.
-</p>
-
-<p>
-But the principal task of the manifest is to inform Android about the application's
-components. For example, an activity might be declared as follows:
-</p>
-
-<pre><?xml version="1.0" encoding="utf-8"?>
-<manifest . . . >
- <application . . . >
- <activity android:name="com.example.project.FreneticActivity"
- android:icon="@drawable/small_pic.png"
- android:label="@string/freneticLabel"
- . . . >
- </activity>
- . . .
- </application>
-</manifest></pre>
-
-<p>
-The {@code name} attribute of the
-<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>
-element names the {@link android.app.Activity} subclass that implements the
-activity. The {@code icon} and {@code label} attributes point to
-resource files containing an icon and label that can be displayed
-to users to represent the activity.
-</p>
-
-<p>
-The other components are declared in a similar way —
-<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>
-elements for services,
-<code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code>
-elements for broadcast receivers, and
-<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code>
-elements for content providers. Activities, services, and content providers
-that are not declared in the manifest are not visible to the system and are
-consequently never run. However, broadcast receivers can either be
-declared in the manifest, or they can be created dynamically in code
-(as {@link android.content.BroadcastReceiver} objects)
-and registered with the system by calling
-<code>{@link android.content.Context#registerReceiver Context.registerReceiver()}</code>.
-</p>
-
-<p>
-For more on how to structure a manifest file for your application, see
-<a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The
-AndroidManifest.xml File</a>.
-</p>
-
-
-<h3 id="ifilters">Intent filters</h3>
-
-<p>
-An Intent object can explicitly name a target component. If it does,
-Android finds that component (based on the declarations in the manifest
-file) and activates it. But if a target is not explicitly named,
-Android must locate the best component to respond to the intent.
-It does so by comparing the Intent object to the <i>intent filters</i>
-of potential targets. A component's intent filters inform Android of
-the kinds of intents the component is able to handle. Like other
-essential information about the component, they're declared in the
-manifest file. Here's an extension of the previous example that adds
-two intent filters to the activity:
-</p>
-
-<pre><?xml version="1.0" encoding="utf-8"?>
-<manifest . . . >
- <application . . . >
- <activity android:name="com.example.project.FreneticActivity"
- android:icon="@drawable/small_pic.png"
- android:label="@string/freneticLabel"
- . . . >
- <intent-filter . . . >
- <action android:name="android.intent.action.MAIN" />
- <category android:name="android.intent.category.LAUNCHER" />
- </intent-filter>
- <intent-filter . . . >
- <action android:name="com.example.project.BOUNCE" />
- <data android:mimeType="image/jpeg" />
- <category android:name="android.intent.category.DEFAULT" />
- </intent-filter>
- </activity>
- . . .
- </application>
-</manifest></pre>
-
-<p>
-The first filter in the example — the combination of the action
-"{@code android.intent.action.MAIN}" and the category
-"{@code android.intent.category.LAUNCHER}" — is a common one.
-It marks the activity as one that should be represented in the
-application launcher, the screen listing applications users can launch
-on the device. In other words, the activity is the entry point for
-the application, the initial one users would see when they choose
-the application in the launcher.
-</p>
-
-<p>
-The second filter declares an action that the activity can perform on
-a particular type of data.
-</p>
-
-<p>
-A component can have any number of intent filters, each one declaring a
-different set of capabilities. If it doesn't have any filters, it can
-be activated only by intents that explicitly name the component as the
-target.
-</p>
-
-<p>
-For a broadcast receiver that's created and registered in code, the
-intent filter is instantiated directly as an {@link android.content.IntentFilter}
-object. All other filters are set up in the manifest.
-</p>
-
-<p>
-For more on intent filters, see a separate document,
-<a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents
-and Intent Filters</a>.
-</p>
-
-
-<h2 id="acttask">Activities and Tasks</h2>
-
-<p>
-As noted earlier, one activity can start another, including one defined
-in a different application. Suppose, for example, that you'd like
-to let users display a street map of some location. There's already an
-activity that can do that, so all your activity needs to do is put together
-an Intent object with the required information and pass it to
-{@code startActivity()}. The map viewer will display the map. When the user
-hits the BACK key, your activity will reappear on screen.
-</p>
-
-<p>
-To the user, it will seem as if the map viewer is part of the same application
-as your activity, even though it's defined in another application and runs in
-that application's process. Android maintains this user experience by keeping
-both activities in the same <i>task</i>. Simply put, a task is what the user
-experiences as an "application." It's a group of related activities, arranged
-in a stack. The root activity in the stack is the one that began the task
-— typically, it's an activity the user selected in the application launcher.
-The activity at the top of the stack is one that's currently running —
-the one that is the focus for user actions. When one activity starts another,
-the new activity is pushed on the stack; it becomes the running activity.
-The previous activity remains in the stack. When the user presses the BACK key,
-the current activity is popped from the stack, and the previous one resumes as
-the running activity.
-</p>
-
-<p>
-The stack contains objects, so if a task has more than one instance of the same
-Activity subclass open — multiple map viewers, for example — the
-stack has a separate entry for each instance. Activities in the stack are never
-rearranged, only pushed and popped.
-</p>
-
-<p>
-A task is a stack of activities, not a class or an element in the manifest file.
-So there's no way to set values for a task independently of its activities.
-Values for the task as a whole are set in the root activity. For example, the
-next section will talk about the "affinity of a task"; that value is read from
-the affinity set for the task's root activity.
-</p>
-
-<p>
-All the activities in a task move together as a unit. The entire task (the entire
-activity stack) can be brought to the foreground or sent to the background.
-Suppose, for instance, that the current task has four activities in its stack
-— three under the current activity. The user presses the HOME key, goes
-to the application launcher, and selects a new application (actually, a new <i>task</i>).
-The current task goes into the background and the root activity for the new task is displayed.
-Then, after a short period, the user goes back to the home screen and again selects
-the previous application (the previous task). That task, with all four
-activities in the stack, comes forward. When the user presses the BACK
-key, the screen does not display the activity the user just left (the root
-activity of the previous task). Rather, the activity on the top of the stack
-is removed and the previous activity in the same task is displayed.
-</p>
-
-<p>
-The behavior just described is the default behavior for activities and tasks.
-But there are ways to modify almost all aspects of it. The association of
-activities with tasks, and the behavior of an activity within a task, is
-controlled by the interaction between flags set in the Intent object that
-started the activity and attributes set in the activity's
-<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>
-element in the manifest. Both requester and respondent have a say in what happens.
-</p>
-
-<p>
-In this regard, the principal Intent flags are:
-
-<p style="margin-left: 2em">{@code FLAG_ACTIVITY_NEW_TASK}
-<br/>{@code FLAG_ACTIVITY_CLEAR_TOP}
-<br/>{@code FLAG_ACTIVITY_RESET_TASK_IF_NEEDED}
-<br/>{@code FLAG_ACTIVITY_SINGLE_TOP}</p>
-
-<p>
-The principal {@code <activity>} attributes are:
-
-<p style="margin-left: 2em">{@code taskAffinity}
-<br/>{@code launchMode}
-<br/>{@code allowTaskReparenting}
-<br/>{@code clearTaskOnLaunch}
-<br/>{@code alwaysRetainTaskState}
-<br/>{@code finishOnTaskLaunch}</p>
-
-<p>
-The following sections describe what some of these flags and attributes do,
-how they interact, and what considerations should govern their use.
-</p>
-
-
-<h3 id="afftask">Affinities and new tasks</h3>
-
-<p>
-By default, all the activities in an application have an <i>affinity</i> for each
-other — that is, there's a preference for them all to belong to the
-same task. However, an individual affinity can be set for each activity
-with the {@code taskAffinity} attribute of the {@code <activity>} element.
-Activities defined in different applications can share an affinity, or activities
-defined in the same application can be assigned different affinities.
-The affinity comes into play in two circumstances: When the Intent object
-that launches an activity contains the {@code FLAG_ACTIVITY_NEW_TASK} flag,
-and when an activity has its {@code allowTaskReparenting} attribute set
-to "{@code true}".
-</p>
-
-<dl>
-<dt>The <code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code> flag</dt>
-<dd>As described earlier, a new activity is, by default, launched into
-the task of the activity that called {@code startActivity()}. It's pushed
- onto the same stack as the caller. However, if the Intent object passed
-to {@code startActivity()} contains the {@code FLAG_ACTIVITY_NEW_TASK}
-flag, the system looks for a different task to house the new activity.
-Often, as the name of the flag implies, it's a new task. However, it
-doesn't have to be. If there's already an existing task with the same
-affinity as the new activity, the activity is launched into that task. If
-not, it begins a new task.</dd>
-
-<dt>The <code><a
-href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code>
-attribute</dt>
-<dd>If an activity has its {@code allowTaskReparenting} attribute set
-to "{@code true}", it can move from the task it starts in to the task
-it has an affinity for when that task comes to the fore. For example,
-suppose that an activity that reports weather conditions in selected
-cities is defined as part of a travel application. It has the same
-affinity as other activities in the same application (the default
-affinity) and it allows reparenting. One of your activities
-starts the weather reporter, so it initially belongs to the same task as
-your activity. However, when the travel application next comes forward,
-the weather reporter will be reassigned to and displayed with that task.</dd>
-</dl>
-
-<p>
-If an {@code .apk} file contains more than one "application"
-from the user's point of view, you will probably want to assign different
-affinities to the activities associated with each of them.
-</p>
-
-
-<h3 id="lmodes">Launch modes</h3>
-
-<p>
-There are four different launch modes that can be assigned to an {@code
-<activity>} element's
-<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">launchMode</a></code>
-attribute:
-</p>
-
-<p style="margin-left: 2em">"{@code standard}" (the default mode)
-<br>"{@code singleTop}"
-<br>"{@code singleTask}"
-<br>"{@code singleInstance}"</p>
-
-<p>
-The modes differ from each other on these four points:
-</p>
-
+<p>That covers the basics regarding how an Android application exists within the system. The rest of
+this document introduces you to:</p>
<ul>
-
-<li><b>Which task will hold the activity that responds to the intent</b>.
-For the "{@code standard}" and "{@code singleTop}" modes, it's the task that
-originated the intent (and called
-<code>{@link android.content.Context#startActivity startActivity()}</code>)
-— unless the Intent object contains the
-<code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code> flag.
-In that case, a different task is chosen as described in the previous
-section, <a href="#afftask">Affinities and new tasks</a>.
-
-<p>
-In contrast, the "{@code singleTask}" and "{@code singleInstance}" modes mark
-activities that are always at the root of a task. They define a task; they're
-never launched into another task.
-</p>
-
-<li><p><b>Whether there can be multiple instances of the activity</b>.
-A "{@code standard}" or "{@code singleTop}" activity can be instantiated
-many times. They can belong to multiple tasks, and a given task can have
-multiple instances of the same activity.
-</p>
-
-<p>
-In contrast, "{@code singleTask}" and "{@code singleInstance}" activities
-are limited to just one instance. Since these activities are at the root
-of a task, this limitation means that there is never more than a single
-instance of the task on the device at one time.
-</p>
-
-<li><p><b>Whether the instance can have other activities in its task</b>.
-A "{@code singleInstance}" activity stands alone as the only activity in its
-task. If it starts another activity, that activity will be launched into a
-different task regardless of its launch mode — as if {@code
-FLAG_ACTIVITY_NEW_TASK} was in the intent. In all other respects, the
-"{@code singleInstance}" mode is identical to "{@code singleTask}".</p>
-
-<p>
-The other three modes permit multiple activities to belong to the task.
-A "{@code singleTask}" activity will always be the root activity of the task,
-but it can start other activities that will be assigned to its
-task. Instances of "{@code standard}" and "{@code singleTop}"
-activities can appear anywhere in a stack.
-</p></li>
-
-<li><b>Whether a new instance of the class will be launched
-to handle a new intent</b>. For the default "{@code standard}" mode, a
-new instance is created to respond to every new intent. Each instance
-handles just one intent. For the "{@code singleTop}" mode, an existing
-instance of the class is re-used to handle a new intent if it resides
-at the top of the activity stack of the target task. If it does not
-reside at the top, it is not re-used. Instead, a new instance
-is created for the new intent and pushed on the stack.
-
-<p>
-For example, suppose a task's activity stack consists of root activity A with
-activities B, C, and D on top in that order, so the stack is A-B-C-D. An intent
-arrives for an activity of type D. If D has the default "{@code standard}" launch
-mode, a new instance of the class is launched and the stack becomes A-B-C-D-D.
-However, if D's launch mode is "{@code singleTop}", the existing instance is
-expected to handle the new intent (since it's at the top of the stack) and the
-stack remains A-B-C-D.
-</p>
-
-<p>
-If, on the other hand, the arriving intent is for an activity of type B, a new
-instance of B would be launched no matter whether B's mode is "{@code standard}"
-or "{@code singleTop}" (since B is not at the top of the stack), so the resulting
-stack would be A-B-C-D-B.
-</p>
-
-<p>
-As noted above, there's never more than one instance of a "{@code singleTask}"
-or "{@code singleInstance}" activity, so that instance is expected to handle
-all new intents. A "{@code singleInstance}" activity is always at the top of
-the stack (since it is the only activity in the task), so it is always in
-position to handle the intent. However, a "{@code singleTask}" activity may
-or may not have other activities above it in the stack. If it does, it is not
-in position to handle the intent, and the intent is dropped. (Even though the
-intent is dropped, its arrival would have caused the task to come to the
-foreground, where it would remain.)
-</p>
-</li>
-
+ <li>The core framework components that define your application.</li>
+ <li>The manifest file in which you declare components and required device features for your
+application.</li>
+ <li>Resources that are separate from the application code and allow your application to
+gracefully optimize its behavior for a variety of device configurations.</li>
</ul>
-<p>
-When an existing activity is asked to handle a new intent, the Intent
-object is passed to the activity in an
-<code>{@link android.app.Activity#onNewIntent onNewIntent()}</code> call.
-(The intent object that originally started the activity can be retrieved by
-calling <code>{@link android.app.Activity#getIntent getIntent()}</code>.)
-</p>
+<p class="note"><strong>Tip:</strong> If you're new to Android development, we suggest that you
+follow the Beginner's Path link at the bottom of this page. For each document in the Application
+Fundamentals, the Beginner's Path points you to the document we suggest you read next, in order
+to get up to speed on the core Android concepts.</p>
-<p>
-Note that when a new instance of an Activity is created to handle a new
-intent, the user can always press the BACK key to return to the previous state
-(to the previous activity). But when an existing instance of an
-Activity handles a new intent, the user cannot press the BACK key to
-return to what that instance was doing before the new intent arrived.
-</p>
-<p>
-For more on launch modes, see the description of the <code><a
-href="{@docRoot}guide/topics/manifest/activity-element.html#lmode"><activity></a></code>
-element.
-</p>
+<h2 id="Components">Application Components</h2>
-<h3 id="clearstack">Clearing the stack</h3>
+<p>Application components are the essential building blocks of an Android application. Each
+component is a different point through which the system can enter your application. Not all
+components are actual entry points for the user and some depend on each other, but each one exists
+as its own entity and plays a specific role—each one is a unique building block that
+helps define your application's overall behavior.</p>
-<p>
-If the user leaves a task for a long time, the system clears the task of all
-activities except the root activity. When the user returns to the task again,
-it's as the user left it, except that only the initial activity is present.
-The idea is that, after
-a time, users will likely have abandoned what they were doing before and are
-returning to the task to begin something new.
-</p>
+<p>There are four different types of application components. Each type serves a distinct purpose
+and has a distinct lifecycle that defines how the component is created and destroyed.</p>
-<p>
-That's the default. There are some activity attributes that can be used to
-control this behavior and modify it:
-</p>
+<p>Here are the four types of application components:</p>
<dl>
-<dt>The <code><a
-href="{@docRoot}guide/topics/manifest/activity-element.html#always">alwaysRetainTaskState</a></code>
-attribute</dt>
-<dd>If this attribute is set to "{@code true}" in the root activity of a task,
-the default behavior just described does not happen.
-The task retains all activities in its stack even after a long period.</dd>
-
-<dt>The <code><a
-href="{@docRoot}guide/topics/manifest/activity-element.html#clear">clearTaskOnLaunch</a></code>
-attribute</dt>
-<dd>If this attribute is set to "{@code true}" in the root activity of a task,
-the stack is cleared down to the root activity whenever the user leaves the task
-and returns to it. In other words, it's the polar opposite of
-{@code alwaysRetainTaskState}. The user always returns to the task in its
-initial state, even after a momentary absence.</dd>
-
-<dt>The <code><a
-href="{@docRoot}guide/topics/manifest/activity-element.html#finish">finishOnTaskLaunch</a></code>
-attribute</dt>
-<dd>This attribute is like {@code clearTaskOnLaunch}, but it operates on a
-single activity, not an entire task. And it can cause any activity to go
-away, including the root activity. When it's set to "{@code true}", the
-activity remains part of the task only for the current session. If the user
-leaves and then returns to the task, it no longer is present.</dd>
-</dl>
-
-<p>
-There's another way to force activities to be removed from the stack.
-If an Intent object includes the <code>{@link
-android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP FLAG_ACTIVITY_CLEAR_TOP}</code>
-flag, and the target task already has an instance of the type of activity that
-should handle the intent in its stack, all activities above that instance
-are cleared away so that it stands at the top of the stack and can respond
-to the intent.
-If the launch mode of the designated activity is "{@code standard}", it too
-will be removed from the stack, and a new instance will be launched to handle
-the incoming intent. That's because a new instance is always created for
-a new intent when the launch mode is "{@code standard}".
-</p>
-
-<p>
-{@code FLAG_ACTIVITY_CLEAR_TOP} is most often used in conjunction
-with {@code FLAG_ACTIVITY_NEW_TASK}. When used together, these flags are
-a way of locating an existing activity in another task and putting it in
-a position where it can respond to the intent.
-</p>
-
-
-<h3 id="starttask">Starting tasks</h3>
-
-<p>
-An activity is set up as the entry point for a task by giving it
-an intent filter with "{@code android.intent.action.MAIN}" as the
-specified action and "{@code android.intent.category.LAUNCHER}" as
-the specified category. (There's an example of this type of filter
-in the earlier <a href="#ifilters">Intent Filters</a> section.)
-A filter of this kind causes an icon and label for the activity to be
-displayed in the application launcher, giving users a way both to
-launch the task and to return to it at any time after it has been
-launched.
-</p>
-
-<p>
-This second ability is important: Users must be able to leave a task
-and then come back to it later. For this reason, the two launch modes
-that mark activities as always initiating a task, "{@code singleTask}"
-and "{@code singleInstance}", should be used only when the activity has
-a {@code MAIN} and {@code LAUNCHER} filter.
-Imagine, for example, what could happen if the filter is missing:
-An intent launches a "{@code singleTask}" activity, initiating a new task,
-and the user spends some time working in that task. The user then presses
-the HOME key. The task is now ordered behind and obscured by the home
-screen. And, because it is not represented in the application launcher,
-the user has no way to return to it.
-</p>
-
-<p>
-A similar difficulty attends the {@code FLAG_ACTIVITY_NEW_TASK} flag.
-If this flag causes an activity to
-begin a new task and the user presses the HOME key to leave it, there
-must be some way for the user to navigate back to it again. Some
-entities (such as the notification manager) always start activities
-in an external task, never as part of their own, so they always put
-{@code FLAG_ACTIVITY_NEW_TASK} in the intents they pass to
-{@code startActivity()}. If you have an activity that can be invoked
-by an external entity that might use this flag, take care that the user
-has a independent way to get back to the task that's started.
-</p>
-
-<p>
-For those cases where you don't want the user to be able to return
-to an activity, set the {@code <activity>} element's {@code
-finishOnTaskLaunch} to "{@code true}".
-See <a href="#clearstack">Clearing the stack</a>, earlier.
-</p>
-
-
-<h3 id="commonpatterns">Common patterns</h3>
-
-<p>
-In most cases an application won't use any flags or special features.
-This gives the standard interaction the user expects: launching the application
-brings any existing task to the foreground, or starts the main activity in
-a new task if there isn't one.
-</p>
-
-<p>
-If an application posts notifications, it needs to decide how the user's
-selection of a notification should impact any currently running task. The
-current suggested behavior is that any current tasks be completely removed,
-replaced with a new task containing a stack of activities representing where
-the user is jumping in to the app. This can be accomplished with a combination
-of the {@link android.app.PendingIntent#getActivities PendingIntent.getActivities()}
-method and {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TASK Intent.FLAG_ACTIVITY_CLEAR_TASK}.
-</p>
-
-<p>
-For example, here is sample code to build an array of Intents to launch an
-application into an activity three levels deep. The first Intent is always
-the main Intent of the application as started by the launcher. The exact
-details of the Intent data will of course depend on your application.
-</p>
-
-{@sample development/samples/ApiDemos/src/com/example/android/apis/app/StatusBarNotifications.java
- intent_array}
-
-<p>
-In some cases an application may not want to directly launch its application
-from a notification, but instead go to a intermediate summary activity. To
-accomplish this, the summary activity should be given a task affinity that
-is different from the main application (one will typically give it no affinity,
-that is "") so that it does not get launched into any existing application task.
-</p>
-
-{@sample development/samples/ApiDemos/AndroidManifest.xml no_task_affinity}
-
-<p>
-The PendingIntent to launch this then does not need to supply anything special:
-</p>
-
-{@sample development/samples/ApiDemos/src/com/example/android/apis/app/IncomingMessage.java
- pending_intent}
-
-<p>
-If an application implements an app widget, it should generally use the same
-approach as the first one for notifications: when the user taps on the app
-widget it should throw away any current task of the application and start a
-new task with potentially multiple activities representing the state the
-user is jumping in to.
-</p>
-
-<h2 id="procthread">Processes and Threads</h2>
-
-<p>
-When the first of an application's components needs to be run, Android
-starts a Linux process for it with a single thread of execution. By default,
-all components of the application run in that process and thread.
-</p>
-
-<p>
-However, you can arrange for components to run in other processes, and you
-can spawn additional threads for any process.
-</p>
+<dt><b>Activities</b></dt>
-<h3 id="procs">Processes</h3>
-
-<p>
-The process where a component runs is controlled by the manifest file.
-The component elements — {@code <activity>},
-{@code <service>}, {@code <receiver>}, and {@code <provider>}
-— each have a {@code process} attribute that can specify a process
-where that component should run. These attributes can be set so that each
-component runs in its own process, or so that some components share a process
-while others do not. They can also be set so that components of
-different applications run in the same process — provided that the
-applications share the same Linux user ID and are signed by the same authorities.
-The {@code <application>} element also has a {@code process} attribute,
-for setting a default value that applies to all components.
-</p>
-
-<p>
-All components are instantiated in the main thread of the specified
-process, and system calls to the component are dispatched from that
-thread. Separate threads are not created for each instance. Consequently,
-methods that respond to those calls — methods like
-<code>{@link android.view.View#onKeyDown View.onKeyDown()}</code> that report
-user actions and the lifecycle notifications discussed later in the
-<a href="#lcycles">Component Lifecycles</a> section — always run in the
-main thread of the process. This means
-that no component should perform long or blocking operations (such as networking
-operations or computation loops) when called by the system, since this will block
-any other components also in the process. You can spawn separate threads for
-long operations, as discussed under <a href="#threads">Threads</a>, next.
-</p>
-
-<p>
-Android may decide to shut down a process at some point, when memory is
-low and required by other processes that are more immediately serving
-the user. Application components running in the process are consequently
-destroyed. A process is restarted for those components when there's again
-work for them to do.
-</p>
-
-<p>
-When deciding which processes to terminate, Android weighs their relative
-importance to the user. For example, it more readily shuts down a process
-with activities that are no longer visible on screen than a process with
-visible activities.
-The decision whether to terminate a process, therefore, depends on the state
-of the components running in that process. Those states are the subject of
-a later section, <a href="#lcycles">Component Lifecycles</a>.
-</p>
-
+<dd>An <i>activity</i> represents a single screen with a user interface. For example,
+an email application might have one activity that shows a list of new
+emails, another activity to compose an email, and another activity for reading emails. Although
+the activities work together to form a cohesive user experience in the email application, each one
+is independent of the others. As such, a different application can start any one of these
+activities (if the email application allows it). For example, a camera application can start the
+activity in the email application that composes new mail, in order for the user to share a picture.
-<h3 id="threads">Threads</h3>
+<p>An activity is implemented as a subclass of {@link android.app.Activity} and you can learn more
+about it in the <a href="{@docRoot}guide/topics/fundamentals/activities.html">Activities</a>
+developer guide.</p>
+</dd>
-<p>
-Even though you may confine your application to a single process, there will
-likely be times when you will need to spawn a thread to do some background
-work. Since the user interface must always be quick to respond to user actions,
-the thread that hosts an activity should not also host time-consuming operations
-like network downloads. Anything that may not be completed quickly should be
-assigned to a different thread.
-</p>
-<p>
-Threads are created in code using standard Java {@link java.lang.Thread}
-objects. Android provides a number of convenience classes for managing
-threads — {@link android.os.Looper} for running a message loop within
-a thread, {@link android.os.Handler} for processing messages, and
-{@link android.os.HandlerThread} for setting up a thread with a message loop.
-</p>
+<dt><b>Services</b></dt>
+<dd>A <i>service</i> is a component that runs in the background to perform long-running
+operations or to perform work for remote processes. A service
+does not provide a user interface. For example, a service might play music in the background while
+the user is in a different application, or it might fetch data over the network without
+blocking user interaction with an activity. Another component, such as an activity, can start the
+service and let it run or bind to it in order to interact with it.
-<h3 id="rpc">Remote procedure calls</h3>
+<p>A service is implemented as a subclass of {@link android.app.Service} and you can learn more
+about it in the <a href="{@docRoot}guide/topics/fundamentals/services.html">Services</a> developer
+guide.</p>
+</dd>
-<p>
-Android has a lightweight mechanism for remote procedure calls (RPCs)
-— where a method is called locally, but executed remotely (in another
-process), with any result returned back to the caller.
-This entails decomposing the method call and all its attendant data to a
-level the operating system can understand, transmitting it from the local
-process and address space to the remote process and address space, and
-reassembling and reenacting the call there. Return values have to be
-transmitted in the opposite direction. Android provides all the code
-to do that work, so that you can concentrate on defining and implementing
-the RPC interface itself.
-</p>
-<p>
-An RPC interface can include only methods. By default,
-all methods are executed synchronously (the local method blocks until the
-remote method finishes), even if there is no return value.
-</p>
-
-<p>
-In brief, the mechanism works as follows: You'd begin by declaring the
-RPC interface you want to implement using a simple IDL (interface definition
-language). From that declaration, the
-<code><a href="{@docRoot}guide/developing/tools/aidl.html">aidl</a></code>
-tool generates a Java interface definition that must be made available to
-both the local and the remote process. It contains two inner class, as shown
-in the following diagram:
-</p>
-
-<p style="margin-left: 2em">
-<img src="{@docRoot}images/binder_rpc.png" alt="RPC mechanism." />
-</p>
+<dt><b>Content providers</b></dt>
-<p>
-The inner classes have all the code needed to administer remote procedure
-calls for the interface you declared with the IDL.
-Both inner classes implement the {@link android.os.IBinder}
-interface. One of them is used locally and internally by the system;
-the code you write can ignore it.
-The other, called Stub, extends the {@link android.os.Binder}
-class. In addition to internal code for effectuating the IPC calls, it
-contains declarations for the methods in the RPC interface you declared.
-You would subclass Stub to implement those methods, as indicated in the
-diagram.
-</p>
+<dd>A <i>content provider</i> manages a shared set of application data. You can store the data in
+the file system, an SQLite database, on the web, or any other persistent storage location your
+application can access. Through the content provider, other applications can query or even modify
+the data (if the content provider allows it). For example, the Android system provides a content
+provider that manages the user's contact information. As such, any application with the proper
+permissions can query part of the content provider (such as {@link
+android.provider.ContactsContract.Data}) to read and write information about a particular person.
-<p>
-Typically, the remote process would be managed by a service (because a
-service can inform the system about the process and its connections to
-other processes). It would have both the interface file generated by
-the {@code aidl} tool and the Stub subclass implementing the
-RPC methods. Clients of the service would have only the interface file
-generated by the {@code aidl} tool.
-</p>
+<p>Content providers are also useful for reading and writing data that is private to your
+application and not shared. For example, the <a
+href="{@docRoot}resources/samples/NotePad/index.html">Note Pad</a> sample application uses a
+content provider to save notes.</p>
-<p>
-Here's how a connection between a service and its clients is set up:
-</p>
+<p>A content provider is implemented as a subclass of {@link android.content.ContentProvider}
+and must implement a standard set of APIs that enable other applications to perform
+transactions. For more information, see the <a
+href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a> developer
+guide.</p>
+</dd>
-<ul>
-<li>Clients of the service (on the local side) would implement
-<code>{@link android.content.ServiceConnection#onServiceConnected
-onServiceConnected()}</code> and
-<code>{@link android.content.ServiceConnection#onServiceDisconnected
-onServiceDisconnected()}</code> methods so they can be notified
-when a successful connection to the remote service is established, and
-when it goes away. They would then call
-<code>{@link android.content.Context#bindService bindService()}</code>
-to set up the connection.
-</li>
-
-<li>
-The service's <code>{@link android.app.Service#onBind onBind()}</code>
-method would be implemented to either accept or reject the connection,
-depending on the intent it receives (the intent passed to
-{@code bindService()}). If the connection is accepted, it returns
-an instance of the Stub subclass.
-</li>
-<li>If the service accepts the connection, Android calls the
-client's {@code onServiceConnected()} method and passes it an IBinder
-object, a proxy for the Stub subclass managed by the service. Through
-the proxy, the client can make calls on the remote service.
-</li>
-</ul>
+<dt><b>Broadcast receivers</b></dt>
-<p>
-This brief description omits some details of the RPC mechanism. For more
-information, see
-<a href="{@docRoot}guide/developing/tools/aidl.html">Designing a Remote
-Interface Using AIDL</a> and the {@link android.os.IBinder IBinder} class
-description.
-</p>
+<dd>A <i>broadcast receiver</i> is a component that responds to system-wide broadcast
+announcements. Many broadcasts originate from the system—for example, a broadcast announcing
+that the screen has turned off, the battery is low, or a picture was captured.
+Applications can also initiate broadcasts—for example, to let other applications know that
+some data has been downloaded to the device and is available for them to use. Although broadcast
+receivers don't display a user interface, they may <a
+href="{@docRoot}guide/topics/ui/notifiers/notifications.html">create a status bar notification</a>
+to alert the user when a broadcast event occurs. More commonly, though, a broadcast receiver is
+just a "gateway" to other components and is intended to do a very minimal amount of work. For
+instance, it might initiate a service to perform some work based on the event.
+
+<p>A broadcast receiver is implemented as a subclass of {@link android.content.BroadcastReceiver}
+and each broadcast is delivered as an {@link android.content.Intent} object. For more information,
+see the {@link android.content.BroadcastReceiver} class.</p>
+</dd>
+</dl>
-<h3 id="tsafe">Thread-safe methods</h3>
-<p>
-In a few contexts, the methods you implement may be called from more
-than one thread, and therefore must be written to be thread-safe.
-</p>
-
-<p>
-This is primarily true for methods that can be called remotely —
-as in the RPC mechanism discussed in the previous section.
-When a call on a method implemented in an IBinder object originates
-in the same process as the IBinder, the method is executed in the
-caller's thread. However, when the call originates in another process,
-the method is executed in a thread chosen from a pool of threads that
-Android maintains in the same process as the IBinder; it's not executed
-in the main thread of the process. For example, whereas a service's
-{@code onBind()} method would be called from the main thread of the
-service's process, methods implemented in the object that {@code onBind()}
-returns (for example, a Stub subclass that implements RPC methods) would
-be called from threads in the pool.
-Since services can have more than one client, more than one pool thread
-can engage the same IBinder method at the same time. IBinder methods
-must, therefore, be implemented to be thread-safe.
-</p>
-
-<p>
-Similarly, a content provider can receive data requests that originate in
-other processes. Although the ContentResolver and ContentProvider classes
-hide the details of how the interprocess communication is managed,
-ContentProvider methods that respond to those requests — the methods
-<code>{@link android.content.ContentProvider#query query()}</code>,
-<code>{@link android.content.ContentProvider#insert insert()}</code>,
-<code>{@link android.content.ContentProvider#delete delete()}</code>,
-<code>{@link android.content.ContentProvider#update update()}</code>, and
-<code>{@link android.content.ContentProvider#getType getType()}</code>
-— are called from a pool of threads in the content provider's
-process, not the main thread of the process. Since these methods
-may be called from any number of threads at the same time, they too must
-be implemented to be thread-safe.
-</p>
-
-
-<h2 id="lcycles">Component Lifecycles</h2>
-
-<p>
-Application components have a lifecycle — a beginning when
-Android instantiates them to respond to intents through to an end when
-the instances are destroyed. In between, they may sometimes be active
-or inactive,or, in the case of activities, visible to the user or
-invisible. This section discusses the lifecycles of activities,
-services, and broadcast receivers — including the states that they
-can be in during their lifetimes, the methods that notify you of transitions
-between states, and the effect of those states on the possibility that
-the process hosting them might be terminated and the instances destroyed.
-</p>
-
-
-<h3 id="actlife">Activity lifecycle</h3>
-
-<p>An activity has essentially three states:</p>
+<p>A unique aspect of the Android system design is that any application can start another
+application’s component. For example, if you want the user to capture a
+photo with the device camera, there's probably another application that does that and your
+application can use it, instead of developing an activity to capture a photo yourself. You don't
+need to incorporate or even link to the code from the camera application.
+Instead, you can simply start the activity in the camera application that captures a
+photo. When complete, the photo is even returned to your application so you can use it. To the user,
+it seems as if the camera is actually a part of your application.</p>
+
+<p>When the system starts a component, it starts the process for that application (if it's not
+already running) and instantiates the classes needed for the component. For example, if your
+application starts the activity in the camera application that captures a photo, that activity
+runs in the process that belongs to the camera application, not in your application's process.
+Therefore, unlike applications on most other systems, Android applications don't have a single entry
+point (there's no {@code main()} function, for example).</p>
+
+<p>Because the system runs each application in a separate process with file permissions that
+restrict access to other applications, your application cannot directly activate a component from
+another application. The Android system, however, can. So, to activate a component in
+another application, you must deliver a message to the system that specifies your <em>intent</em> to
+start a particular component. The system then activates the component for you.</p>
+
+
+<h3 id="ActivatingComponents">Activating Components</h3>
+
+<p>Three of the four component types—activities, services, and
+broadcast receivers—are activated by an asynchronous message called an <em>intent</em>.
+Intents bind individual components to each other at runtime (you can think of them
+as the messengers that request an action from other components), whether the component belongs
+to your application or another.</p>
+
+<p>An intent is created with an {@link android.content.Intent} object, which defines a message to
+activate either a specific component or a specific <em>type</em> of component—an intent
+can be either explicit or implicit, respectively.</p>
+
+<p>For activities and services, an intent defines the action to perform (for example, to "view" or
+"send" something) and may specify the URI of the data to act on (among other things that the
+component being started might need to know). For example, an intent might convey a request for an
+activity to show an image or to open a web page. In some cases, you can start an
+activity to receive a result, in which case, the activity also returns
+the result in an {@link android.content.Intent} (for example, you can issue an intent to let
+the user pick a personal contact and have it returned to you—the return intent includes a
+URI pointing to the chosen contact).</p>
+
+<p>For broadcast receivers, the intent simply defines the
+announcement being broadcast (for example, a broadcast to indicate the device battery is low
+includes only a known action string that indicates "battery is low").</p>
+
+<p>The other component type, content provider, is not activated by intents. Rather, it is
+activated when targeted by a request from a {@link android.content.ContentResolver}. The content
+resolver handles all direct transactions with the content provider so that the component that's
+performing transactions with the provider doesn't need to and instead calls methods on the {@link
+android.content.ContentResolver} object. This leaves a layer of abstraction between the content
+provider and the component requesting information (for security).</p>
+
+<p>There are separate methods for activiting each type of component:</p>
<ul>
-<li> It is <em>active</em> or <em>running</em> when it is in the foreground of the
-screen (at the top of the activity stack for the current task). This is the
-activity that is the focus for the user's actions.</li>
-
-<li><p>It is <em>paused</em> if it has lost focus but is still visible to the user.
-That is, another activity lies on top of it and that activity either is transparent
-or doesn't cover the full screen, so some of the paused activity can show through.
-A paused activity is completely alive (it maintains all state and member information
-and remains attached to the window manager), but can be killed by the system in
-extreme low memory situations.</p></li>
-
-<li><p>It is <em>stopped</em> if it is completely obscured by another activity.
-It still retains all state and member information. However, it is no longer
-visible to the user so its window is hidden and it will often be killed by the
-system when memory is needed elsewhere.</p></li>
+ <li>You can start an activity (or give it something new to do) by
+passing an {@link android.content.Intent} to {@link android.content.Context#startActivity
+startActivity()} or {@link android.app.Activity#startActivityForResult startActivityForResult()}
+(when you want the activity to return a result).</li>
+ <li>You can start a service (or give new instructions to an ongoing service) by
+passing an {@link android.content.Intent} to {@link android.content.Context#startService
+startService()}. Or you can bind to the service by passing an {@link android.content.Intent} to
+{@link android.content.Context#bindService bindService()}.</li>
+ <li>You can initiate a broadcast by passing an {@link android.content.Intent} to methods like
+{@link android.content.Context#sendBroadcast(Intent) sendBroadcast()}, {@link
+android.content.Context#sendOrderedBroadcast(Intent, String) sendOrderedBroadcast()}, or {@link
+android.content.Context#sendStickyBroadcast sendStickyBroadcast()}.</li>
+ <li>You can perform a query to a content provider by calling {@link
+android.content.ContentProvider#query query()} on a {@link android.content.ContentResolver}.</li>
</ul>
-<p>
-If an activity is paused or stopped, the system can drop it from memory either
-by asking it to finish (calling its {@link android.app.Activity#finish finish()}
-method), or simply killing its process. When it is displayed again
-to the user, it must be completely restarted and restored to its previous state.
-</p>
-
-<p>
-As an activity transitions from state to state, it is notified of the change
-by calls to the following protected methods:
-</p>
-
-<p style="margin-left: 2em">{@code void onCreate(Bundle <i>savedInstanceState</i>)}
-<br/>{@code void onStart()}
-<br/>{@code void onRestart()}
-<br/>{@code void onResume()}
-<br/>{@code void onPause()}
-<br/>{@code void onStop()}
-<br/>{@code void onDestroy()}</p>
-
-<p>
-All of these methods are hooks that you can override to do appropriate work
-when the state changes. All activities must implement
-<code>{@link android.app.Activity#onCreate onCreate()}</code> to do the
-initial setup when the object is first instantiated.
-Many will also implement <code>{@link android.app.Activity#onPause onPause()}</code>
-to commit data changes and otherwise prepare to stop interacting with the user.
-</p>
-
-<div class="sidebox-wrapper">
-<div class="sidebox">
-<h2>Calling into the superclass</h2>
-<p>
-An implementation of any activity lifecycle method should always first
-call the superclass version. For example:
-</p>
+<p>For more information about using intents, see the <a
+href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and
+Intent Filters</a> document. More information about activating specific components is also provided
+in the following documents: <a
+href="{@docRoot}guide/topics/fundamentals/activities.html">Activities</a>, <a
+href="{@docRoot}guide/topics/fundamentals/services.html">Services</a>, {@link
+android.content.BroadcastReceiver} and <a
+href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>.</p>
-<pre>protected void onPause() {
- super.onPause();
- . . .
-}</pre>
-</div>
-</div>
+<h2 id="Manifest">The Manifest File</h2>
-<p>
-Taken together, these seven methods define the entire lifecycle of an
-activity. There are three nested loops that you can monitor by
-implementing them:
-</p>
+<p>Before the Android system can start an application component, the system must know that the
+component exists by reading the application's {@code AndroidManifest.xml} file (the "manifest"
+file). Your application must declare all its components in this file, which must be at the root of
+the application project directory.</p>
+<p>The manifest does a number of things in addition to declaring the application's components,
+such as:</p>
<ul>
-<li>The <b>entire lifetime</b> of an activity happens between the first call
-to <code>{@link android.app.Activity#onCreate onCreate()}</code> through to a
-single final call to <code>{@link android.app.Activity#onDestroy}</code>.
-An activity does all its initial setup of "global" state in {@code onCreate()},
-and releases all remaining resources in {@code onDestroy()}. For example,
-if it has a thread running in the background to download data from the network,
-it may create that thread in {@code onCreate()} and then stop the thread in
-{@code onDestroy()}.</li>
-
-<li><p>The <b>visible lifetime</b> of an activity happens between a call to
-<code>{@link android.app.Activity#onStart onStart()}</code> until a
-corresponding call to <code>{@link android.app.Activity#onStop onStop()}</code>.
-During this time, the user can see the activity on-screen, though it may not
-be in the foreground and interacting with the user. Between these two methods,
-you can maintain resources that are needed to show the activity to the user.
-For example, you can register a {@link android.content.BroadcastReceiver} in
-{@code onStart()} to monitor for changes that impact your UI, and unregister
-it in {@code onStop()} when the user can no longer see what you are displaying.
-The {@code onStart()} and {@code onStop()} methods can be called multiple times,
-as the activity alternates between being visible and hidden to the user.</p></li>
-
-<li><p>The <b>foreground lifetime</b> of an activity happens between a call
-to <code>{@link android.app.Activity#onResume onResume()}</code> until a
-corresponding call to <code>{@link android.app.Activity#onPause onPause()}</code>.
-During this time, the activity is in front of all other activities on screen and
-is interacting with the user. An activity can frequently transition between the
-resumed and paused states — for example, {@code onPause()} is called when
-the device goes to sleep or when a new activity is started, {@code onResume()}
-is called when an activity result or a new intent is delivered. Therefore, the
-code in these two methods should be fairly lightweight.</p></li>
+ <li>Identify any user permissions the application requires, such as Internet access or
+read-access to the user's contacts.</li>
+ <li>Declare the minimum <a href="{@docRoot}guide/appendix/api-levels.html">API Level</a>
+required by the application, based on which APIs the application uses.</li>
+ <li>Declare hardware and software features used or required by the application, such as a camera,
+bluetooth services, or a multitouch screen.</li>
+ <li>API libraries the application needs to be linked against (other than the Android framework
+APIs), such as the <a
+href="http://code.google.com/android/add-ons/google-apis/maps-overview.html">Google Maps
+library</a>.</li>
+ <li>And more</li>
</ul>
-<p>
-The following diagram illustrates these loops and the paths an activity
-may take between states. The colored ovals are major states the activity
-can be in. The square rectangles represent the callback methods you can implement
-to perform operations when the activity transitions between states.
-<p>
-
-<p style="margin-left: 2em"><img src="{@docRoot}images/activity_lifecycle.png"
-alt="State diagram for an Android activity lifecycle." /></p>
-
-<p>
-The following table describes each of these methods in more detail and
-locates it within the activity's overall lifecycle:
-</p>
-<table border="2" width="85%" frame="hsides" rules="rows">
-<colgroup align="left" span="3"></colgroup>
-<colgroup align="left"></colgroup>
-<colgroup align="center"></colgroup>
-<colgroup align="center"></colgroup>
-
-<thead>
-<tr><th colspan="3">Method</th> <th>Description</th> <th>Killable?</th> <th>Next</th></tr>
-</thead>
-
-<tbody>
-<tr>
- <td colspan="3" align="left"><code>{@link android.app.Activity#onCreate onCreate()}</code></td>
- <td>Called when the activity is first created.
- This is where you should do all of your normal static set up —
- create views, bind data to lists, and so on. This method is passed
- a Bundle object containing the activity's previous state, if that
- state was captured (see <a href="#actstate">Saving Activity State</a>,
- later).
- <p>Always followed by {@code onStart()}.</p></td>
- <td align="center">No</td>
- <td align="center">{@code onStart()}</td>
-</tr>
-
-<tr>
- <td rowspan="5" style="border-left: none; border-right: none;"> </td>
- <td colspan="2" align="left"><code>{@link android.app.Activity#onRestart
-onRestart()}</code></td>
- <td>Called after the activity has been stopped, just prior to it being
- started again.
- <p>Always followed by {@code onStart()}</p></td>
- <td align="center">No</td>
- <td align="center">{@code onStart()}</td>
-</tr>
-
-<tr>
- <td colspan="2" align="left"><code>{@link android.app.Activity#onStart onStart()}</code></td>
- <td>Called just before the activity becomes visible to the user.
- <p>Followed by {@code onResume()} if the activity comes
- to the foreground, or {@code onStop()} if it becomes hidden.</p></td>
- <td align="center">No</td>
- <td align="center">{@code onResume()} <br/>or<br/> {@code onStop()}</td>
-</tr>
-
-<tr>
- <td rowspan="2" style="border-left: none;"> </td>
- <td align="left"><code>{@link android.app.Activity#onResume onResume()}</code></td>
- <td>Called just before the activity starts
- interacting with the user. At this point the activity is at
- the top of the activity stack, with user input going to it.
- <p>Always followed by {@code onPause()}.</p></td>
- <td align="center">No</td>
- <td align="center">{@code onPause()}</td>
-</tr>
-
-<tr>
- <td align="left"><code>{@link android.app.Activity#onPause onPause()}</code></td>
- <td>Called when the system is about to start resuming another
- activity. This method is typically used to commit unsaved changes to
- persistent data, stop animations and other things that may be consuming
- CPU, and so on. It should do whatever it does very quickly, because
- the next activity will not be resumed until it returns.
- <p>Followed either by {@code onResume()} if the activity
- returns back to the front, or by {@code onStop()} if it becomes
- invisible to the user.</td>
- <td align="center"><strong style="color:#800000">Yes</strong></td>
- <td align="center">{@code onResume()} <br/>or<br/> {@code onStop()}</td>
-</tr>
-
-<tr>
- <td colspan="2" align="left"><code>{@link android.app.Activity#onStop onStop()}</code></td>
- <td>Called when the activity is no longer visible to the user. This
- may happen because it is being destroyed, or because another activity
- (either an existing one or a new one) has been resumed and is covering it.
- <p>Followed either by {@code onRestart()} if
- the activity is coming back to interact with the user, or by
- {@code onDestroy()} if this activity is going away.</p></td>
- <td align="center"><strong style="color:#800000">Yes</strong></td>
- <td align="center">{@code onRestart()} <br/>or<br/> {@code onDestroy()}</td>
-</tr>
-
-<tr>
- <td colspan="3" align="left"><code>{@link android.app.Activity#onDestroy
-onDestroy()}</code></td>
- <td>Called before the activity is destroyed. This is the final call
- that the activity will receive. It could be called either because the
- activity is finishing (someone called <code>{@link android.app.Activity#finish
- finish()}</code> on it), or because the system is temporarily destroying this
- instance of the activity to save space. You can distinguish
- between these two scenarios with the <code>{@link
- android.app.Activity#isFinishing isFinishing()}</code> method.</td>
- <td align="center"><strong style="color:#800000">Yes</strong></td>
- <td align="center"><em>nothing</em></td>
-</tr>
-</tbody>
-</table>
-
-<p>
-Note the <b>Killable</b> column in the table above. It indicates
-whether or not the system can kill the process hosting the activity
-<em>at any time after the method returns, without executing another
-line of the activity's code</em>. Three methods ({@code onPause()},
-{@code onStop()}, and {@code onDestroy()}) are marked "Yes." Because
-{@code onPause()} is the first of the three, it's the only one that's
-guaranteed to be called before the process is killed —
-{@code onStop()} and {@code onDestroy()} may not be. Therefore, you
-should use {@code onPause()} to write any persistent data (such as user
-edits) to storage.
-</p>
-
-<p>
-Methods that are marked "No" in the <b>Killable</b> column protect the
-process hosting the activity from being killed from the moment they are
-called. Thus an activity is in a killable state, for example, from the
-time {@code onPause()} returns to the time {@code onResume()} is called.
-It will not again be killable until {@code onPause()} again returns.
-</p>
-
-<p>
-As noted in a later section, <a href="#proclife">Processes and lifecycle</a>,
-an activity that's not technically "killable" by this definition might
-still be killed by the system — but that would happen only in
-extreme and dire circumstances when there is no other recourse.
-</p>
+<h3 id="DeclaringComponents">Declaring components</h3>
+<p>The primary task of the manifest is to inform the system about the application's components. For
+example, a manifest file can declare an activity as follows: </p>
-<h4 id="actstate">Saving activity state</h4>
-
-<p>
-When the system, rather than the user, shuts down an activity to conserve
-memory, the user may expect to return to the activity and find it in its
-previous state.
-</p>
-
-<p>
-To capture that state before the activity is killed, you can implement
-an <code>{@link android.app.Activity#onSaveInstanceState
-onSaveInstanceState()}</code> method for the activity. Android calls this
-method before making the activity vulnerable to being destroyed —
-that is, before {@code onPause()} is called. It
-passes the method a {@link android.os.Bundle} object where you can record
-the dynamic state of the activity as name-value pairs. When the activity is
-again started, the Bundle is passed both to {@code onCreate()} and to a
-method that's called after {@code onStart()}, <code>{@link
-android.app.Activity#onRestoreInstanceState onRestoreInstanceState()}</code>,
-so that either or both of them can recreate the captured state.
-</p>
-
-<p>
-Unlike {@code onPause()} and the other methods discussed earlier,
-{@code onSaveInstanceState()} and {@code onRestoreInstanceState()} are
-not lifecycle methods. They are not always called. For example, Android
-calls {@code onSaveInstanceState()} before the activity becomes
-vulnerable to being destroyed by the system, but does not bother
-calling it when the instance is actually being destroyed by a user action
-(such as pressing the BACK key). In that case, the user won't expect to
-return to the activity, so there's no reason to save its state.
-</p>
-
-<p>
-Because {@code onSaveInstanceState()} is not always called, you should
-use it only to record the transient state of the activity, not to store
-persistent data. Use {@code onPause()} for that purpose instead.
-</p>
-
-
-<h4 id="coordact">Coordinating activities</h4>
-
-<p>
-When one activity starts another, they both experience lifecycle
-transitions. One pauses and may stop, while the other starts up.
-On occasion, you may need to coordinate these activities, one with
-the other.
-</p>
-
-<p>
-The order of lifecycle callbacks is well defined,
-particularly when the two activities are in the same process:
-</p>
-
-<ol>
-<li>The current activity's {@code onPause()} method is called.</li>
-
-<li>Next, the starting activity's {@code onCreate()}, {@code onStart()},
-and {@code onResume()} methods are called in sequence.</li>
-
-<li>Then, if the starting activity is no longer visible
-on screen, its {@code onStop()} method is called.</li>
-</ol>
-
+<pre>
+<?xml version="1.0" encoding="utf-8"?>
+<manifest ... >
+ <application android:icon="@drawable/app_icon.png" ... >
+ <activity android:name="com.example.project.ExampleActivity"
+ android:label="@string/example_label" ... >
+ </activity>
+ ...
+ </application>
+</manifest></pre>
-<h3 id="servlife">Service lifecycle</h3>
+<p>In the <code><a
+href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code>
+element, the {@code android:icon} attribute points to resources for an icon that identifies the
+application.</p>
-<p>
-A service can be used in two ways:
-</p>
+<p>In the <code><a
+href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> element,
+the {@code android:name} attribute specifies the fully qualified class name of the {@link
+android.app.Activity} subclass and the {@code android:label} attributes specifies a string
+to use as the user-visible label for the activity.</p>
+<p>You must declare all application components this way:</p>
<ul>
-<li>It can be started and allowed to run until someone stops it or
-it stops itself. In this mode, it's started by calling
-<code>{@link android.content.Context#startService Context.startService()}</code>
-and stopped by calling
-<code>{@link android.content.Context#stopService Context.stopService()}</code>.
-It can stop itself by calling
-<code>{@link android.app.Service#stopSelf() Service.stopSelf()}</code> or
-<code>{@link android.app.Service#stopSelfResult Service.stopSelfResult()}</code>.
-Only one {@code stopService()} call is needed to stop the service, no matter how
-many times {@code startService()} was called.</li>
-
-<li><p>It can be operated programmatically using an interface that
-it defines and exports. Clients establish a connection to the Service
-object and use that connection to call into the service. The connection is
-established by calling
-<code>{@link android.content.Context#bindService Context.bindService()}</code>,
-and is closed by calling
-<code>{@link android.content.Context#unbindService Context.unbindService()}</code>.
-Multiple clients can bind to the same service.
-If the service has not already been launched, {@code bindService()} can optionally
-launch it.
-</p></li>
+ <li><code><a
+href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> elements
+for activities</li>
+ <li><code><a
+href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> elements for
+services</li>
+ <li><code><a
+href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code> elements
+for broadcast receivers</li>
+ <li><code><a
+href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> elements
+for content providers</li>
</ul>
-<p>
-The two modes are not entirely separate. You can bind to a service that
-was started with {@code startService()}. For example, a background music
-service could be started by calling {@code startService()} with an Intent
-object that identifies the music to play. Only later, possibly when the
-user wants to exercise some control over the player or get information
-about the current song, would an activity
-establish a connection to the service by calling {@code bindService()}.
-In cases like this, {@code stopService()}
-will not actually stop the service until the last binding is closed.
-</p>
+<p>Activities, services, and content providers that you include in your source but do not declare
+in the manifest are not visible to the system and, consequently, can never run. However,
+broadcast
+receivers can be either declared in the manifest or created dynamically in code (as
+{@link android.content.BroadcastReceiver} objects) and registered with the system by calling
+{@link android.content.Context#registerReceiver registerReceiver()}.</p>
-<p>
-Like an activity, a service has lifecycle methods that you can implement
-to monitor changes in its state. But they are fewer than the activity
-methods — only three — and they are public, not protected:
-</p>
+<p>For more about how to structure the manifest file for your application, see the <a
+href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</a>
+documentation. </p>
-<p style="margin-left: 2em">{@code void onCreate()}
-<br/>{@code void onStart(Intent <i>intent</i>)}
-<br/>{@code void onDestroy()}</p>
-<p>
-By implementing these methods, you can monitor two nested loops of the
-service's lifecycle:
-</p>
-
-<ul>
-<li>The <b>entire lifetime</b> of a service happens between the time
-<code>{@link android.app.Service#onCreate onCreate()}</code> is called and
-the time <code>{@link android.app.Service#onDestroy}</code> returns.
-Like an activity, a service does its initial setup in {@code onCreate()},
-and releases all remaining resources in {@code onDestroy()}. For example,
-a music playback service could create the thread where the music will be played
-in {@code onCreate()}, and then stop the thread in {@code onDestroy()}.</li>
-
-<li><p>The <b>active lifetime</b> of a service begins with a call to
-<code>{@link android.app.Service#onStartCommand onStartCommand()}</code>. This method
-is handed the Intent object that was passed to {@code startService()}.
-The music service would open the Intent to discover which music to
-play, and begin the playback.</p>
-
-<p>
-There's no equivalent callback for when the service stops — no
-{@code onStop()} method.
-</p></li>
-</ul>
-
-<p>
-The {@code onCreate()} and {@code onDestroy()} methods are called for all
-services, whether they're started by
-<code>{@link android.content.Context#startService Context.startService()}</code>
-or
-<code>{@link android.content.Context#bindService Context.bindService()}</code>.
-However, {@code onStartCommand()} is called only for services started by {@code
-startService()}.
-</p>
-
-<p>
-If a service permits others to
-bind to it, there are additional callback methods for it to implement:
-</p>
-<p style="margin-left: 2em">{@code IBinder onBind(Intent <i>intent</i>)}
-<br/>{@code boolean onUnbind(Intent <i>intent</i>)}
-<br/>{@code void onRebind(Intent <i>intent</i>)}</p>
-
-<p>
-The <code>{@link android.app.Service#onBind onBind()}</code> callback is passed
-the Intent object that was passed to {@code bindService} and
-<code>{@link android.app.Service#onUnbind onUnbind()}</code> is handed
-the intent that was passed to {@code unbindService()}.
-If the service permits the binding, {@code onBind()}
-returns the communications channel that clients use to interact with the service.
-The {@code onUnbind()} method can ask for
-<code>{@link android.app.Service#onRebind onRebind()}</code>
-to be called if a new client connects to the service.
-</p>
+<h3 id="DeclaringComponentCapabilities">Declaring component capabilities</h3>
-<p>
-The following diagram illustrates the callback methods for a service.
-Although, it separates services that are created via {@code startService}
-from those created by {@code bindService()}, keep in mind that any service,
-no matter how it's started, can potentially allow clients to bind to it,
-so any service may receive {@code onBind()} and {@code onUnbind()} calls.
-</p>
+<p>As discussed above, in <a href="#ActivatingComponents">Activating Components</a>, you can use an
+{@link android.content.Intent} to start activities, services, and broadcast receivers. You can do so
+by explicitly naming the target component (using the component class name) in the intent. However,
+the real power of intents lies in the concept of intent actions. With intent actions, you simply
+describe the type of action you want to perform (and optionally, the data upon which you’d like to
+perform the action) and allow the system to find a component on the device that can perform the
+action and start it. If there are multiple components that can perform the action described by the
+intent, then the user selects which one to use.</p>
-<p style="margin-left: 2em"><img src="{@docRoot}images/service_lifecycle.png"
-alt="State diagram for Service callbacks." /></p>
+<p>The way the system identifies the components that can respond to an intent is by comparing the
+intent received to the <i>intent filters</i> provided in the manifest file of other applications on
+the device.</p>
+<p>When you declare a component in your application's manifest, you can optionally include
+intent filters that declare the capabilities of the component so it can respond to intents
+from other applications. You can declare an intent filter for your component by
+adding an <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code
+<intent-filter>}</a> element as a child of the component's declaration element.</p>
-<h3 id="broadlife">Broadcast receiver lifecycle</h3>
+<p>For example, an email application with an activity for composing a new email might declare an
+intent filter in its manifest entry to respond to "send" intents (in order to send email). An
+activity in your application can then create an intent with the “send” action ({@link
+android.content.Intent#ACTION_SEND}), which the system matches to the email application’s “send”
+activity and launches it when you invoke the intent with {@link android.app.Activity#startActivity
+startActivity()}.</p>
-<p>
-A broadcast receiver has single callback method:
+<p>For more about creating intent filters, see the <a
+href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent Filters</a> document.
</p>
-<p style="margin-left: 2em">{@code void onReceive(Context <i>curContext</i>, Intent <i>broadcastMsg</i>)}</p>
-<p>
-When a broadcast message arrives for the receiver, Android calls its
-<code>{@link android.content.BroadcastReceiver#onReceive onReceive()}</code>
-method and passes it the Intent object containing the message. The broadcast
-receiver is considered to be active only while it is executing this method.
-When {@code onReceive()} returns, it is inactive.
-</p>
-<p>
-A process with an active broadcast receiver is protected from being killed.
-But a process with only inactive components can be killed by the system at
-any time, when the memory it consumes is needed by other processes.
-</p>
+<h3 id="DeclaringRequirements">Declaring application requirements</h3>
-<p>
-This presents a problem when the response to a broadcast message is time
-consuming and, therefore, something that should be done in a separate thread,
-away from the main thread where other components of the user interface run.
-If {@code onReceive()} spawns the thread and then returns, the entire process,
-including the new thread, is judged to be inactive (unless other application
-components are active in the process), putting it in jeopardy of being killed.
-The solution to this problem is for {@code onReceive()} to start a service
-and let the service do the job, so the
-system knows that there is still active work being done in the process.
-</p>
+<p>There are a variety of devices powered by Android and not all of them provide the
+same features and capabilities. In order to prevent your application from being installed on devices
+that lack features needed by your application, it's important that you clearly define a profile for
+the types of devices your application supports by declaring device and software requirements in your
+manifest file. Most of these declarations are informational only and the system does not read
+them, but external services such as Android Market do read them in order to provide filtering
+for users when they search for applications from their device.</p>
-<p>
-The next section has more on the vulnerability of processes to being killed.
-</p>
+<p>For example, if your application requires a camera and uses APIs introduced in Android 2.1 (<a
+href="{@docRoot}guide/appendix/api-levels.html">API Level</a> 7), you should declare these as
+requirements in your manifest file. That way, devices that do <em>not</em> have a camera and have an
+Android version <em>lower</em> than 2.1 cannot install your application from Android Market.</p>
+<p>However, you can also declare that your applicaiton uses the camera, but does not
+<em>require</em> it. In that case, your application must perform a check at runtime to determine
+if the device has a camera and disable any features that use the camera if one is not available.</p>
-<h3 id="proclife">Processes and lifecycles</h3>
+<p>Here are some of the important device characteristics that you should consider as you design and
+develop your application:</p>
-<p>The Android system tries to maintain an application process for as
-long as possible, but eventually it will need to remove old processes when
-memory runs low. To determine which processes to keep and which to kill,
-Android places each process into an "importance hierarchy" based on the
-components running in it and the state of those components. Processes
-with the lowest importance are eliminated first, then those with the next
-lowest, and so on. There are five levels in the hierarchy. The following
-list presents them in order of importance:
-</p>
+<dl>
+ <dt>Screen size and density</dt>
+ <dd>In order to categorize devices by their screen type, Android defines two characteristics for
+each device: screen size (the physical dimensions of the screen) and screen density (the physical
+density of the pixels on the screen, or dpi—dots per inch). To simplify all the different
+types of screen configurations, the Android system generalizes them into select groups that make
+them easier to target.
+<p>The screen sizes are: small, normal, large, and extra large.<br/>
+The screen densities are: low density, medium density, high density, and extra high density.</p>
+
+<p>By default, your application is compatible with all screen sizes and densities,
+because the Android system makes the appropriate adjustments to your UI layout and image
+resources. However, you should create specialized layouts for certain screen sizes and provide
+specialized images for certain densities, using alternative layout resources, and by declaring in
+your manifest exactly which screen sizes your application supports with the <a
+href="{@docRoot}guide/topics/manifest/supports-screens.html">{@code
+<supports-screens>}</a> element.</p>
+<p>For more information, see the <a
+href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>
+document.</p></dd>
+
+ <dt>Input configurations</dt>
+ <dd>Many devices provide a different type of user input mechanism, such as a hardware keyboard, a
+trackball, or a five-way navigation pad. If your application requires a particular kind of input
+hardware, then you should declare it in your manifest with the <a
+href="{@docRoot}guide/topics/manifest/uses-configuration-element.html">{@code
+<uses-configuration>}</a> element. However, it is rare that an application should require
+a certain input configuration.</dd>
+
+ <dt>Device features</dt>
+ <dd>There are many hardware and software features that may or may not exist on a given
+Android-powered device, such as a camera, a light sensor, bluetooth, a certain
+version of OpenGL, or the fidelity of the touchscreen. You should never assume that a certain
+feature is available on all Android-powered devices (other than the availability of the standard
+Android library), so you should declare any features used by your application with the <a
+href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a>
+element.</dd>
+
+ <dt>Platform Version</dt>
+ <dd>Different Android-powered devices often run different versions of the Android platform,
+such as Android 1.6 or Android 2.3. Each successive version often includes additional APIs not
+available in the previous version. In order to indicate which set of APIs are available, each
+platform version specifies an <a
+href="{@docRoot}guide/appendix/api-levels.html">API Level</a> (for example, Android 1.0 is API Level
+1 and Android 2.3 is API Level 9). If you use any APIs that were added to the platform after
+version 1.0, you should declare the minimum API Level in which those APIs were introduced using the
+<a href="{@docRoot}guide/topics/manifest/uses-sdk.html">{@code <uses-sdk>}</a> element.</dd>
+</dl>
-<ol>
+<p>It's important that you declare all such requirements for your application, because, when you
+distribute your application on Android Market, Market uses these declarations to filter which
+applications are available on each device. As such, your application should be available only to
+devices that meet all your application requirements.</p>
-<li>A <b>foreground process</b> is one that is required for
-what the user is currently doing. A process is considered to be
-in the foreground if any of the following conditions hold:
+<p>For more information about how Android Market filters applications based on these (and other)
+requirements, see the <a href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>
+document.</p>
-<ul>
-<li>It is running an activity that the user is interacting with
-(the Activity object's <code>{@link android.app.Activity#onResume
-onResume()}</code> method has been called).</li>
-<li><p>It hosts a service that's bound
-to the activity that the user is interacting with.</p></li>
-<li><p>It has a {@link android.app.Service} object that's executing
-one of its lifecycle callbacks (<code>{@link android.app.Service#onCreate
-onCreate()}</code>, <code>{@link android.app.Service#onStartCommand onStartCommand()}</code>,
-or <code>{@link android.app.Service#onDestroy onDestroy()}</code>).</p></li>
+<h2 id="Resources">Application Resources</h2>
-<li><p>It has a {@link android.content.BroadcastReceiver} object that's
-executing its <code>{@link android.content.BroadcastReceiver#onReceive
-onReceive()}</code> method.</p></li>
-</ul>
+<p>An Android application is composed of more than just code—it requires resources that are
+separate from the source code, such as images, audio files, and anything relating to the visual
+presentation of the application. For example, you should define animations, menus, styles, colors,
+and the layout of activity user interfaces with XML files. Using application resources makes it easy
+to update various characteristics of your application without modifying code and—by providing
+sets of alternative resources—enables you to optimize your application for a variety of
+device configurations (such as different languages and screen sizes).</p>
-<p>
-Only a few foreground processes will exist at any given time. They
-are killed only as a last resort — if memory is so low that
-they cannot all continue to run. Generally, at that point, the device has
-reached a memory paging state, so killing some foreground processes is
-required to keep the user interface responsive.
-</p></li>
+<p>For every resource that you include in your Android project, the SDK build tools define a unique
+integer ID, which you can use to reference the resource from your application code or from
+other resources defined in XML. For example, if your application contains an image file named {@code
+logo.png} (saved in the {@code res/drawable/} directory), the SDK tools generate a resource ID
+named {@code R.drawable.logo}, which you can use to reference the image and insert it in your
+user interface.</p>
-<li><p>A <b>visible process</b> is one that doesn't have any foreground
-components, but still can affect what the user sees on screen.
-A process is considered to be visible if either of the following conditions
-holds:</p>
+<p>One of the most important aspects of providing resources separate from your source code
+is the ability for you to provide alternative resources for different device
+configurations. For example, by defining UI strings in XML, you can translate the strings into other
+languages and save those strings in separate files. Then, based on a language <em>qualifier</em>
+that you append to the resource directory's name (such as {@code res/values-fr/} for French string
+values) and the user's language setting, the Android system applies the appropriate language strings
+to your UI.</p>
-<ul>
-<li>It hosts an activity that is not in the foreground, but is still visible
-to the user (its <code>{@link android.app.Activity#onPause onPause()}</code>
-method has been called). This may occur, for example, if the foreground
-activity is a dialog that allows the previous activity to be seen behind it.</li>
+<p>Android supports many different <em>qualifiers</em> for your alternative resources. The
+qualifier is a short string that you include in the name of your resource directories in order to
+define the device configuration for which those resources should be used. As another
+example, you should often create different layouts for your activities, depending on the
+device's screen orientation and size. For example, when the device screen is in portrait
+orientation (tall), you might want a layout with buttons to be vertical, but when the screen is in
+landscape orientation (wide), the buttons should be aligned horizontally. To change the layout
+depending on the orientation, you can define two different layouts and apply the appropriate
+qualifier to each layout's directory name. Then, the system automatically applies the appropriate
+layout depending on the current device orientation.</p>
-<li><p>It hosts a service that's bound to a visible activity.</p></li>
-</ul>
+<p>For more about the different kinds of resources you can include in your application and how
+to create alternative resources for various device configurations, see the <a
+href="{@docRoot}guide/topics/resources/index.html">Application Resources</a> developer guide.</p>
-<p>
-A visible process is considered extremely important and will not be killed
-unless doing so is required to keep all foreground processes running.
-</p></li>
-
-<li><p>A <b>service process</b> is one that is running a service that
-has been started with the
-<code>{@link android.content.Context#startService startService()}</code>
-method and that does not fall into either of the two higher categories.
-Although service processes are not directly tied to anything the
-user sees, they are generally doing things that the user cares about (such
-as playing an mp3 in the background or downloading data on the network),
-so the system keeps them running unless there's not enough
-memory to retain them along with all foreground and visible processes.
-</p></li>
-
-<li><p>A <b>background process</b> is one holding an activity
-that's not currently visible to the user (the Activity object's
-<code>{@link android.app.Activity#onStop onStop()}</code> method has been called).
-These processes have no direct impact on the user experience, and can be killed
-at any time to reclaim memory for a foreground, visible, or service process.
-Usually there are many background processes running, so they are kept in an
-LRU (least recently used) list to ensure that the process with the activity that
-was most recently seen by the user is the last to be killed.
-If an activity implements its lifecycle methods correctly, and captures its current
-state, killing its process will not have a deleterious effect on the user experience.
-</p></li>
-
-<li><p>An <b>empty process</b> is one that doesn't hold any active application
-components. The only reason to keep such a process around is as a cache to
-improve startup time the next time a component needs to run in it. The system
-often kills these processes in order to balance overall system resources between
-process caches and the underlying kernel caches.</p></li>
-</ol>
+<h2>Beginner's Path</h2>
-<p>
-Android ranks a process at the highest level it can, based upon the
-importance of the components currently active in the process. For example,
-if a process hosts a service and a visible activity, the process will be
-ranked as a visible process, not a service process.
-</p>
+<p>For a close look at implementing activities—the components your users use to
+interact with your application—continue with the <b><a
+href="{@docRoot}guide/topics/fundamentals/activities.html">Activities</a></b> document.</p>
-<p>
-In addition, a process's ranking may be increased because other processes are
-dependent on it. A process that is serving another process can never be
-ranked lower than the process it is serving. For example, if a content
-provider in process A is serving a client in process B, or if a service in
-process A is bound to a component in process B, process A will always be
-considered at least as important as process B.
-</p>
-
-<p>
-Because a process running a service is ranked higher than one with background
-activities, an activity that initiates a long-running operation might do
-well to start a service for that operation, rather than simply spawn a thread
-— particularly if the operation will likely outlast the activity.
-Examples of this are playing music in the background
-and uploading a picture taken by the camera to a web site. Using a service
-guarantees that the operation will have at least "service process" priority,
-regardless of what happens to the activity. As noted in the
-<a href="#broadlife">Broadcast receiver lifecycle</a> section earlier, this
-is the same reason that broadcast receivers should employ services rather
-than simply put time-consuming operations in a thread.
-</p>
+++ /dev/null
-page.title=Application Fundamentals
-@jd:body
-
-<div id="qv-wrapper">
-<div id="qv">
-
-<h2>Quickview</h2>
-<ul>
- <li>Android applications are composed of one or more application components (activities,
-services, content providers, and broadcast receivers)</li>
- <li>Each component performs a different role in the overall application behavior, and each
-one can be activated individually (even by other applications)</li>
- <li>The manifest file must declare all components in the application and should also declare
-all application requirements, such as the minimum version of Android required and any hardware
-configurations required</li>
- <li>Non-code application resources (images, strings, layout files, etc.) should include
-alternatives for different device configurations (such as different strings for different
-languages and different layouts for different screen sizes)</li>
-</ul>
-
-
-<h2>In this document</h2>
-<ol>
-<li><a href="#Components">Application Components</a>
- <ol>
- <li><a href="#ActivatingComponents">Activating components</a></li>
- </ol>
-</li>
-<li><a href="#Manifest">The Manifest File</a>
- <ol>
- <li><a href="#DeclaringComponents">Declaring components</a></li>
- <li><a href="#DeclaringRequirements">Declaring application requirements</a></li>
- </ol>
-</li>
-<li><a href="#Resources">Application Resources</a></li>
-</ol>
-</div>
-</div>
-
-<p>Android applications are written in the Java programming language. The Android SDK tools compile
-the code—along with any data and resource files—into an <i>Android package</i>, an
-archive file with an {@code .apk} suffix. All the code in a single {@code .apk} file is considered
-to be one application and is the file that Android-powered devices use to install the
-application.</p>
-
-<p>Once installed on a device, each Android application lives in its own security sandbox: </p>
-
-<ul>
- <li>The Android operating system is a multi-user Linux system in which each application is a
-different user.</li>
-
-<li>By default, the system assigns each application a unique Linux user ID (the ID is used only by
-the system and is unknown to the application). The system sets permissions for all the files in an
-application so that only the user ID assigned to that application can access them. </li>
-
-<li>Each process has its own virtual machine (VM), so an application's code runs in isolation from
-other applications.</li>
-
-<li>By default, every application runs in its own Linux process. Android starts the process when any
-of the application's components need to be executed, then shuts down the process when it's no longer
-needed or when the system must recover memory for other applications.</li>
-</ul>
-
-<p>In this way, the Android system implements the <em>principle of least privilege</em>. That is,
-each application, by default, has access only to the components that it requires to do its work and
-no more. This creates a very secure environment in which an application cannot access parts of
-the system for which it is not given permission.</p>
-
-<p>However, there are ways for an application to share data with other applications and for an
-application to access system services:</p>
-
-<ul>
- <li>It's possible to arrange for two applications to share the same Linux user ID, in which case
-they are able to access each other's files. To conserve system resources, applications with the
-same user ID can also arrange to run in the same Linux process and share the same VM (the
-applications must also be signed with the same certificate).</li>
- <li>An application can request permission to access device data such as the user's
-contacts, SMS messages, the mountable storage (SD card), camera, Bluetooth, and more. All
-application permissions must be granted by the user at install time.</li>
-</ul>
-
-<p>That covers the basics regarding how an Android application exists within the system. The rest of
-this document introduces you to:</p>
-<ul>
- <li>The core framework components that define your application.</li>
- <li>The manifest file in which you declare components and required device features for your
-application.</li>
- <li>Resources that are separate from the application code and allow your application to
-gracefully optimize its behavior for a variety of device configurations.</li>
-</ul>
-
-<p class="note"><strong>Tip:</strong> If you're new to Android development, we suggest that you
-follow the Beginner's Path link at the bottom of this page. For each document in the Application
-Fundamentals, the Beginner's Path points you to the document we suggest you read next, in order
-to get up to speed on the core Android concepts.</p>
-
-
-
-<h2 id="Components">Application Components</h2>
-
-<p>Application components are the essential building blocks of an Android application. Each
-component is a different point through which the system can enter your application. Not all
-components are actual entry points for the user and some depend on each other, but each one exists
-as its own entity and plays a specific role—each one is a unique building block that
-helps define your application's overall behavior.</p>
-
-<p>There are four different types of application components. Each type serves a distinct purpose
-and has a distinct lifecycle that defines how the component is created and destroyed.</p>
-
-<p>Here are the four types of application components:</p>
-
-<dl>
-
-<dt><b>Activities</b></dt>
-
-<dd>An <i>activity</i> represents a single screen with a user interface. For example,
-an email application might have one activity that shows a list of new
-emails, another activity to compose an email, and another activity for reading emails. Although
-the activities work together to form a cohesive user experience in the email application, each one
-is independent of the others. As such, a different application can start any one of these
-activities (if the email application allows it). For example, a camera application can start the
-activity in the email application that composes new mail, in order for the user to share a picture.
-
-<p>An activity is implemented as a subclass of {@link android.app.Activity} and you can learn more
-about it in the <a href="{@docRoot}guide/topics/fundamentals/activities.html">Activities</a>
-developer guide.</p>
-</dd>
-
-
-<dt><b>Services</b></dt>
-
-<dd>A <i>service</i> is a component that runs in the background to perform long-running
-operations or to perform work for remote processes. A service
-does not provide a user interface. For example, a service might play music in the background while
-the user is in a different application, or it might fetch data over the network without
-blocking user interaction with an activity. Another component, such as an activity, can start the
-service and let it run or bind to it in order to interact with it.
-
-<p>A service is implemented as a subclass of {@link android.app.Service} and you can learn more
-about it in the <a href="{@docRoot}guide/topics/fundamentals/services.html">Services</a> developer
-guide.</p>
-</dd>
-
-
-<dt><b>Content providers</b></dt>
-
-<dd>A <i>content provider</i> manages a shared set of application data. You can store the data in
-the file system, an SQLite database, on the web, or any other persistent storage location your
-application can access. Through the content provider, other applications can query or even modify
-the data (if the content provider allows it). For example, the Android system provides a content
-provider that manages the user's contact information. As such, any application with the proper
-permissions can query part of the content provider (such as {@link
-android.provider.ContactsContract.Data}) to read and write information about a particular person.
-
-<p>Content providers are also useful for reading and writing data that is private to your
-application and not shared. For example, the <a
-href="{@docRoot}resources/samples/NotePad/index.html">Note Pad</a> sample application uses a
-content provider to save notes.</p>
-
-<p>A content provider is implemented as a subclass of {@link android.content.ContentProvider}
-and must implement a standard set of APIs that enable other applications to perform
-transactions. For more information, see the <a
-href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a> developer
-guide.</p>
-</dd>
-
-
-<dt><b>Broadcast receivers</b></dt>
-
-<dd>A <i>broadcast receiver</i> is a component that responds to system-wide broadcast
-announcements. Many broadcasts originate from the system—for example, a broadcast announcing
-that the screen has turned off, the battery is low, or a picture was captured.
-Applications can also initiate broadcasts—for example, to let other applications know that
-some data has been downloaded to the device and is available for them to use. Although broadcast
-receivers don't display a user interface, they may <a
-href="{@docRoot}guide/topics/ui/notifiers/notifications.html">create a status bar notification</a>
-to alert the user when a broadcast event occurs. More commonly, though, a broadcast receiver is
-just a "gateway" to other components and is intended to do a very minimal amount of work. For
-instance, it might initiate a service to perform some work based on the event.
-
-<p>A broadcast receiver is implemented as a subclass of {@link android.content.BroadcastReceiver}
-and each broadcast is delivered as an {@link android.content.Intent} object. For more information,
-see the {@link android.content.BroadcastReceiver} class.</p>
-</dd>
-
-</dl>
-
-
-
-<p>A unique aspect of the Android system design is that any application can start another
-application’s component. For example, if you want the user to capture a
-photo with the device camera, there's probably another application that does that and your
-application can use it, instead of developing an activity to capture a photo yourself. You don't
-need to incorporate or even link to the code from the camera application.
-Instead, you can simply start the activity in the camera application that captures a
-photo. When complete, the photo is even returned to your application so you can use it. To the user,
-it seems as if the camera is actually a part of your application.</p>
-
-<p>When the system starts a component, it starts the process for that application (if it's not
-already running) and instantiates the classes needed for the component. For example, if your
-application starts the activity in the camera application that captures a photo, that activity
-runs in the process that belongs to the camera application, not in your application's process.
-Therefore, unlike applications on most other systems, Android applications don't have a single entry
-point (there's no {@code main()} function, for example).</p>
-
-<p>Because the system runs each application in a separate process with file permissions that
-restrict access to other applications, your application cannot directly activate a component from
-another application. The Android system, however, can. So, to activate a component in
-another application, you must deliver a message to the system that specifies your <em>intent</em> to
-start a particular component. The system then activates the component for you.</p>
-
-
-<h3 id="ActivatingComponents">Activating Components</h3>
-
-<p>Three of the four component types—activities, services, and
-broadcast receivers—are activated by an asynchronous message called an <em>intent</em>.
-Intents bind individual components to each other at runtime (you can think of them
-as the messengers that request an action from other components), whether the component belongs
-to your application or another.</p>
-
-<p>An intent is created with an {@link android.content.Intent} object, which defines a message to
-activate either a specific component or a specific <em>type</em> of component—an intent
-can be either explicit or implicit, respectively.</p>
-
-<p>For activities and services, an intent defines the action to perform (for example, to "view" or
-"send" something) and may specify the URI of the data to act on (among other things that the
-component being started might need to know). For example, an intent might convey a request for an
-activity to show an image or to open a web page. In some cases, you can start an
-activity to receive a result, in which case, the activity also returns
-the result in an {@link android.content.Intent} (for example, you can issue an intent to let
-the user pick a personal contact and have it returned to you—the return intent includes a
-URI pointing to the chosen contact).</p>
-
-<p>For broadcast receivers, the intent simply defines the
-announcement being broadcast (for example, a broadcast to indicate the device battery is low
-includes only a known action string that indicates "battery is low").</p>
-
-<p>The other component type, content provider, is not activated by intents. Rather, it is
-activated when targeted by a request from a {@link android.content.ContentResolver}. The content
-resolver handles all direct transactions with the content provider so that the component that's
-performing transactions with the provider doesn't need to and instead calls methods on the {@link
-android.content.ContentResolver} object. This leaves a layer of abstraction between the content
-provider and the component requesting information (for security).</p>
-
-<p>There are separate methods for activiting each type of component:</p>
-<ul>
- <li>You can start an activity (or give it something new to do) by
-passing an {@link android.content.Intent} to {@link android.content.Context#startActivity
-startActivity()} or {@link android.app.Activity#startActivityForResult startActivityForResult()}
-(when you want the activity to return a result).</li>
- <li>You can start a service (or give new instructions to an ongoing service) by
-passing an {@link android.content.Intent} to {@link android.content.Context#startService
-startService()}. Or you can bind to the service by passing an {@link android.content.Intent} to
-{@link android.content.Context#bindService bindService()}.</li>
- <li>You can initiate a broadcast by passing an {@link android.content.Intent} to methods like
-{@link android.content.Context#sendBroadcast(Intent) sendBroadcast()}, {@link
-android.content.Context#sendOrderedBroadcast(Intent, String) sendOrderedBroadcast()}, or {@link
-android.content.Context#sendStickyBroadcast sendStickyBroadcast()}.</li>
- <li>You can perform a query to a content provider by calling {@link
-android.content.ContentProvider#query query()} on a {@link android.content.ContentResolver}.</li>
-</ul>
-
-<p>For more information about using intents, see the <a
-href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and
-Intent Filters</a> document. More information about activating specific components is also provided
-in the following documents: <a
-href="{@docRoot}guide/topics/fundamentals/activities.html">Activities</a>, <a
-href="{@docRoot}guide/topics/fundamentals/services.html">Services</a>, {@link
-android.content.BroadcastReceiver} and <a
-href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>.</p>
-
-
-<h2 id="Manifest">The Manifest File</h2>
-
-<p>Before the Android system can start an application component, the system must know that the
-component exists by reading the application's {@code AndroidManifest.xml} file (the "manifest"
-file). Your application must declare all its components in this file, which must be at the root of
-the application project directory.</p>
-
-<p>The manifest does a number of things in addition to declaring the application's components,
-such as:</p>
-<ul>
- <li>Identify any user permissions the application requires, such as Internet access or
-read-access to the user's contacts.</li>
- <li>Declare the minimum <a href="{@docRoot}guide/appendix/api-levels.html">API Level</a>
-required by the application, based on which APIs the application uses.</li>
- <li>Declare hardware and software features used or required by the application, such as a camera,
-bluetooth services, or a multitouch screen.</li>
- <li>API libraries the application needs to be linked against (other than the Android framework
-APIs), such as the <a
-href="http://code.google.com/android/add-ons/google-apis/maps-overview.html">Google Maps
-library</a>.</li>
- <li>And more</li>
-</ul>
-
-
-<h3 id="DeclaringComponents">Declaring components</h3>
-
-<p>The primary task of the manifest is to inform the system about the application's components. For
-example, a manifest file can declare an activity as follows: </p>
-
-<pre>
-<?xml version="1.0" encoding="utf-8"?>
-<manifest ... >
- <application android:icon="@drawable/app_icon.png" ... >
- <activity android:name="com.example.project.ExampleActivity"
- android:label="@string/example_label" ... >
- </activity>
- ...
- </application>
-</manifest></pre>
-
-<p>In the <code><a
-href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code>
-element, the {@code android:icon} attribute points to resources for an icon that identifies the
-application.</p>
-
-<p>In the <code><a
-href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> element,
-the {@code android:name} attribute specifies the fully qualified class name of the {@link
-android.app.Activity} subclass and the {@code android:label} attributes specifies a string
-to use as the user-visible label for the activity.</p>
-
-<p>You must declare all application components this way:</p>
-<ul>
- <li><code><a
-href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> elements
-for activities</li>
- <li><code><a
-href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> elements for
-services</li>
- <li><code><a
-href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code> elements
-for broadcast receivers</li>
- <li><code><a
-href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> elements
-for content providers</li>
-</ul>
-
-<p>Activities, services, and content providers that you include in your source but do not declare
-in the manifest are not visible to the system and, consequently, can never run. However,
-broadcast
-receivers can be either declared in the manifest or created dynamically in code (as
-{@link android.content.BroadcastReceiver} objects) and registered with the system by calling
-{@link android.content.Context#registerReceiver registerReceiver()}.</p>
-
-<p>For more about how to structure the manifest file for your application, see the <a
-href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</a>
-documentation. </p>
-
-
-
-<h3 id="DeclaringComponentCapabilities">Declaring component capabilities</h3>
-
-<p>As discussed above, in <a href="#ActivatingComponents">Activating Components</a>, you can use an
-{@link android.content.Intent} to start activities, services, and broadcast receivers. You can do so
-by explicitly naming the target component (using the component class name) in the intent. However,
-the real power of intents lies in the concept of intent actions. With intent actions, you simply
-describe the type of action you want to perform (and optionally, the data upon which you’d like to
-perform the action) and allow the system to find a component on the device that can perform the
-action and start it. If there are multiple components that can perform the action described by the
-intent, then the user selects which one to use.</p>
-
-<p>The way the system identifies the components that can respond to an intent is by comparing the
-intent received to the <i>intent filters</i> provided in the manifest file of other applications on
-the device.</p>
-
-<p>When you declare a component in your application's manifest, you can optionally include
-intent filters that declare the capabilities of the component so it can respond to intents
-from other applications. You can declare an intent filter for your component by
-adding an <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code
-<intent-filter>}</a> element as a child of the component's declaration element.</p>
-
-<p>For example, an email application with an activity for composing a new email might declare an
-intent filter in its manifest entry to respond to "send" intents (in order to send email). An
-activity in your application can then create an intent with the “send” action ({@link
-android.content.Intent#ACTION_SEND}), which the system matches to the email application’s “send”
-activity and launches it when you invoke the intent with {@link android.app.Activity#startActivity
-startActivity()}.</p>
-
-<p>For more about creating intent filters, see the <a
-href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent Filters</a> document.
-</p>
-
-
-
-<h3 id="DeclaringRequirements">Declaring application requirements</h3>
-
-<p>There are a variety of devices powered by Android and not all of them provide the
-same features and capabilities. In order to prevent your application from being installed on devices
-that lack features needed by your application, it's important that you clearly define a profile for
-the types of devices your application supports by declaring device and software requirements in your
-manifest file. Most of these declarations are informational only and the system does not read
-them, but external services such as Android Market do read them in order to provide filtering
-for users when they search for applications from their device.</p>
-
-<p>For example, if your application requires a camera and uses APIs introduced in Android 2.1 (<a
-href="{@docRoot}guide/appendix/api-levels.html">API Level</a> 7), you should declare these as
-requirements in your manifest file. That way, devices that do <em>not</em> have a camera and have an
-Android version <em>lower</em> than 2.1 cannot install your application from Android Market.</p>
-
-<p>However, you can also declare that your applicaiton uses the camera, but does not
-<em>require</em> it. In that case, your application must perform a check at runtime to determine
-if the device has a camera and disable any features that use the camera if one is not available.</p>
-
-<p>Here are some of the important device characteristics that you should consider as you design and
-develop your application:</p>
-
-<dl>
- <dt>Screen size and density</dt>
- <dd>In order to categorize devices by their screen type, Android defines two characteristics for
-each device: screen size (the physical dimensions of the screen) and screen density (the physical
-density of the pixels on the screen, or dpi—dots per inch). To simplify all the different
-types of screen configurations, the Android system generalizes them into select groups that make
-them easier to target.
-<p>The screen sizes are: small, normal, large, and extra large.<br/>
-The screen densities are: low density, medium density, high density, and extra high density.</p>
-
-<p>By default, your application is compatible with all screen sizes and densities,
-because the Android system makes the appropriate adjustments to your UI layout and image
-resources. However, you should create specialized layouts for certain screen sizes and provide
-specialized images for certain densities, using alternative layout resources, and by declaring in
-your manifest exactly which screen sizes your application supports with the <a
-href="{@docRoot}guide/topics/manifest/supports-screens.html">{@code
-<supports-screens>}</a> element.</p>
-<p>For more information, see the <a
-href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>
-document.</p></dd>
-
- <dt>Input configurations</dt>
- <dd>Many devices provide a different type of user input mechanism, such as a hardware keyboard, a
-trackball, or a five-way navigation pad. If your application requires a particular kind of input
-hardware, then you should declare it in your manifest with the <a
-href="{@docRoot}guide/topics/manifest/uses-configuration-element.html">{@code
-<uses-configuration>}</a> element. However, it is rare that an application should require
-a certain input configuration.</dd>
-
- <dt>Device features</dt>
- <dd>There are many hardware and software features that may or may not exist on a given
-Android-powered device, such as a camera, a light sensor, bluetooth, a certain
-version of OpenGL, or the fidelity of the touchscreen. You should never assume that a certain
-feature is available on all Android-powered devices (other than the availability of the standard
-Android library), so you should declare any features used by your application with the <a
-href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a>
-element.</dd>
-
- <dt>Platform Version</dt>
- <dd>Different Android-powered devices often run different versions of the Android platform,
-such as Android 1.6 or Android 2.3. Each successive version often includes additional APIs not
-available in the previous version. In order to indicate which set of APIs are available, each
-platform version specifies an <a
-href="{@docRoot}guide/appendix/api-levels.html">API Level</a> (for example, Android 1.0 is API Level
-1 and Android 2.3 is API Level 9). If you use any APIs that were added to the platform after
-version 1.0, you should declare the minimum API Level in which those APIs were introduced using the
-<a href="{@docRoot}guide/topics/manifest/uses-sdk.html">{@code <uses-sdk>}</a> element.</dd>
-</dl>
-
-<p>It's important that you declare all such requirements for your application, because, when you
-distribute your application on Android Market, Market uses these declarations to filter which
-applications are available on each device. As such, your application should be available only to
-devices that meet all your application requirements.</p>
-
-<p>For more information about how Android Market filters applications based on these (and other)
-requirements, see the <a href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>
-document.</p>
-
-
-
-<h2 id="Resources">Application Resources</h2>
-
-<p>An Android application is composed of more than just code—it requires resources that are
-separate from the source code, such as images, audio files, and anything relating to the visual
-presentation of the application. For example, you should define animations, menus, styles, colors,
-and the layout of activity user interfaces with XML files. Using application resources makes it easy
-to update various characteristics of your application without modifying code and—by providing
-sets of alternative resources—enables you to optimize your application for a variety of
-device configurations (such as different languages and screen sizes).</p>
-
-<p>For every resource that you include in your Android project, the SDK build tools define a unique
-integer ID, which you can use to reference the resource from your application code or from
-other resources defined in XML. For example, if your application contains an image file named {@code
-logo.png} (saved in the {@code res/drawable/} directory), the SDK tools generate a resource ID
-named {@code R.drawable.logo}, which you can use to reference the image and insert it in your
-user interface.</p>
-
-<p>One of the most important aspects of providing resources separate from your source code
-is the ability for you to provide alternative resources for different device
-configurations. For example, by defining UI strings in XML, you can translate the strings into other
-languages and save those strings in separate files. Then, based on a language <em>qualifier</em>
-that you append to the resource directory's name (such as {@code res/values-fr/} for French string
-values) and the user's language setting, the Android system applies the appropriate language strings
-to your UI.</p>
-
-<p>Android supports many different <em>qualifiers</em> for your alternative resources. The
-qualifier is a short string that you include in the name of your resource directories in order to
-define the device configuration for which those resources should be used. As another
-example, you should often create different layouts for your activities, depending on the
-device's screen orientation and size. For example, when the device screen is in portrait
-orientation (tall), you might want a layout with buttons to be vertical, but when the screen is in
-landscape orientation (wide), the buttons should be aligned horizontally. To change the layout
-depending on the orientation, you can define two different layouts and apply the appropriate
-qualifier to each layout's directory name. Then, the system automatically applies the appropriate
-layout depending on the current device orientation.</p>
-
-<p>For more about the different kinds of resources you can include in your application and how
-to create alternative resources for various device configurations, see the <a
-href="{@docRoot}guide/topics/resources/index.html">Application Resources</a> developer guide.</p>
-
-
-<h2>Beginner's Path</h2>
-
-<p>For a close look at implementing activities—the components your users use to
-interact with your application—continue with the <b><a
-href="{@docRoot}guide/topics/fundamentals/activities.html">Activities</a></b> document.</p>
-