Aug 22, 2013

Read the code: IntentService

In the new category Read the code I’m going to show the internals of the Android framework. Reading the code of the framework can give you a good impression about what’s going on under the hood. In addition to that knowing how the framework developers solved common problems can help you to find the best solutions when facing problems in your own app code.

What is the IntentService class good for?
This article is about the IntentService class of Android. Extending the IntentService class is the best solution for implementing a background service that is going to process something in a queue-like fashion. You can pass data via Intents to the IntentService and it will take care of queuing and processing the Intents on a worker thread one at a time. When writing your IntentService implementation you are required to override the onHandleIntent() method to process the data of the supplied Intents.

Let’s take a look at a simple example: This DownloadService class receives Uris to download data from. It will download only one thing at a time with the other requests waiting in a queue.

DownloadService


The components
Before we dip into the source code of the IntentService class, let's first take a look at the different components that we need to know in order to understand the source code.

Handler (documentation) (source code)
You may already have used Handler objects. When a Handler is created on the UI thread, messages can be posted to it and these messages will be processed on the UI thread.

ServiceHandler (source code)
The ServiceHandler inner-class is a helper class extending the Handler class to delegate the Intent wrapped inside a Message object to the IntentService for processing.

ServiceHandler inner class of android.app.IntentService

Looper (documentation) (source code)
The Looper class has a MessageQueue object attached to it and blocks the current thread until a Message is received. This message will be passed to the assigned Handler. After that the Looper processes the next message in the queue or blocks again until a message is received.

HandlerThread (documentation) (source code)
A HandlerThread is a Thread implementation that does all the Looper setup for you. By creating and starting a HandlerThread instance you will have a running thread with a Looper attached to it waiting for messages to process.

Read the code!

Now we know enough about all the components to understand the IntentService code.

onCreate()

IntentService.onCreate()

At first a HandlerThread is created and started. We now have a background thread running that already has a Looper assigned. This Looper is waiting on the background thread for messages to process.

Next a ServiceHandler is created for this Looper. The Handler’s handleMessage() method will be called for every message received by the Looper. The ServiceHandler obtains the Intent object from the Message and passes it to the onHandleIntent() method of the IntentService.

onStart()

IntentService.onStart()

The onStart() method is called every time startService() is called. We wrap the Intent in a Message object and post it to the Handler. The Handler will enqueue it in the message queue of the Looper. The onStart() method is deprecated since API level 5 (Android 2.0). Instead onStartCommand() should be implemented.

onStartCommand()

IntentService.onStartCommand()
In onStartCommand() we call onStart() to enqueue the Intent. We return START_REDELIVER_INTENT or START_NOT_STICK depending on what the child class has set via setIntentRedelivery(). Depending on this setting an Intent will be redelivered to the service if the process dies before onHandleIntent() returns or the Intent will die as well.

onDestroy()

IntentService.onDestroy()
In onDestroy() we just need to stop the Looper.

Conclusion

The IntentService code is quite short and simple, yet a powerful pattern. With the Handler, Looper and Thread class you can easily build your own simple processing queues.

Oh, and if you are looking for an exercise. The code of the onCreate() method contains a TODO comment that I omitted above:

TODO in onCreate()