1 /*
2  * Copyright (C) 2008 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.app;
18 
19 import android.annotation.WorkerThread;
20 import android.annotation.Nullable;
21 import android.content.Intent;
22 import android.os.Handler;
23 import android.os.HandlerThread;
24 import android.os.IBinder;
25 import android.os.Looper;
26 import android.os.Message;
27 
28 /**
29  * IntentService is a base class for {@link Service}s that handle asynchronous
30  * requests (expressed as {@link Intent}s) on demand.  Clients send requests
31  * through {@link android.content.Context#startService(Intent)} calls; the
32  * service is started as needed, handles each Intent in turn using a worker
33  * thread, and stops itself when it runs out of work.
34  *
35  * <p>This "work queue processor" pattern is commonly used to offload tasks
36  * from an application's main thread.  The IntentService class exists to
37  * simplify this pattern and take care of the mechanics.  To use it, extend
38  * IntentService and implement {@link #onHandleIntent(Intent)}.  IntentService
39  * will receive the Intents, launch a worker thread, and stop the service as
40  * appropriate.
41  *
42  * <p>All requests are handled on a single worker thread -- they may take as
43  * long as necessary (and will not block the application's main loop), but
44  * only one request will be processed at a time.
45  *
46  * <div class="special reference">
47  * <h3>Developer Guides</h3>
48  * <p>For a detailed discussion about how to create services, read the
49  * <a href="{@docRoot}guide/components/services.html">Services</a> developer
50  * guide.</p>
51  * </div>
52  *
53  * @see android.os.AsyncTask
54  */
55 public abstract class IntentService extends Service {
56     private volatile Looper mServiceLooper;
57     private volatile ServiceHandler mServiceHandler;
58     private String mName;
59     private boolean mRedelivery;
60 
61     private final class ServiceHandler extends Handler {
ServiceHandler(Looper looper)62         public ServiceHandler(Looper looper) {
63             super(looper);
64         }
65 
66         @Override
handleMessage(Message msg)67         public void handleMessage(Message msg) {
68             onHandleIntent((Intent)msg.obj);
69             stopSelf(msg.arg1);
70         }
71     }
72 
73     /**
74      * Creates an IntentService.  Invoked by your subclass's constructor.
75      *
76      * @param name Used to name the worker thread, important only for debugging.
77      */
IntentService(String name)78     public IntentService(String name) {
79         super();
80         mName = name;
81     }
82 
83     /**
84      * Sets intent redelivery preferences.  Usually called from the constructor
85      * with your preferred semantics.
86      *
87      * <p>If enabled is true,
88      * {@link #onStartCommand(Intent, int, int)} will return
89      * {@link Service#START_REDELIVER_INTENT}, so if this process dies before
90      * {@link #onHandleIntent(Intent)} returns, the process will be restarted
91      * and the intent redelivered.  If multiple Intents have been sent, only
92      * the most recent one is guaranteed to be redelivered.
93      *
94      * <p>If enabled is false (the default),
95      * {@link #onStartCommand(Intent, int, int)} will return
96      * {@link Service#START_NOT_STICKY}, and if the process dies, the Intent
97      * dies along with it.
98      */
setIntentRedelivery(boolean enabled)99     public void setIntentRedelivery(boolean enabled) {
100         mRedelivery = enabled;
101     }
102 
103     @Override
onCreate()104     public void onCreate() {
105         // TODO: It would be nice to have an option to hold a partial wakelock
106         // during processing, and to have a static startService(Context, Intent)
107         // method that would launch the service & hand off a wakelock.
108 
109         super.onCreate();
110         HandlerThread thread = new HandlerThread("IntentService[" + mName + "]");
111         thread.start();
112 
113         mServiceLooper = thread.getLooper();
114         mServiceHandler = new ServiceHandler(mServiceLooper);
115     }
116 
117     @Override
onStart(@ullable Intent intent, int startId)118     public void onStart(@Nullable Intent intent, int startId) {
119         Message msg = mServiceHandler.obtainMessage();
120         msg.arg1 = startId;
121         msg.obj = intent;
122         mServiceHandler.sendMessage(msg);
123     }
124 
125     /**
126      * You should not override this method for your IntentService. Instead,
127      * override {@link #onHandleIntent}, which the system calls when the IntentService
128      * receives a start request.
129      * @see android.app.Service#onStartCommand
130      */
131     @Override
onStartCommand(@ullable Intent intent, int flags, int startId)132     public int onStartCommand(@Nullable Intent intent, int flags, int startId) {
133         onStart(intent, startId);
134         return mRedelivery ? START_REDELIVER_INTENT : START_NOT_STICKY;
135     }
136 
137     @Override
onDestroy()138     public void onDestroy() {
139         mServiceLooper.quit();
140     }
141 
142     /**
143      * Unless you provide binding for your service, you don't need to implement this
144      * method, because the default implementation returns null.
145      * @see android.app.Service#onBind
146      */
147     @Override
148     @Nullable
onBind(Intent intent)149     public IBinder onBind(Intent intent) {
150         return null;
151     }
152 
153     /**
154      * This method is invoked on the worker thread with a request to process.
155      * Only one Intent is processed at a time, but the processing happens on a
156      * worker thread that runs independently from other application logic.
157      * So, if this code takes a long time, it will hold up other requests to
158      * the same IntentService, but it will not hold up anything else.
159      * When all requests have been handled, the IntentService stops itself,
160      * so you should not call {@link #stopSelf}.
161      *
162      * @param intent The value passed to {@link
163      *               android.content.Context#startService(Intent)}.
164      *               This may be null if the service is being restarted after
165      *               its process has gone away; see
166      *               {@link android.app.Service#onStartCommand}
167      *               for details.
168      */
169     @WorkerThread
onHandleIntent(@ullable Intent intent)170     protected abstract void onHandleIntent(@Nullable Intent intent);
171 }
172