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 | |
Mathew Inwood | 4fb17d1 | 2018-08-14 14:25:44 +0100 | [diff] [blame] | 19 | import android.annotation.UnsupportedAppUsage; |
Tor Norbye | 83c6896 | 2015-03-10 20:55:31 -0700 | [diff] [blame] | 20 | import android.annotation.WorkerThread; |
Ryan Lothian | ce8d4f5 | 2016-01-21 15:07:01 +0000 | [diff] [blame] | 21 | import android.annotation.Nullable; |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 22 | import android.content.Intent; |
| 23 | import android.os.Handler; |
| 24 | import android.os.HandlerThread; |
| 25 | import android.os.IBinder; |
| 26 | import android.os.Looper; |
| 27 | import android.os.Message; |
| 28 | |
| 29 | /** |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 30 | * IntentService is a base class for {@link Service}s that handle asynchronous |
| 31 | * requests (expressed as {@link Intent}s) on demand. Clients send requests |
Wu-cheng Li | cae57d6 | 2010-04-07 13:52:37 +0800 | [diff] [blame] | 32 | * through {@link android.content.Context#startService(Intent)} calls; the |
| 33 | * service is started as needed, handles each Intent in turn using a worker |
| 34 | * 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] | 35 | * |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 36 | * <p>This "work queue processor" pattern is commonly used to offload tasks |
| 37 | * from an application's main thread. The IntentService class exists to |
| 38 | * simplify this pattern and take care of the mechanics. To use it, extend |
| 39 | * IntentService and implement {@link #onHandleIntent(Intent)}. IntentService |
| 40 | * will receive the Intents, launch a worker thread, and stop the service as |
| 41 | * appropriate. |
| 42 | * |
| 43 | * <p>All requests are handled on a single worker thread -- they may take as |
| 44 | * long as necessary (and will not block the application's main loop), but |
| 45 | * only one request will be processed at a time. |
| 46 | * |
Andrew Solovay | 494f1a4 | 2017-07-31 19:13:38 -0700 | [diff] [blame] | 47 | * <p class="note"><b>Note:</b> IntentService is subject to all the |
| 48 | * <a href="/preview/features/background.html">background execution limits</a> |
| 49 | * imposed with Android 8.0 (API level 26). In most cases, you are better off |
| 50 | * using {@link android.support.v4.app.JobIntentService}, which uses jobs |
| 51 | * instead of services when running on Android 8.0 or higher. |
| 52 | * </p> |
| 53 | * |
Joe Fernandez | b54e7a3 | 2011-10-03 15:09:50 -0700 | [diff] [blame] | 54 | * <div class="special reference"> |
| 55 | * <h3>Developer Guides</h3> |
| 56 | * <p>For a detailed discussion about how to create services, read the |
Hemal Patel | 1918214 | 2016-09-30 14:59:23 -0700 | [diff] [blame] | 57 | * <a href="{@docRoot}guide/components/services.html">Services</a> developer |
| 58 | * guide.</p> |
Joe Fernandez | b54e7a3 | 2011-10-03 15:09:50 -0700 | [diff] [blame] | 59 | * </div> |
| 60 | * |
Andrew Solovay | 494f1a4 | 2017-07-31 19:13:38 -0700 | [diff] [blame] | 61 | * @see android.support.v4.app.JobIntentService |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 62 | * @see android.os.AsyncTask |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 63 | */ |
| 64 | public abstract class IntentService extends Service { |
| 65 | private volatile Looper mServiceLooper; |
Mathew Inwood | 4fb17d1 | 2018-08-14 14:25:44 +0100 | [diff] [blame] | 66 | @UnsupportedAppUsage |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 67 | private volatile ServiceHandler mServiceHandler; |
| 68 | private String mName; |
Dianne Hackborn | f6f9f2d | 2009-08-21 16:26:03 -0700 | [diff] [blame] | 69 | private boolean mRedelivery; |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 70 | |
| 71 | private final class ServiceHandler extends Handler { |
| 72 | public ServiceHandler(Looper looper) { |
| 73 | super(looper); |
| 74 | } |
| 75 | |
| 76 | @Override |
| 77 | public void handleMessage(Message msg) { |
| 78 | onHandleIntent((Intent)msg.obj); |
| 79 | stopSelf(msg.arg1); |
| 80 | } |
| 81 | } |
| 82 | |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 83 | /** |
| 84 | * Creates an IntentService. Invoked by your subclass's constructor. |
| 85 | * |
| 86 | * @param name Used to name the worker thread, important only for debugging. |
| 87 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 88 | public IntentService(String name) { |
| 89 | super(); |
| 90 | mName = name; |
| 91 | } |
| 92 | |
Dianne Hackborn | f6f9f2d | 2009-08-21 16:26:03 -0700 | [diff] [blame] | 93 | /** |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 94 | * Sets intent redelivery preferences. Usually called from the constructor |
| 95 | * with your preferred semantics. |
| 96 | * |
| 97 | * <p>If enabled is true, |
Dianne Hackborn | f6f9f2d | 2009-08-21 16:26:03 -0700 | [diff] [blame] | 98 | * {@link #onStartCommand(Intent, int, int)} will return |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 99 | * {@link Service#START_REDELIVER_INTENT}, so if this process dies before |
| 100 | * {@link #onHandleIntent(Intent)} returns, the process will be restarted |
| 101 | * and the intent redelivered. If multiple Intents have been sent, only |
| 102 | * the most recent one is guaranteed to be redelivered. |
| 103 | * |
| 104 | * <p>If enabled is false (the default), |
| 105 | * {@link #onStartCommand(Intent, int, int)} will return |
| 106 | * {@link Service#START_NOT_STICKY}, and if the process dies, the Intent |
| 107 | * dies along with it. |
Dianne Hackborn | f6f9f2d | 2009-08-21 16:26:03 -0700 | [diff] [blame] | 108 | */ |
| 109 | public void setIntentRedelivery(boolean enabled) { |
| 110 | mRedelivery = enabled; |
| 111 | } |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 112 | |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 113 | @Override |
| 114 | public void onCreate() { |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 115 | // TODO: It would be nice to have an option to hold a partial wakelock |
| 116 | // during processing, and to have a static startService(Context, Intent) |
| 117 | // method that would launch the service & hand off a wakelock. |
| 118 | |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 119 | super.onCreate(); |
| 120 | HandlerThread thread = new HandlerThread("IntentService[" + mName + "]"); |
| 121 | thread.start(); |
| 122 | |
| 123 | mServiceLooper = thread.getLooper(); |
| 124 | mServiceHandler = new ServiceHandler(mServiceLooper); |
| 125 | } |
| 126 | |
| 127 | @Override |
Ryan Lothian | ce8d4f5 | 2016-01-21 15:07:01 +0000 | [diff] [blame] | 128 | public void onStart(@Nullable Intent intent, int startId) { |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 129 | Message msg = mServiceHandler.obtainMessage(); |
| 130 | msg.arg1 = startId; |
| 131 | msg.obj = intent; |
| 132 | mServiceHandler.sendMessage(msg); |
| 133 | } |
| 134 | |
Scott Main | 7a14b93 | 2010-10-04 18:30:46 -0700 | [diff] [blame] | 135 | /** |
| 136 | * You should not override this method for your IntentService. Instead, |
| 137 | * override {@link #onHandleIntent}, which the system calls when the IntentService |
| 138 | * receives a start request. |
| 139 | * @see android.app.Service#onStartCommand |
| 140 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 141 | @Override |
Ryan Lothian | ce8d4f5 | 2016-01-21 15:07:01 +0000 | [diff] [blame] | 142 | public int onStartCommand(@Nullable Intent intent, int flags, int startId) { |
Dianne Hackborn | f6f9f2d | 2009-08-21 16:26:03 -0700 | [diff] [blame] | 143 | onStart(intent, startId); |
| 144 | return mRedelivery ? START_REDELIVER_INTENT : START_NOT_STICKY; |
| 145 | } |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 146 | |
Dianne Hackborn | f6f9f2d | 2009-08-21 16:26:03 -0700 | [diff] [blame] | 147 | @Override |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 148 | public void onDestroy() { |
| 149 | mServiceLooper.quit(); |
| 150 | } |
| 151 | |
Scott Main | 7a14b93 | 2010-10-04 18:30:46 -0700 | [diff] [blame] | 152 | /** |
| 153 | * 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] | 154 | * method, because the default implementation returns null. |
Scott Main | 7a14b93 | 2010-10-04 18:30:46 -0700 | [diff] [blame] | 155 | * @see android.app.Service#onBind |
| 156 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 157 | @Override |
Ryan Lothian | ce8d4f5 | 2016-01-21 15:07:01 +0000 | [diff] [blame] | 158 | @Nullable |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 159 | public IBinder onBind(Intent intent) { |
| 160 | return null; |
| 161 | } |
| 162 | |
| 163 | /** |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 164 | * This method is invoked on the worker thread with a request to process. |
| 165 | * Only one Intent is processed at a time, but the processing happens on a |
| 166 | * worker thread that runs independently from other application logic. |
| 167 | * So, if this code takes a long time, it will hold up other requests to |
| 168 | * the same IntentService, but it will not hold up anything else. |
Scott Main | 7a14b93 | 2010-10-04 18:30:46 -0700 | [diff] [blame] | 169 | * When all requests have been handled, the IntentService stops itself, |
| 170 | * so you should not call {@link #stopSelf}. |
Dan Egnor | 6e3d988 | 2010-04-06 18:28:42 -0700 | [diff] [blame] | 171 | * |
Wu-cheng Li | cae57d6 | 2010-04-07 13:52:37 +0800 | [diff] [blame] | 172 | * @param intent The value passed to {@link |
| 173 | * android.content.Context#startService(Intent)}. |
Ryan Lothian | ce8d4f5 | 2016-01-21 15:07:01 +0000 | [diff] [blame] | 174 | * This may be null if the service is being restarted after |
| 175 | * its process has gone away; see |
| 176 | * {@link android.app.Service#onStartCommand} |
| 177 | * for details. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 178 | */ |
Tor Norbye | 83c6896 | 2015-03-10 20:55:31 -0700 | [diff] [blame] | 179 | @WorkerThread |
Ryan Lothian | ce8d4f5 | 2016-01-21 15:07:01 +0000 | [diff] [blame] | 180 | protected abstract void onHandleIntent(@Nullable Intent intent); |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 181 | } |