Mobile Development and 3D Graphics - Part 3

Introduction to Services and Broadcasts

Introduction - 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.

Services

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 thread

It is important to note that a Service is not the same as a thread.
It is a separate component to an Activity, but by default it does not run in a separate thread.
If you wish your service to perform tasks such as connecting to the Internet, you will need to implement a coroutine or thread within the service

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)
Even though in many cases you do not need to bind a service, you must still provide the onBind() method in your service

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

Services, like activities, 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 (we will do notifications next week).

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, 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 as you need to provide a Binder object which provides access to your Service from your Activity.
The Binder object is an object which inherits from android.os.Binder and provides a method to return the Service.
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.
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.
A common pattern is to have the Binder as an inner class of the Service.

Binding a service - example

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. 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

In our activity, we must create a ServiceConnection object, to obtain a connection to the service. Here is an example:

 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 actually bind the service

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 destroying an Activity, 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")
}
```
We then register the receiver with the Activity (or whatever application component is receiving it), specifying both receiver and intent filter:
```
registerReceiver(receiver, filter)
```
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)

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)
}

Exercises

Start with this GitHub repository:
```
https://github.com/nwcourses/ServicesStarter.git
```
which is another version of the mapping application. It features a map plus three buttons: "Start GPS", "Get GPS location" and "Stop GPS". Using a service, complete the app as follows. The functionality associated with each button should only run if the permissionsGranted boolean is true.
- In the activity's empty initService() method, start and bind the service. The service should contain a LocationListener. Start this up in a method of the service called startGps() and call this from onStartCommand(). Also write a method in the service called stopGps and remove updates on the listener in this method. Call this method from the onDestroy() in the service.
- "Start GPS" - start the GPS service. You should call the service's startGps() method.
- "Get GPS location" - query the service to get the GPS location. You'll need to use binding for this. Update the ViewModel accordingly.
- "Stop GPS" - stop the GPS service. You should call the service's stopGps() method.
Test by using the emulator and sending mock locations -GPS is unlikely to work indoors.
Modify the app to use broadcasts as follows:
- A broadcast should be used to continuously notify the main activity of location changes. Comment out the code to bind the service in the activity. In the service, when a new location is received, send a broadcast containing the latitude and longitude, using a custom name for the action.. In your activity, update the view model with that latitude and longitude when the broadcast is received.
- Modify the behaviour of your "Start GPS" and "Stop GPS" buttons. Using broadcasts, send intents from the activity to the service. Write a broadcast receiver in the service which receives these broadcasts and starts and stops the location listener, respectively (using the startGps() and stopGps() methods). Register the receiver in onStartCommand().