Home | History | Annotate | Download | only in run-background-service
      1 page.title=Creating a Background Service
      2 trainingnavtop=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 simple
     59     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>
     74 public 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