IntentService.java revision 15a4d2ffd04dc6c70f2cd17dae12ac6bc14c69ab 
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.content.Intent;
20import android.os.Handler;
21import android.os.HandlerThread;
22import android.os.IBinder;
23import android.os.Looper;
24import android.os.Message;
25
26/**
27 * An abstract {@link Service} that serializes the handling of the Intents passed upon service
28 * start and handles them on a handler thread.
29 *
30 * <p>To use this class extend it and implement {@link #onHandleIntent}. The {@link Service} will
31 * automatically be stopped when the last enqueued {@link Intent} is handled.
32 */
33public abstract class IntentService extends Service {
34    private volatile Looper mServiceLooper;
35    private volatile ServiceHandler mServiceHandler;
36    private String mName;
37    private boolean mRedelivery;
38
39    private final class ServiceHandler extends Handler {
40        public ServiceHandler(Looper looper) {
41            super(looper);
42        }
43
44        @Override
45        public void handleMessage(Message msg) {
46            onHandleIntent((Intent)msg.obj);
47            stopSelf(msg.arg1);
48        }
49    }
50
51    public IntentService(String name) {
52        super();
53        mName = name;
54    }
55
56    /**
57     * Control redelivery of intents.  If called with true,
58     * {@link #onStartCommand(Intent, int, int)} will return
59     * {@link Service#START_REDELIVER_INTENT} instead of
60     * {@link Service#START_NOT_STICKY}, so that if this service's process
61     * is killed while it is executing the Intent in
62     * {@link #onHandleIntent(Intent)}, then when later restarted the same Intent
63     * will be re-delivered to it, to retry its execution.
64     */
65    public void setIntentRedelivery(boolean enabled) {
66        mRedelivery = enabled;
67    }
68
69    @Override
70    public void onCreate() {
71        super.onCreate();
72        HandlerThread thread = new HandlerThread("IntentService[" + mName + "]");
73        thread.start();
74
75        mServiceLooper = thread.getLooper();
76        mServiceHandler = new ServiceHandler(mServiceLooper);
77    }
78
79    @Override
80    public void onStart(Intent intent, int startId) {
81        Message msg = mServiceHandler.obtainMessage();
82        msg.arg1 = startId;
83        msg.obj = intent;
84        mServiceHandler.sendMessage(msg);
85    }
86
87    @Override
88    public int onStartCommand(Intent intent, int flags, int startId) {
89        onStart(intent, startId);
90        return mRedelivery ? START_REDELIVER_INTENT : START_NOT_STICKY;
91    }
92
93    @Override
94    public void onDestroy() {
95        mServiceLooper.quit();
96    }
97
98    @Override
99    public IBinder onBind(Intent intent) {
100        return null;
101    }
102
103    /**
104     * Invoked on the Handler thread with the {@link Intent} that is passed to {@link #onStart}.
105     * Note that this will be invoked from a different thread than the one that handles the
106     * {@link #onStart} call.
107     */
108    protected abstract void onHandleIntent(Intent intent);
109}
110