Skip to content


Subversion checkout URL

You can clone with
Download ZIP
CommonsWare Android Components: WakefulIntentService

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


CWAC Wakeful: Staying Awake At Work

The recommended pattern for Android's equivalent to cron jobs and Windows scheduled tasks is to use AlarmManager. This works well when coupled with an IntentService, as the service will do its work on a background thread and shut down when there is no more work to do.

There's one small problem: IntentService does nothing to keep the device awake. If the alarm was a WAKEUP variant, the phone will only stay awake on its own while the BroadcastReceiver handling the alarm is in its onReceive() method. Otherwise, the phone may fall back asleep.

WakefulIntentService attempts to combat this by combining the ease of IntentService with a partial WakeLock.

This is available as a JAR file from the downloads area of this GitHub repo. The project itself is set up as an Android library project, in case you wish to use the source code in that fashion.

NOTE: WakefulIntentService v0.4.0 and newer requires Android 2.0+, so it can take advantage of onStartCommand() for better handling of crashed services. Use earlier versions of WakefulIntentService if you wish to try to use it on older versions of Android, though this is not supported.


Any component that wants to send work to a WakefulIntentService subclass needs to call either:

WakefulIntentService.sendWakefulWork(context, MyService.class);

(where MyService.class is the WakefulIntentService subclass)


WakefulIntentService.sendWakefulWork(context, intentOfWork);

(where intentOfWork is an Intent that will be used to call startService() on your WakefulIntentService subclass)

Implementations of WakefulIntentService must override doWakefulWork() instead of onHandleIntent(). doWakefulWork() will be processed within the bounds of a WakeLock. Otherwise, the semantics of doWakefulWork() are identical to onHandleIntent(). doWakefulWork() will be passed the Intent supplied to sendWakefulWork() (or an Intent created by the sendWakefulWork() method, depending on which flavor of that method you use).

And that's it. WakefulIntentService handles the rest.

NOTE: this only works with local services. You have no means of accessing the static WakeLock of a remote service.

NOTE #2: Your application must hold the WAKE_LOCK permission.




This is version v0.4.5 of this module, meaning it is being beaten to a pulp by reusers, prompting some revisions.


In the demo/ project directory and com.commonsware.cwac.wakeful.demo package you will find an OnBootReceiver designed to be attached to the BOOT_COMPLETED broadcast Intent. OnBootReceiver schedules an alarm, which is sent to OnAlarmReceiver. OnAlarmReceiver in turn asks AppService (which extends WakefulIntentService) to do some work in a background thread. It uses the library project itself to access the source code and resources of the WakefulIntentService library.

Note that when you build the JAR via ant jar, the sample activity is not included, nor any resources -- only the compiled classes for the actual library are put into the JAR.


The code in this project is licensed under the Apache Software License 2.0, per the terms of the included LICENSE file.


If you have questions regarding the use of this code, please post a question on StackOverflow tagged with commonsware and android. Be sure to indicate what CWAC module you are having issues with, and be sure to include source code and stack traces if you are encountering crashes.

Release Notes

  • v0.4.5: completed switch to Application as the Context for the WakeLock
  • v0.4.4: switched to Application as the Context for the WakeLock
  • v0.4.3: added better recovery from an Intent redelivery condition
  • v0.4.2: added volatile keyword to static WakeLock for better double-checked locking implementation
  • v0.4.1: added setIntentRedelivery() call, nuked extraneous permissions check
  • v0.4.0: switched to onStartCommand(), requiring Android 2.0+ (API level 5 or higher)
  • v0.3.0: converted to Android library project, added test for WAKE_LOCK permission
Something went wrong with that request. Please try again.