am f2f5b6ef: delete orphaned/redirected files

page.title=Application Model

@jd:body

<h1>Android Application Model: Applications, Tasks, Processes, and Threads</h1>

<p>In most operating systems, there is a strong 1-to-1 correlation between

the executable image (such as the .exe on Windows) that an application lives in,

the process it runs in, and the icon and application the user interacts with.

In Android these associations are much more fluid, and it is important to

understand how the various pieces can be put together.</p>

<p>Because of the flexible nature of Android applications, there is some

basic terminology that needs to be understood when implementing the

various pieces of an application:</p>

<ul>

<li><p>An <strong>android package</strong> (or <strong>.apk</strong> for short)

is the file containing an application's code and its resources.  This is the

file that an application is distributed in and downloaded by the user when

installing that application on their device.</p></li>

<li><p>A <strong>task</strong> is generally what the user perceives as

an "application" that can be launched: usually a task has an icon in the

home screen through which it is accessed, and it is available as a top-level

item that can be brought to the foreground in front of other

tasks.</p></li>

<li><p>A <strong>process</strong> is a low-level kernel process in which

an application's code is running.  Normally all of the code in a

.apk is run in one, dedicated process for that .apk; however, the

{@link android.R.styleable#AndroidManifestApplication_process process} tag

can be used to modify where that code is run, either for

{@link android.R.styleable#AndroidManifestApplication the entire .apk}

or for individual

{@link android.R.styleable#AndroidManifestActivity activity},

{@link android.R.styleable#AndroidManifestReceiver receiver},

{@link android.R.styleable#AndroidManifestService service}, or

{@link android.R.styleable#AndroidManifestProvider provider}, components.</p></li>

</ul>

<h2 id="Tasks">Tasks</h2>

<p>A key point here is: <em>when the user sees as an "application," what

they are actually dealing with is a task</em>.  If you just create a .apk

with a number of activities, one of which is a top-level entry point (via

an {@link android.R.styleable#AndroidManifestIntentFilter intent-filter} for

the action <code>android.intent.action.MAIN</code> and

category <code>android.intent.category.LAUNCHER</code>), then there will indeed

be one task created for your .apk, and any activities you start from there

will also run as part of that task.</p>

<p>A task, then, from the user's perspective your application; and from the

application developer's perspective it is one or more activities the user

has traversed through in that task and not yet closed, or an activity stack.

A new task is created by

starting an activity Intent with the {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK

Intent.FLAG_ACTIVITY_NEW_TASK} flag; this Intent will be used as the root Intent of

the task, defining what task it is.  Any activity started without this flag

will run in the same task as the activity that is starting it (unless that

activity has requested a special launch mode, as discussed later).  Tasks can

be re-ordered: if you use FLAG_ACTIVITY_NEW_TASK but there is already a task

running for that Intent, the current task's activity stack will be brought

to the foreground instead of starting a new task.</p>

<p>FLAG_ACTIVITY_NEW_TASK must only be used with care: using it says that,

from the user's perspective, a new application starts at this point.  If this

is not the behavior you desire, you should not be creating a new task.  In

addition, you should only use the new task flag if it is possible for the user

to navigate from home back to where they are and launch the same Intent as a

new task.  Otherwise, if the user presses HOME instead of BACK from the task

you have launched, your task and its activities will be ordered behind the

home screen without a way to return to them.</p>

<h3>Task Affinities</h3>

<p>In some cases Android needs to know which task an activity belongs to even when

it is not being launched in to a specific task.  This is accomplished through

task affinities, which provide a unique static name for the task that one or more

activities are intended to run in.  The default task affinity for an activity

is the name of the .apk package name the activity is implemented in.  This

provides the normally expected behavior, where all of the activities in a

particular .apk are part of a single application to the user.</p>

<p>When starting a new activity without the

{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK

Intent.FLAG_ACTIVITY_NEW_TASK} flag, task affinities have no impact on the

task the new activity will run in: it will always run in the task of the

activity that is starting it.  However, if the NEW_TASK flag is being used,

then the affinity will be used to determine if a task already exists with

the same affinity.  If so, that task will be brought to the front and the

new activity launched at the top of that task.</p>

<p>This behavior is most useful for situations where you must use the

NEW_TASK flag, in particular launching activities from status bar notifications

or home screen shortcuts.  The result is that, when the user launches your

application this way, its current task state will be brought to the foreground,

and the activity they now want to look at placed on top of it.</p>

<p>You can assign your own task affinities in your manifest's

{@link android.R.styleable#AndroidManifestApplication application} tag for

all activities in the .apk, or the

{@link android.R.styleable#AndroidManifestActivity activity} tag of

individual activities.  Some examples of how this can be used are:</p>

<ul>

<li>If your .apk contains multiple top-level applications that the user can

launch, then you will probably want to assign different affinities to each

of the activities that the users sees for your .apk.  A good convention for

coming up with distinct names is to append your .apk's package name with

a colon separated string.  For example, the "com.android.contacts" .apk

may have the affinities "com.android.contacts:Dialer" and

"com.android.contacts:ContactsList".</ul>

<li>If you are replacing a notification, shortcut, or other such "inner"

activity of an application that can be launched from outside of it, you may

need to explicitly set the taskAffinity of your replacement activity to be

the same as the application you are replacing.  For example, if you are

replacing the contacts details view (which the user can make and invoke

shortcuts to), you would want to set the taskAffinity to

"com.android.contacts".</li>

</ul>

<h3>Launch Modes and Launch Flags</h3>

<p>The main way you control how activities interact with tasks is through

the activity's

{@link android.R.styleable#AndroidManifestActivity_launchMode launchMode}

attribute and the {@link android.content.Intent#setFlags flags} associated

with an Intent.  These two parameters can work together in various ways

to control the outcome of the activity launch, as described in their

associated documentation.  Here we will look at some common use cases and

combinations of these parameters.</p>

<p>The most common launch mode you will use (besides the default

<code>standard</code> mode) is <code>singleTop</code>.  This does not have

an impact on tasks; it just avoids starting the same activity multiple times

on the top of a stack.

<p>The <code>singleTask</code> launch mode has a major

impact on tasks: it causes the activity to always be started in

a new task (or its existing task to be brought to the foreground).  Using

this mode requires a lot of care in how you interact with the rest of the

system, as it impacts every path in to the activity.  It should only be used

with activities that are front doors to the application (that is, which

support the MAIN action and LAUNCHER category).</p>

<p>The <code>singleInstance</code> launch mode is even more specialized, and

should only be used in applications that are implemented entirely as one

activity.</p>

<p>A situation you will often run in to is when another entity (such as the

{@link android.app.SearchManager} or {@link android.app.NotificationManager})

starts one of your activities.  In this case, the

{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK

Intent.FLAG_ACTIVITY_NEW_TASK} flag must be used, because the activity is

being started outside of a task (and the application/task may not even

exist).  As described previously, the standard behavior in this situation

is to bring to the foreground the current task matching the new activity's

affinity and start the new activity at the top of it.  There are, however,

other types of behavior that you can implement.</p>

<p>One common approach is to also use the

{@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP

Intent.FLAG_ACTIVITY_CLEAR_TOP} flag in conjunction with NEW_TASK.  By doing so,

if your task is already running, then it will be brought to the foreground,

all of the activities on its stack cleared except the root activity, and the

root activity's {@link android.app.Activity#onNewIntent} called with the

Intent being started.  Note that the activity often also use the <code>singleTop</code>

or <code>singleTask</code> launch mode when using this approach, so that

the current instance is given the new intent instead of requiring that it

be destroyed and a new instance started.</p>

<p>Another approach you can take is to set the notification activity's

<code>android:taskAffinity</code> to the empty string "" (indicating no affinity)

and setting the

<code>{@link android.R.styleable#AndroidManifestActivity_noHistory

android:noHistory}</code> and

<code>{@link android.R.styleable#AndroidManifestActivity_excludeFromRecents

android:excludeFromRecents}</code> attributes.

This approach is useful if you would like the notification

to take the user to a separate activity describing it, rather than return

to the application's task.  By specifying these attributes, the activity will

be finished whether the user leaves it with BACK or HOME and it will not

show up in the recent tasks list; if the <code>noHistory</code> attribute

isn't specified, pressing HOME will result in the activity and its task

remaining in the system, possibly with no way to return to it.</p>

<p>Be sure to read the documentation on the

{@link android.R.styleable#AndroidManifestActivity_launchMode launchMode attribute}

and the {@link android.content.Intent#setFlags Intent flags} for the details

on these options.</p>

<h2 id="Processes">Processes</h2>

<p>In Android, processes are entirely an implementation detail of applications

and not something the user is normally aware of.  Their main uses are simply:</p>

<ul>

<li> Improving stability or security by putting untrusted or unstable code

into another process.

<li> Reducing overhead by running the code of multiple .apks in the same

process.

<li> Helping the system manage resources by putting heavy-weight code in

a separate process that can be killed independently of other parts of the

application.

</ul>

<p>As described previously, the

{@link android.R.styleable#AndroidManifestApplication_process process} attribute

is used to control the process that particular application components run in.

Note that this attribute can not be used to violate security of the system: if

two .apks that are not sharing the same user ID try to run in the same process,

this will not be allowed and different distinct processes will be created for

each of them.</p>

<p>See the <a href="{@docRoot}devel/security.html">security</a> document for

more information on these security restrictions.</p>

<h2 id="Threads">Threads</h2>

<p>Every process has one or more threads running in it.  In most situations, Android

avoids creating additional threads in a process, keeping an application

single-threaded unless it creates its own threads.  An important repercussion

of this is that all calls to {@link android.app.Activity},

{@link android.content.BroadcastReceiver}, and {@link android.app.Service}

instances are made only from the main thread of the process they are running in.</p>

<p>Note that a new thread is <strong>not</strong> created for each

Activity, BroadcastReceiver, Service, or ContentProvider instance:

these application components are instantiated in the desired process (all in the

same process unless otherwise specified), in the main thread of that process.

This means that none of these components (including services) should perform

long or blocking operations (such as networking calls or computation loops)

when called by the system, since this will block

all other components in the process.  You can use the standard library

{@link java.lang.Thread} class or Android's {@link android.os.HandlerThread}

convenience class to perform long operations on another thread.</p>

<p>There are a few important exceptions to this threading rule:</p>

<ul>

<li><p>Calls on to an {@link android.os.IBinder} or interface implemented on

an IBinder are dispatched from the thread calling them or a thread pool in the

local process if coming from another process, <em>not</em>

from the main thread of their process.  In particular, calls on to the IBinder

of a {@link android.app.Service} will be called this way.  (Though

calls to methods on Service itself are done from the main thread.)

This means that <em>implementations of IBinder interfaces must always be

written in a thread-safe way, since they can be called from any number of

arbitrary threads at the same time</em>.</p></li>

<li><p>Calls to the main methods of {@link android.content.ContentProvider}

are dispatched from the calling thread or main thread as with IBinder.  The

specific methods are documented in the ContentProvider class.

This means that <em>implementations of these methods must always be

written in a thread-safe way, since they can be called from any number of

arbitrary threads at the same time</em>.</p></li>

<li><p>Calls on {@link android.view.View} and its subclasses are made from the

thread that the view's window is running in.  Normally this will be the main

thread of the process, however if you create a thread and show a window from

there then the window's view hierarchy will be called from that thread.</p></li>

</ul>

page.title=Building Blocks

@jd:body

<h1>Android Building Blocks</h1>

<p>You can think of an Android application as a collection of components, of

various kinds. These components are for the most part quite loosely coupled,

to the degree where you can accurately describe them as a federation of

components rather than a single cohesive application.</p>

<p>Generally, these components all run in the same system process. It's

possible (and quite common) to create multiple threads within that process,

and it's also possible to create completely separate child processes if you

need to. Such cases are pretty uncommon though, because Android tries very

hard to make processes transparent to your code.</p>

<p>These are the most important parts of the Android APIs:</p>

<dl>

    <dt><a href="{@docRoot}devel/bblocks-manifest.html">AndroidManifest.xml</a></dt>

    <dd>The AndroidManifest.xml file is the control file that tells the system

    what to do with all the top-level components (specifically activities,

    services, intent receivers, and content providers described below)

    you've created.  For instance, this is the

    "glue" that actually specifies which Intents your Activities receive.</dd>

    <dt>{@link android.app.Activity Activities}</dt>

    <dd>An Activity is, fundamentally, an object that has a life cycle. An

    Activity is a chunk of code that does some work; if necessary, that work

    can include displaying a UI to the user. It doesn't have to, though - some

    Activities never display UIs. Typically, you'll designate one of your

    application's Activities as the entry point to your application. </dd>

    <dt>{@link android.view.View Views}</dt>

    <dd>A View is an object that knows how to draw itself to the screen.

    Android user interfaces are comprised of trees of Views. If you want to

    perform some custom graphical technique (as you might if you're writing a

    game, or building some unusual new user interface widget) then you'd

    create a View.</dd>

    <dt>{@link android.content.Intent Intents}</dt>

    <dd>An Intent is a simple message object that represents an "intention" to

    do something. For example, if your application wants to display a web

    page, it expresses its "Intent" to view the URI by creating an Intent

    instance and handing it off to the system. The system locates some other

    piece of code (in this case, the Browser) that knows how to handle that

    Intent, and runs it. Intents can also be used to broadcast interesting

    events (such as a notification) system-wide.</dd>

    <dt>{@link android.app.Service Services}</dt>

    <dd>A Service is a body of code that runs in the background. It can run in

    its own process, or in the context of another application's process,

    depending on its needs. Other components "bind" to a Service and invoke

    methods on it via remote procedure calls. An example of a Service is a

    media player; even when the user quits the media-selection UI, she

    probably still intends for her music to keep playing. A Service keeps the

    music going even when the UI has completed.</dd>

    <dt>{@link android.app.NotificationManager Notifications}</dt>

    <dd>A Notification is a small icon that appears in the status bar. Users

    can interact with this icon to receive information. The most well-known

    notifications are SMS messages, call history, and voicemail, but

    applications can create their own. Notifications are the

    strongly-preferred mechanism for alerting the user of something that needs

    their attention.</dd>

    <dt>{@link android.content.ContentProvider ContentProviders}</dt>

    <dd>A ContentProvider is a data storehouse that provides access to data on

    the device; the classic example is the ContentProvider that's used to

    access the user's list of contacts. Your application can access data that

    other applications have exposed via a ContentProvider, and you can also

    define your own ContentProviders to expose data of your own.</dd>

</dl>

page.title=Getting Started

@jd:body

<h1>Getting Started with Android</h1>

<p>To get started with Android, please read the following sections first:</p>

<dl>

    <dt><a href="{@docRoot}intro/installing.html">Installing the SDK and

    Plugin</a></dt>

    <dd>How to install the Android SDK and Eclipse plugin.</dd>

    <dt><a href="{@docRoot}intro/develop-and-debug.html">Developing and Debugging</a></dt>

    <dd>An introduction to developing and debugging Android applications in Eclipse,

    plus information on using other IDEs.</dd>

    <dt><a href="{@docRoot}intro/hello-android.html">Hello Android</a></dt>

    <dd>Writing your first Android Application, the ever popular Hello World,

    Android style.</dd>

    <dt><a href="{@docRoot}intro/anatomy.html">Anatomy of an App</a></dt>

    <dd>A guide to the structure and architecture of an Android

    Application. This guide will help you understand the pieces that make up

    an Android app.</dd>

    <dt><a href="{@docRoot}intro/tutorial.html">Notepad Tutorial</a></dt>

    <dd>This tutorial document will lead you through

    constructing a real Android Application: A notepad which can create, edit

    and delete notes, and covers many of the basic concepts with practical

    examples.</dd>

    <dt><a href="{@docRoot}intro/tools.html">Development Tools</a></dt>

    <dd>The

    command line tools included with the SDK, what they do, and how to use

    them.</dd>

    <dt><a href="{@docRoot}intro/appmodel.html">Application Model</a></dt>

    <dd>A guide to Applications, Tasks, Processes, and Threads.

    These are the elements that define the way your application is run by the 

    system and presented to the user.</dd>

    <dt><a href="{@docRoot}intro/lifecycle.html">Application Life Cycle</a></dt>

    <dd>The important life-cycle details for

    Applications and the Activities running inside of them.</dd>

</dl>

<h2>Other Introductory Material</h2>

<p>After reading the sections above, the following Getting Started information is also very useful:</p>

<h3>Core Packages</h3>

<p> These are the basic packages that make up the Android SDK for writing

applications. The packages are organized as layers, listed here from

lowest-level to highest.</p>

<dl>

    <dt>{@link android.util}</dt>

    <dd>contains various low-level utility classes, such

    as specialized container classes, XML utilities, etc.</dd>

    <dt>{@link android.os}</dt>

    <dd> provides basic operating system services, message

    passing, and inter-process communication.</dd>

    <dt>{@link android.graphics}</dt><dd>is the core rendering package.</dd>

    <dt>{@link android.text}, {@link android.text.method}, {@link

    android.text.style}, and {@link android.text.util} </dt>

    <dd>supply a rich set of

    text processing tools, supporting rich text, input methods, etc.</dd>

    <dt>{@link android.database}</dt>

    <dd>contains low-level APIs for working with

    databases.</dd>

    <dt>{@link android.content}</dt>

    <dd>provides various services for accessing data

    on the device: applications installed on the device and their associated

    resources, and content providers for persistent dynamic data.</dd>

    <dt>{@link android.view}</dt>

    <dd>is the core user-interface framework.</dd>

    <dt>{@link android.widget}</dt>

    <dd>supplies standard user interface elements

    (lists, buttons, layout managers, etc) built from the view package.</dd>

    <dt>{@link android.app}</dt>

    <dd>provides the high-level application model,

    implemented using Activities.</dd>

</dl>

<h3>Other Notable Packages</h3>

<p> These packages provide additional domain-specific features of the Android

platform. They are not necessary for basic application development.</p>

<dl>

    <dt>{@link android.provider}</dt>

    <dd>contains definitions for various standard

    content providers included with the platform.</dd>

    <dt>{@link android.telephony}</dt>

    <dd>provides APIs for interacting with the

    device's phone stack.</dd>

    <dt>{@link android.webkit}</dt>

    <dd>includes various APIs for working with

    web-based content.</dd>

</dl>

<html>

<head>

<meta http-equiv="refresh" content="0;url=../index.html">

</head>

<body>

<a href="../index.html">click here</a> if you are not redirected.

</body>

</html>

 No newline at end of file