docs/html/guide/basics/anatomy.jd

page.title=Anatomy of an Android Application
@jd:body
<h1>Anatomy of an Android Application</h1>

<p>
There are four building blocks to an Android application:
</p>

<ul>
  <li>Activity</li>
  <li>Broadcast Receiver</li>
  <li>Service</li>
  <li>Content Provider</li>
</ul>

<p>
Not every application needs to have all four, but your application will be written with some
combination of these.
</p>

<p>
Once you have decided what components you need for your application, you should list them in a file 
called AndroidManifest.xml. This is an XML file where you declare the components of your application
and what their capabilities and requirements are. See the 
<a href="{@docRoot}devel/bblocks-manifest.html">Android manifest file documentation</a>
for complete details.
</p>

<h2>Activity</h2>
<p>
Activities are the most common of the four Android building blocks. An activity is usually a single 
screen in your application. Each activity is implemented as a single class that extends the 
{@link android.app.Activity Activity} base class. Your class will display a user interface composed 
of {@link android.view.View Views} and respond to events. Most applications consist of multiple 
screens. For example, a text messaging application might have one screen that shows a list of 
contacts to send messages to, a second screen to write the message to the chosen contact, and other 
screens to review old messages or change settings. Each of these screens would be implemented as an
activity. Moving to another screen is accomplished by a starting a new activity. In some cases an
activity may return a value to the previous activity -- for example an activity that lets the user 
pick a photo would return the chosen photo to the caller.
</p>

<p>
When a new screen opens, the previous screen is paused and put onto a history stack. The user can 
navigate backward through previously opened screens in the history. Screens can also choose to be 
removed from the history stack when it would be inappropriate for them to remain. Android retains 
history stacks for each application launched from the home screen.
</p>

<h3>Intent and Intent Filters</h3>

<p>
Android uses a special class called an {@link android.content.Intent Intent} to move from screen to
screen. An intent describes what an application wants done. The two most important parts of the 
intent data structure are the action and the data to act upon. Typical values for action are MAIN
(the front door of the application), VIEW, PICK, EDIT, etc.  The data is expressed as a URI. 
For example, to view contact information for a person, you would create an intent with the VIEW 
action and the data set to a URI representing that person.
</p>

<p>
There is a related class called an {@link android.content.IntentFilter IntentFilter}. While an 
intent is effectively a request to do something, an intent filter is a description of what intents
 an activity (or broadcast receiver, see below) is capable of handling. An activity that is able to 
 display contact information for a person would publish an IntentFilter that said that it knows 
 how to handle the action VIEW when applied to data representing a person. 
 Activities publish their IntentFilters in the AndroidManifest.xml file.
</p>

<p>
Navigating from screen to screen is accomplished by resolving intents. To navigate forward, an 
activity calls <code>{@link android.app.Activity#startActivity startActivity(myIntent)}</code>. 
The system then looks at the intent filters for all installed applications and picks the activity 
whose intent filters best matches <code>myIntent</code>. The new activity is informed of the intent, which causes
it to be launched. The process of resolving intents happens at run time when startActivity is 
called, which offers two key benefits:
</p>

<ul>
  <li>Activities can reuse functionality from other components simply by making a request in the form of an Intent</li>
  <li>Activities can be replaced at any time by a new Activity with an equivalent IntentFilter</li>
</ul>


<h2>Broadcast Receiver</h2>

<p>
You can use a {@link android.content.BroadcastReceiver BroadcastReceiver} when you want code in your 
application to execute in reaction to an external event, for example, when the phone rings, or when 
the data network is available, or when it's midnight. Broadcast receivers do not display a UI, although 
they may use the {@link android.app.NotificationManager NotificationManager} to alert the user if
something interesting has happened. Broadcast receivers are registered in AndroidManifest.xml, but you 
can also register them from code using 
<code>{@link android.content.Context#registerReceiver Context.registerReceiver()}</code>. 
Your application does not have to be running for its broadcast receivers to be called; the system will 
start your application, if necessary, when a broadcast receiver is triggered. Applications can also send
their own intent broadcasts to others with 
<code>{@link android.content.Context#sendBroadcast Context.sendBroadcast()}</code>.
</p>

<h2>Service</h2>

<p>
A {@link android.app.Service Service} is code that is long-lived and runs without a UI. A good 
example of this is a media player playing songs from a play list. In a media player application, 
there would probably be one or more activities that allow the user to choose songs and start 
playing them. However, the music playback itself should not be handled by an activity because the 
user will expect the music to keep playing even after navigating to a new screen. In this case, the 
media player activity could start a service using 
<code>{@link android.content.Context#startService Context.startService()}</code> 
to run in the background to keep the music going. The system will then keep the music playback 
service running until it has finished.  (You can learn more about the priority given to services in 
the system by reading 
<a href="{@docRoot}intro/lifecycle.html">Life Cycle of an Android Application</a>.) 
Note that you can connect to a
service (and start it if it's not already running) with the 
<code>{@link android.content.Context#bindService Context.bindService() }</code> method. 
When connected to a service, you can communicate with it through an interface exposed by the 
service. For the music service, this might allow you to pause, rewind, etc.
</p>

<h2>Content Provider</h2>
<p>
Applications can store their data in files, an SQLite database, or any other mechanism that makes 
sense. A content provider, however, is useful if you want your application's data to be shared with
other applications. A content provider is a class that implements a standard set of methods to let
other applications store and retrieve the type of data that is handled by that content provider.
</p>

<p>
To get more details on content providers, see
<a href="{@docRoot}devel/data/contentproviders.html">Accessing Content Providers</a>.
</p>