1page.title=Creating a Background Service
2trainingnavtop=true
3@jd:body
4<div id="tb-wrapper">
5<div id="tb">
6<h2>This lesson teaches you to</h2>
7<ol>
8    <li>
9        <a href="#CreateClass">Create an IntentService</a>
10    </li>
11    <li>
12        <a href="#DefineManifest">Define the IntentService in the Manifest</a>
13    </li>
14</ol>
15<h2>You should also read</h2>
16<ul>
17    <li>
18<a href="{@docRoot}guide/components/services.html#ExtendingIntentService">Extending the IntentService Class</a>
19    </li>
20    <li>
21        <a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a>
22    </li>
23</ul>
24<h2>Try it out</h2>
25
26<div class="download-box">
27    <a href="{@docRoot}shareables/training/ThreadSample.zip" class="button">Download the sample</a>
28    <p class="filename">ThreadSample.zip</p>
29</div>
30
31</div>
32</div>
33<p>
34    The {@link android.app.IntentService} class provides a straightforward structure for running
35    an operation on a single background thread. This allows it to handle long-running operations
36    without affecting your user interface's responsiveness. Also, an
37    {@link android.app.IntentService} isn't affected by most user interface lifecycle events, so it
38    continues to run in circumstances that would shut down an {@link android.os.AsyncTask}
39</p>
40<p>
41    An {@link android.app.IntentService} has a few limitations:
42</p>
43<ul>
44    <li>
45        It can't interact directly with your user interface. To put its results in the UI, you
46        have to send them to an {@link android.app.Activity}.
47    </li>
48    <li>
49        Work requests run sequentially. If an operation is running in an
50        {@link android.app.IntentService}, and you send it another request, the request waits until
51        the first operation is finished.
52    </li>
53    <li>
54        An operation running on an {@link android.app.IntentService} can't be interrupted.
55    </li>
56</ul>
57<p>
58    However, in most cases an {@link android.app.IntentService} is the preferred way to perform
59    simple background operations.
60</p>
61<p>
62    This lesson shows you how to create your own subclass of {@link android.app.IntentService}.
63    The lesson also shows you how to create the required callback method
64    {@link android.app.IntentService#onHandleIntent onHandleIntent()}. Finally, the lesson describes
65    shows you how to define the {@link android.app.IntentService} in your manifest file.
66</p>
67<h2 id="CreateClass">Create an IntentService</h2>
68<p>
69    To create an {@link android.app.IntentService} component for your app, define a class that
70    extends {@link android.app.IntentService}, and within it, define a method that
71    overrides {@link android.app.IntentService#onHandleIntent onHandleIntent()}. For example:
72</p>
73<pre>
74public class RSSPullService extends IntentService {
75    &#64;Override
76    protected void onHandleIntent(Intent workIntent) {
77        // Gets data from the incoming Intent
78        String dataString = workIntent.getDataString();
79        ...
80        // Do work here, based on the contents of dataString
81        ...
82    }
83}
84</pre>
85<p>
86    Notice that the other callbacks of a regular {@link android.app.Service} component, such as
87    {@link android.app.Service#onStartCommand onStartCommand()} are automatically invoked by
88    {@link android.app.IntentService}. In an {@link android.app.IntentService}, you should avoid
89    overriding these callbacks.
90</p>
91<h2 id="DefineManifest">Define the IntentService in the Manifest</h2>
92<p>
93    An {@link android.app.IntentService} also needs an entry in your application manifest.
94    Provide this entry as a
95    <code><a href="{@docRoot}guide/topics/manifest/service-element.html">&lt;service&gt;</a></code>
96    element that's a child of the
97    <code><a href="{@docRoot}guide/topics/manifest/application-element.html">
98    &lt;application&gt;</a></code> element:
99</p>
100<pre>
101    &lt;application
102        android:icon="&#64;drawable/icon"
103        android:label="&#64;string/app_name"&gt;
104        ...
105        &lt;!--
106            Because android:exported is set to "false",
107            the service is only available to this app.
108        --&gt;
109        &lt;service
110            android:name=".RSSPullService"
111            android:exported="false"/&gt;
112        ...
113    &lt;application/&gt;
114</pre>
115<p>
116    The attribute <code>android:name</code> specifies the class name of the
117    {@link android.app.IntentService}.
118</p>
119<p>
120    Notice that the
121    <code><a href="{@docRoot}guide/topics/manifest/service-element.html">&lt;service&gt;</a></code>
122    element doesn't contain an intent filter. The {@link android.app.Activity} that sends work
123    requests to the service uses an explicit {@link android.content.Intent}, so no filter is needed.
124    This also means that only components in the same app or other applications with the same user ID
125    can access the service.
126</p>
127<p>
128    Now that you have the basic {@link android.app.IntentService} class, you can send work requests
129    to it with {@link android.content.Intent} objects. The procedure for constructing these objects
130    and sending them to your {@link android.app.IntentService} is described in the next lesson.
131</p>
132