Leaving tasks running when the app is shut down

Frequently in an app we need to perform a task when the activity has been completely shut down. For example, in a music player, we probably want the music to continue to play when the user has closed the player's main activity - and we want the user to be able to pause or rewind the same music when they relaunch the activity. Another example might be a mapping application in which the user would like to record their walking route using GPS. We want the recording to continue even if the user closes the activity - and allow the user to stop the recording if they re-launch the activity.

• To deal with these scenarios we use Services (see the Android developer documentation for full details - here).
• A Service is a background application component which is part of an application but is independent of any of the application's Activities.
• As they are part of the application, we have to declare all our services in the manifest, immediately after declaring our activities e.g.

  <service android:name=".MusicService"></service>

Difference between a service and a coroutine

• It is important to note that a Service is not the same as a coroutine.
• It is a separate component to an Activity, but by default it does not run in the background.
• If you wish your service to perform tasks such as connecting to the Internet, you will need to implement a coroutine within the service and switch to a background context
• To launch coroutines from a service, you need to use the androidx.lifecycle.LifecycleService class rather than an ordinary Service; this requires the dependency androidx.lifecycle:lifecycle-service:X.Y.Z where X.Y.Z is the version; the current version is 2.7.0.

Implementing a Service

• You must create a class (separate to your Activity) which extends from android.app.Service and then launch it from the main activity.
• To launch a Service, you can either start or bind it, or both.
• Starting a service is intended for long-running services, which will run even if the Activity you start them from is closed down.
• Binding a service is intended for shorter-running services, which are bound to a particular instance of an Activity and will stop when the Activity shuts down (e.g. a music player which only plays while the Activity is running). Binding is useful if you want to be able to access the service directly from the activity; if you start the service and do not bind it, you are unable to do this.
• Even though in many cases you do not need to bind a service, you must still provide the onBind() method in your service, but it can return null.
• It is possible to both start and bind a service, if you want the service to keep running when the activity is destroyed and you want to easily access it from the activity.
• Example of a template service:

  import android.app.Service
  import android.content.Intent
  import android.os.IBinder
  
  class MyService: Service() {
  
      // start handler
      override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
          return START_STICKY // we will look at this return value below
      }
  
      // bind handler - not needed in many cases but defined as an abstract
      // method in Service, therefore must be overridden
      override fun onBind(intent: Intent?): IBinder? {
          return null // can just return null if binding is not needed
      }
  
  }
  

Service lifecycle methods

Rather like activities, services have lifecycle methods including:

• onCreate() - when the service is created;
• onStartCommand(intent: Intent?, startFlags: Int, id: Int): Int - runs when a service is started (see below);
• onBind(intent: Intent?): IBinder? - runs when a service is bound. As seen above, you have to implement this even if you do not use binding, but it can just return null
• onDestroy() - when a service is destroyed.

Starting a service

• Starting a service is the easiest, you create an Intent to start a particular Service (similar to creating an Intent to launch a secondary activity) and then call startService():

  val startIntent = Intent(this, MusicService::class.java)
  startService(startIntent)
  

• This will have the effect both of creating a long-lasting service (which will continue until the service has done its work), though it may be killed if memory becomes low
• Generally you should make your service a background service (the default). You can alternatively make it a foreground service if you want to minimise the chance of it being killed due to low memory, however this is not recommended as it might result in apps the user is actively using being killed instead. Mark Murphy, a well-known authority in Android development, talks about this issue with services. If you really do need a foreground service, you must also provide a notification to the user.

Using onStartCommand() to start the service

• As we have seen, onStartCommand() is called when a service is started with startService()
• The return value is important; if you want the service to be restarted if it is killed when memory becomes low, you should return a value of START_STICKY (see here)
• If you don't want it to be restarted, return START_NOT_STICKY instead
• Here is an example using START_STICKY:

   override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
          
      // do something, e.g. start GPS, or music playing, etc.
  
      return START_STICKY // Important if you want service to be restarted!
  
  }
  

• If the service is restarted due to previously being killed because of low memory, the intent parameter will be null (again, see here; otherwise, this is the intent used to start the service)

Stopping a service and overriding onDestroy()

• It's possible that you want your activity to stop a service at any time
• To do this you can call stopService() with the same Intent used to start the service, for example:

  stopService(serviceIntent)

• When a service is stopped, the onDestroy() method of the service will be called. In the Service's onDestroy(), you must stop any threads, background tasks, etc. that the Service is running, as otherwise, the thread will continue to run after its parent Service has been destroyed, resulting in possible memory leaks and unintended behaviour

Binding a service

While starting a service is best for long running services, it has the disadvantage that you will not have a reference to the Service in the Activity. If you want to be able to easily control your Service from your Activity, there are two main approaches:

• Using broadcasts. This is discussed later.
• Bind the service. This gives you a reference to the service from the activity, which you can then use to control the service.

We will first look at binding the service. You must bind it instead of, or in addition to, starting the service (see the Android documentation for more details).

Binding a service is a little trickier than starting it as you need to provide a Binder object. This is an interface to the service which gives the outside world (e.g. the activity) access to it. The Binder object is an object which inherits from android.os.Binder.

The Activity is able to access the Binder (see below) and, as long as the Binder has a method which returns the Service, can obtain the Service. Thus, the Binder should provide a method to return the service.

As seen above, you must also provide an onBind() method within the Service to create a new Binder object and return it when the Activity binds to the service. Remember that you need this method even if you do not intend to use binding, but it can return null in that case.

A common pattern is to have the Binder as an inner class of the Service (an inner class is a class within another class)

Architecture of binding

To bind a service, we need two more components, a Binder (as we have seen) and a ServiceConnection, which is used to provide a connection between the activity and the service, and is discussed further below. The architecture of binding a service, showing the Binder and ServiceConnection, is shown below:

Example

Here is an example. (Note that IBinder is an interface which Binder implements).

class MusicService: Service() {
    inner class MusicServiceBinder(val musicService: MusicService): android.os.Binder()

    override fun onBind(intent:Intent) : IBinder {
        return MusicServiceBinder(this)
    }
}

Note the following:

• The service contains a binder as an inner class. An instance of the binder is created, and returned, in the onBind() method. This method runs when the activity binds to it.
• The binder has a reference to the service within it, i.e. musicService. This is needed as the activity will receive only the binder, not the service. Thus, if the activity wants the service, it must obtain it from the binder.

The ServiceConnection

As we have seen, in our activity, we must create a ServiceConnection object, to obtain a connection to the service. Here is an example - this might go in your onCreate():

 val serviceConn = object: ServiceConnection {
     override fun onServiceConnected(name: ComponentName?, binder: IBinder?) {
        service = (binder as MusicService.MusicServiceBinder).musicService
     }

     override fun onServiceDisconnected(name: ComponentName?) {
     }
 }

It is an instance of an anonymous class (a class with no name, which inherits from the abstract class ServiceConnection and overrides the required methods on-the-fly. These methods are:

• The onServiceConnected() method is a callback method which runs as soon as the Activity has been bound to the Service. The Binder object (the inner class within our Service, see above) is provided as a parameter to onServiceConnected(), so we cast it to the correct object (MusicService.MusicServiceBinder) and obtain our Service using its service attribute.
• onServiceDisconnected() runs when the service is disconnected from the activity. Here, we're not doing anything in the method but we still need to override it.

Using bindService() to initiate the binding

Finally, In your main activity, you bind the service using bindService() which, like startService() takes an Intent for the Service.

val bindIntent = Intent(this, MusicService::class.java);
bindService(bindIntent, serviceConn,  Context.BIND_AUTO_CREATE)

This will bind the activity to the service and trigger the onBind() method in the MusicService. The Context.BIND_AUTO_CREATE flag will "automatically create the service as long as the binding exists" (see here), without this flag, you will also need to call startService() to start the service.

Unbinding

• When an Activity is destroyed (i.e. when onDestroy() is called), you should call unbindService() to let Android know that the activity does not wish to be connected anymore.
• By default, the service will be destroyed if no activities are currently connected to it
• unbindService() takes the ServiceConnection as an argument
• e.g.:

  override fun onDestroy() {
      super.onDestroy()
      unbindService(gpsServiceConn)
  }
  

Starting and binding

• What if we wish to bind a service, but want the service to keep going even if an Activity is not running?
• This would be the case in both a music player and a GPS recorder, in which we want a GPS track to record even if the activity shuts down
• In this case, we need to call both startService() and bindService().
• This will have the effect both of creating a long-lasting service (which will continue until the service has done its work) - this is enabled with startService() - and allowing the activity to control the service - this is done with bindService().
• You should still call unbindService() when the activity is destroyed.

Broadcasts

• Broadcasts allow us to use Intents to send information between components, and components can also listen to broadcasts. These components may belong to completely different applications or the same application
• Using broadcasts allows for clean, easy to understand, loosely-coupled components
• A broadcast is an Intent and as such can pass data to another application component as a Bundle

BroadcastReceiver

• To receive a broadcast in a component, we need to create a BroadcastReceiver object
• A BroadcastReceiver can receive intents and act upon them according to the intent's action
• To use a BroadcastReceiver you must also use an IntentFilter
• An IntentFilter allows you to control which intents an application component can receive
• Intents which do not match the filter will be ignored

Example of sending a broadcast

val broadcast = Intent().apply {
    action = "sendTime"
    putExtra("time", System.currentTimeMillis())
}
sendBroadcast(broadcast)

• We are creating an intent with an action of sendTime
• The intent contains an extra, time, containing the current time in milliseconds since Jan 1st 1970
• We then use sendBroadcast() to send the Intent as a broadcast
• This might typically be placed in a Service (so that the Service can broadcast updates to one or more activities) but could equally well be placed in any application component, such as an activity

Receiving a broadcast

• This code, typically appearing in an Activity, shows a broadcast receiver:

  receiver = object:BroadcastReceiver() {
      override fun onReceive(context: Context?, intent: Intent?) {
           when (intent?.action) {
                  "sendTime" -> toast("${intent?.getLongExtra("time", 0)}")
              }
          }
   }
  

• We then need to set up an IntentFilter in our activity to explicitly state that this activity is capable of receiving intents with an action of sendTime:

  val filter = IntentFilter().apply {
      addAction("sendTime")
  }
  

• Note how we first check that the intent's action is indeed sendTime. Even though this is specified by the intent filter, it is recommended to do this as "it is possible for senders to force delivery to specific recipients, bypassing filter resolution" (see the documentation)
• We then register the receiver with the Activity (or whatever application component is receiving it), specifying both receiver and intent filter:

  ContextCompat.registerReceiver(this, receiver, intentFilter, ContextCompat.RECEIVER_NOT_EXPORTED)

• ContextCompat.RECEIVER_NOT_EXPORTED specifies that we cannot receive broadcasts from other apps, which is useful for security. In theory, an app could send a malicious broadcast to another app which could have harmful side effects, so if we don't need inter-app communication when receiving broadcasts, we should turn it off.
• We use ContextCompat because we are using the compatibility version of the call; RECEIVER_NOT_EXPORTED was only introduced in API 33. The compatibility (appcompat) library allows us to use newer API features on older versions of Android.

Unregistering a broadcast receiver

• A broadcast receiver must be unregistered on shutdown of the component receiving it
• This would typically go in onDestroy()
• e.g.

  override fun onDestroy() {
      super.onDestroy()
      unregisterReceiver(receiver)
  }