Kenny Root | 15a4d2f | 2010-03-11 18:20:12 -0800 | [diff] [blame] | 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 | |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 17 | package android.app; |
| 18 | |
Tor Norbye | 83c6896 | 2015-03-10 20:55:31 -0700 | [diff] [blame] | 19 | import android.annotation.WorkerThread; |
Ryan Lothian | ce8d4f5 | 2016-01-21 15:07:01 +0000 | [diff] [blame] | 20 | import android.annotation.Nullable; |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | /** |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 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 |
Wu-cheng Li | cae57d6 | 2010-04-07 13:52:37 +0800 | [diff] [blame] | 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. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 34 | * |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 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 | * |
Joe Fernandez | b54e7a3 | 2011-10-03 15:09:50 -0700 | [diff] [blame] | 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/topics/fundamentals/services.html">Services</a> developer guide.</p> |
| 50 | * </div> |
| 51 | * |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 52 | * @see android.os.AsyncTask |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 53 | */ |
| 54 | public abstract class IntentService extends Service { |
| 55 | private volatile Looper mServiceLooper; |
| 56 | private volatile ServiceHandler mServiceHandler; |
| 57 | private String mName; |
Dianne Hackborn | f6f9f2d | 2009-08-21 16:26:03 -0700 | [diff] [blame] | 58 | private boolean mRedelivery; |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 59 | |
| 60 | private final class ServiceHandler extends Handler { |
| 61 | public ServiceHandler(Looper looper) { |
| 62 | super(looper); |
| 63 | } |
| 64 | |
| 65 | @Override |
| 66 | public void handleMessage(Message msg) { |
| 67 | onHandleIntent((Intent)msg.obj); |
| 68 | stopSelf(msg.arg1); |
| 69 | } |
| 70 | } |
| 71 | |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 72 | /** |
| 73 | * Creates an IntentService. Invoked by your subclass's constructor. |
| 74 | * |
| 75 | * @param name Used to name the worker thread, important only for debugging. |
| 76 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 77 | public IntentService(String name) { |
| 78 | super(); |
| 79 | mName = name; |
| 80 | } |
| 81 | |
Dianne Hackborn | f6f9f2d | 2009-08-21 16:26:03 -0700 | [diff] [blame] | 82 | /** |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 83 | * Sets intent redelivery preferences. Usually called from the constructor |
| 84 | * with your preferred semantics. |
| 85 | * |
| 86 | * <p>If enabled is true, |
Dianne Hackborn | f6f9f2d | 2009-08-21 16:26:03 -0700 | [diff] [blame] | 87 | * {@link #onStartCommand(Intent, int, int)} will return |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 88 | * {@link Service#START_REDELIVER_INTENT}, so if this process dies before |
| 89 | * {@link #onHandleIntent(Intent)} returns, the process will be restarted |
| 90 | * and the intent redelivered. If multiple Intents have been sent, only |
| 91 | * the most recent one is guaranteed to be redelivered. |
| 92 | * |
| 93 | * <p>If enabled is false (the default), |
| 94 | * {@link #onStartCommand(Intent, int, int)} will return |
| 95 | * {@link Service#START_NOT_STICKY}, and if the process dies, the Intent |
| 96 | * dies along with it. |
Dianne Hackborn | f6f9f2d | 2009-08-21 16:26:03 -0700 | [diff] [blame] | 97 | */ |
| 98 | public void setIntentRedelivery(boolean enabled) { |
| 99 | mRedelivery = enabled; |
| 100 | } |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 101 | |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 102 | @Override |
| 103 | public void onCreate() { |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 104 | // TODO: It would be nice to have an option to hold a partial wakelock |
| 105 | // during processing, and to have a static startService(Context, Intent) |
| 106 | // method that would launch the service & hand off a wakelock. |
| 107 | |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 108 | super.onCreate(); |
| 109 | HandlerThread thread = new HandlerThread("IntentService[" + mName + "]"); |
| 110 | thread.start(); |
| 111 | |
| 112 | mServiceLooper = thread.getLooper(); |
| 113 | mServiceHandler = new ServiceHandler(mServiceLooper); |
| 114 | } |
| 115 | |
| 116 | @Override |
Ryan Lothian | ce8d4f5 | 2016-01-21 15:07:01 +0000 | [diff] [blame] | 117 | public void onStart(@Nullable Intent intent, int startId) { |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 118 | Message msg = mServiceHandler.obtainMessage(); |
| 119 | msg.arg1 = startId; |
| 120 | msg.obj = intent; |
| 121 | mServiceHandler.sendMessage(msg); |
| 122 | } |
| 123 | |
Scott Main | 7a14b93 | 2010-10-04 18:30:46 -0700 | [diff] [blame] | 124 | /** |
| 125 | * You should not override this method for your IntentService. Instead, |
| 126 | * override {@link #onHandleIntent}, which the system calls when the IntentService |
| 127 | * receives a start request. |
| 128 | * @see android.app.Service#onStartCommand |
| 129 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 130 | @Override |
Ryan Lothian | ce8d4f5 | 2016-01-21 15:07:01 +0000 | [diff] [blame] | 131 | public int onStartCommand(@Nullable Intent intent, int flags, int startId) { |
Dianne Hackborn | f6f9f2d | 2009-08-21 16:26:03 -0700 | [diff] [blame] | 132 | onStart(intent, startId); |
| 133 | return mRedelivery ? START_REDELIVER_INTENT : START_NOT_STICKY; |
| 134 | } |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 135 | |
Dianne Hackborn | f6f9f2d | 2009-08-21 16:26:03 -0700 | [diff] [blame] | 136 | @Override |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 137 | public void onDestroy() { |
| 138 | mServiceLooper.quit(); |
| 139 | } |
| 140 | |
Scott Main | 7a14b93 | 2010-10-04 18:30:46 -0700 | [diff] [blame] | 141 | /** |
| 142 | * Unless you provide binding for your service, you don't need to implement this |
Ryan Lothian | ce8d4f5 | 2016-01-21 15:07:01 +0000 | [diff] [blame] | 143 | * method, because the default implementation returns null. |
Scott Main | 7a14b93 | 2010-10-04 18:30:46 -0700 | [diff] [blame] | 144 | * @see android.app.Service#onBind |
| 145 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 146 | @Override |
Ryan Lothian | ce8d4f5 | 2016-01-21 15:07:01 +0000 | [diff] [blame] | 147 | @Nullable |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 148 | public IBinder onBind(Intent intent) { |
| 149 | return null; |
| 150 | } |
| 151 | |
| 152 | /** |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 153 | * This method is invoked on the worker thread with a request to process. |
| 154 | * Only one Intent is processed at a time, but the processing happens on a |
| 155 | * worker thread that runs independently from other application logic. |
| 156 | * So, if this code takes a long time, it will hold up other requests to |
| 157 | * the same IntentService, but it will not hold up anything else. |
Scott Main | 7a14b93 | 2010-10-04 18:30:46 -0700 | [diff] [blame] | 158 | * When all requests have been handled, the IntentService stops itself, |
| 159 | * so you should not call {@link #stopSelf}. |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 160 | * |
Wu-cheng Li | cae57d6 | 2010-04-07 13:52:37 +0800 | [diff] [blame] | 161 | * @param intent The value passed to {@link |
| 162 | * android.content.Context#startService(Intent)}. |
Ryan Lothian | ce8d4f5 | 2016-01-21 15:07:01 +0000 | [diff] [blame] | 163 | * This may be null if the service is being restarted after |
| 164 | * its process has gone away; see |
| 165 | * {@link android.app.Service#onStartCommand} |
| 166 | * for details. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 167 | */ |
Tor Norbye | 83c6896 | 2015-03-10 20:55:31 -0700 | [diff] [blame] | 168 | @WorkerThread |
Ryan Lothian | ce8d4f5 | 2016-01-21 15:07:01 +0000 | [diff] [blame] | 169 | protected abstract void onHandleIntent(@Nullable Intent intent); |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 170 | } |