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