android.intent.action.ACTION_POWER_CONNECTED<\/code> intent. All apps registered to respond to that intent will start up, demanding RAM, CPU time, and bandwidth. Consequentially, it is possible these simultaneous demands may exceed the available space on the device and cause it to slow down. At this point, all a user knows is that they plugged in their device and it started exhibiting sluggish, unresponsive behavior and may assume something is wrong with their phone or memory.![\"\"](\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/44\/2019\/03\/jobscheduler-1.png\")
<\/p>\nAndroid and the JobScheduler<\/h2>\n
Android 8.0 has introduced new background execution limits<\/a> that dramatically change how services work.\u00a0When applications move into the background, any services they start will be granted several minutes to complete their work before the operating system terminates them. The Android Framework JobScheduler<\/a> is one possible way to address this change for Xamarin.Android apps targeting Android 5.0 (API level 21) or higher.<\/p>\nThe Android Framework\u00a0JobScheduler<\/em><\/a>\u00a0is an API designed to run jobs—discrete, distinct units of work—in the background of various apps. The JobScheduler schedules which jobs will run at appropriate times according to conditions that can be set by the application. Going back to our original example above,\u00a0the JobScheduler\u00a0may schedule the jobs so that they run one after another, instead of all at once.<\/p>\nScheduling<\/h3>\n
The ability to schedule and queue\u00a0jobs make the JobScheduler\u00a0perfect for tasks that are traditionally handled by long-running services, such as:<\/p>\n
\n- Downloading a file, but only when the device is connected to an unmetered (free) network.<\/li>\n
- When charging a device, make a series of thumbnail images from a collection of larger images.<\/li>\n
- If connected to the network, call a method on a web service using an exponential backoff algorithm between unsuccessful web service calls.<\/li>\n<\/ul>\n
Classes<\/h3>\n
There are three important classes\u00a0in\u00a0the JobScheduler API:<\/p>\n
\n- JobScheduler<\/strong>: A system service that will run jobs scheduled by apps.<\/li>\n
- JobService<\/strong>: A class extended by applications and contains the code that runs as part of a job. The code for each job is contained in a class that extends the JobService class and requests the\u00a0
android.permission.BIND_JOB_SERVICE<\/code> permission.<\/li>\n- JobInfo<\/strong>: Holds information about the job that the JobScheduler needs in order to run a JobService. The JobInfo will tell the JobScheduler which JobService type to use and which conditions must be met before the job can run. It also contains any parameters that the app must pass to the JobService. A JobInfo object is not directly instantiated, instead it is created by using a JobInfo.Builder<\/strong>.<\/li>\n<\/ul>\n
Methods<\/h3>\n
A JobService sub-class must override two methods:<\/p>\n
\n- OnStartJob<\/strong>: A system invokes when the job starts and runs on the main thread of the app. \nIf the work is a small, easy task (less than 16 milliseconds), it will run on the main thread. Lengthy tasks such as disk access or network calls must run asynchronously.\u00a0
OnStartJob<\/code> should return \"true\"<\/code> if it is running work on another thread, while \"false\"<\/code> should be returned if the all the work was performed within\u00a0OnStartJob<\/code> itself.<\/li>\n- \u00a0OnStopJob<\/strong>: Called when the system has to prematurely terminate the job and provide the JobService a chance to perform any necessary cleanup. If the job should be rescheduled, it will return
\"true\"<\/code>.<\/li>\n<\/ul>\nApplying JobScheduler<\/h2>\n
The following code shows a sample JobService type:<\/p>\n
[Service(Name = \"JobScheduleSample.FibonacciJob\", Permission = \"android.permission.BIND_JOB_SERVICE\")]\npublic class FibonacciJob : JobService\n{\n public override bool OnStartJob(JobParameters jobParams)\n {\n \/\/ Called by the operating system when starting the service.\n \/\/ Start up a thread, do work on the thread.\n return true;\n }\n\n public override bool OnStopJob(JobParameters jobParams)\n {\n \/\/ Called by Android when it has to terminate a running service.\n return false; \/\/ Don't reschedule the job.\n }\n}\n<\/pre>\nCreate a JobInfo Object<\/h3>\n
In order to schedule a job, it’s necessary for an app to use a JobInfo.JobBuilder to create a JobInfo object. The JobInfo.JobBuilder has a fluent interface and is used to collect meta-data, such as the type of JobService to instantiate and any conditions that should be met before the job is run. This snippet shows how to create a JobInfo class to run the FibonacciJob (from the example above), but only when the device is connected to an “unmetered” (free) network. The job should run between one and five seconds from being scheduled:<\/p>\n
Java.Lang.Class javaClass = Java.Lang.Class.FromType(typeof(FibonacciJob);\nComponentName component = new ComponentName(context, javaClass);\n\nJobInfo.Builder builder = new JobInfo.Builder(context, component)\n .SetMinimumLatency(1000) \/\/ Wait at least 1 second\n .SetOverrideDeadline(5000) \/\/ But no longer than 5 seconds\n .SetRequiredNetworkType(NetworkType.Unmetered);\nJobInfo jobInfo = builder.Build();\n<\/pre>\nIn the previous example, the context<\/code> is any Android Context, such as an Activity. The parameter is a unique integer that identifies the job service to the JobScheduler.<\/p>\nThe following C# extension method should help with creating a ComponentName for a given JobService subclass:<\/p>\n
public static ComponentName GetComponentNameForJob(this Context context) where T : JobService, new()\n{\n Class javaClass = Class.FromType(typeof(T));\n return new ComponentName(context, javaClass);\n}\n<\/pre>\nSchedule a Job<\/h3>\n
Once a\u00a0JobInfo created is created, the app can schedule a job. This code snippet will get a reference to the JobScheduler service and ask it to schedule the job identified in the jobInfo<\/code>\u00a0object:<\/p>\nJobScheduler jobScheduler = (JobScheduler)GetSystemService(JobSchedulerService);\nint result = jobScheduler.Schedule(jobInfo);\nif (result == JobScheduler.ResultSuccess)\n{\n \/\/ The job was scheduled.\n}\nelse\n{\n \/\/ Couldn't schedule the job.\n}\n<\/pre>\nJobParameters and .SetExtras<\/h3>\n
It’s also possible for the app to pass parameters\u00a0to a service by packaging them up in a Bundle and then calling the JobInfo.SetExtras<\/code> method. The Bundle is included with the JobParameters object passed to the JobService when\u00a0OnStartJob is invoked. For example, this snippet will pass a value to a job:<\/p>\n\/\/ Bundle up parameters\nvar jobParameters = new PersistableBundle();\nextras.PutLong(\"some_long_value\", 10L);\n\n\/\/ Put the Bundle with the parameters into the jobInfo.\nJobInfo.Builder builder = new JobInfo.Builder(context, component)\n .SetExtras(extras);\nJobInfo jobInfo = builder.Build();\n<\/pre>\nTo access this value, the JobService should read the .Extras property on the JobParameter object:<\/p>\n
public override bool OnStartJob(JobParameters jobParams)\n{\n long theValue = jobParams.Extras.GetLong(\"some_long_value\", -1);\n\n \/\/ Job does something with the value.\n}\n<\/pre>\nJobFinished<\/h3>\n
Finally, when a JobService has finished its\u00a0work (regardless of which thread the work is running on), it should call its own JobFinished()<\/code> method. It’s important to call this method because it tells the JobScheduler that the work is done and it’s safe to release any wake locks that were acquired for the JobService in the first place. This diagram illustrates how the JobService methods relate to each other and how they would be used:<\/p>\n![\"The](\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/44\/2019\/03\/jobscheduler-2.png\")
<\/p>\n
Wrapping Up<\/h2>\n
Now that you’ve seen the basics of the JobScheduler API,\u00a0try using it in your Xamarin.Android application to replace a task done in a background service. This is a great opportunity to enhance the experience your user has with your applications and<\/em> update to Android Oreo 8.0 all at once! You can find a simple sample on GitHub<\/a> that shows the JobScheduler API in action. The sample calculates a Fibonacci number in a job and then passes that number back to an Activity.<\/p>\n