JobIntentService

Added in 1.1.0
Deprecated in 1.6.0

abstract class JobIntentService : Service

kotlin.Any
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ androidx.core.app.JobIntentService

Helper for processing work that has been enqueued for a job/service. When running on Android O or later, the work will be dispatched as a job via JobScheduler.enqueue. When running on older versions of the platform, it will use Context.startService.

You must publish your subclass in your manifest for the system to interact with. This should be published as a android.app.job.JobService, as described for that class, since on O and later platforms it will be executed that way.

Use enqueueWork to enqueue new work to be dispatched to and handled by your service. It will be executed in onHandleWork.

You do not need to use androidx.legacy.content.WakefulBroadcastReceiver when using this class. When running on Android O, the JobScheduler will take care of wake locks for you (holding a wake lock from the time you enqueue work until the job has been dispatched and while it is running). When running on previous versions of the platform, this wake lock handling is emulated in the class here by directly calling the PowerManager; this means the application must request the WAKE_LOCK permission.

There are a few important differences in behavior when running on Android O or later as a Job vs. pre-O:

  • When running as a pre-O service, the act of enqueueing work will generally start the service immediately, regardless of whether the device is dozing or in other conditions. When running as a Job, it will be subject to standard JobScheduler policies for a Job with a setOverrideDeadline of 0: the job will not run while the device is dozing, it may get delayed more than a service if the device is under strong memory pressure with lots of demand to run jobs.

  • When running as a pre-O service, the normal service execution semantics apply: the service can run indefinitely, though the longer it runs the more likely the system will be to outright kill its process, and under memory pressure one should expect the process to be killed even of recently started services. When running as a Job, the typical android.app.job.JobService execution time limit will apply, after which the job will be stopped (cleanly, not by killing the process) and rescheduled to continue its execution later. Job are generally not killed when the system is under memory pressure, since the number of concurrent jobs is adjusted based on the memory state of the device.

Here is an example implementation of this class:

import android.content.Context;
import android.content.Intent;
import android.os.Handler;
import android.os.SystemClock;
import android.util.Log;
import android.widget.Toast;

import androidx.annotation.NonNull;
import androidx.core.app.JobIntentService;

/**
 * Example implementation of a JobIntentService.
 */
public class SimpleJobIntentService extends JobIntentService {
    /**
     * Unique job ID for this service.
     */
    static final int JOB_ID = 1000;

    /**
     * Convenience method for enqueuing work in to this service.
     */
    static void enqueueWork(Context context, Intent work) {
        enqueueWork(context, SimpleJobIntentService.class, JOB_ID, work);
    }

    @Override
    protected void onHandleWork(@NonNull Intent intent) {
        // We have received work to do.  The system or framework is already
        // holding a wake lock for us at this point, so we can just go.
        Log.i("SimpleJobIntentService", "Executing work: " + intent);
        String label = intent.getStringExtra("label");
        if (label == null) {
            label = intent.toString();
        }
        toast("Executing: " + label);
        for (int i = 0; i < 5; i++) {
            Log.i("SimpleJobIntentService", "Running service " + (i + 1)
                    + "/5 @ " + SystemClock.elapsedRealtime());
            try {
                Thread.sleep(1000);
            } catch (InterruptedException e) {
            }
        }
        Log.i("SimpleJobIntentService", "Completed service @ " + SystemClock.elapsedRealtime());
    }

    @Override
    public void onDestroy() {
        super.onDestroy();
        toast("All work complete");
    }

    @SuppressWarnings("deprecation")
    final Handler mHandler = new Handler();

    // Helper for showing tests
    void toast(final CharSequence text) {
        mHandler.post(new Runnable() {
            @Override public void run() {
                Toast.makeText(SimpleJobIntentService.this, text, Toast.LENGTH_SHORT).show();
            }
        });
    }
}

Summary

Public constructors

Default empty constructor.

Public functions
java-static Unit
enqueueWork(context: Context, cls: Class<Any!>, jobId: Int, work: Intent)

Call this to enqueue work for your subclass of JobIntentService.
java-static Unit
enqueueWork(
    context: Context,
    component: ComponentName,
    jobId: Int,
    work: Intent
)

Like enqueueWork, but supplies a ComponentName for the service to interact with instead of its class.
Boolean

Returns true if onStopCurrentWork has been called.
IBinder!
onBind(intent: Intent)

Returns the IBinder for the android.app.job.JobServiceEngine when running as a JobService on O and later platforms.
Unit
Unit
Int
onStartCommand(intent: Intent?, flags: Int, startId: Int)

Processes start commands when running as a pre-O service, enqueueing them to be later dispatched in onHandleWork.
Boolean

This will be called if the JobScheduler has decided to stop this job.
Unit
setInterruptIfStopped(interruptIfStopped: Boolean)

Control whether code executing in onHandleWork will be interrupted if the job is stopped.

Protected functions
abstract Unit

Called serially for each work dispatched to and processed by the service.

Inherited Constants
From android.content.ComponentCallbacks2
const Int
const Int
const Int
const Int
const Int
const Int
const Int
From android.content.Context
const String!
ACCESSIBILITY_SERVICE = "accessibility"
const String!
ACCOUNT_SERVICE = "account"
const String!
ACTIVITY_SERVICE = "activity"
const String!
ALARM_SERVICE = "alarm"
const String!
APPWIDGET_SERVICE = "appwidget"
const String!
APP_OPS_SERVICE = "appops"
const String!
APP_SEARCH_SERVICE = "app_search"
const String!
AUDIO_SERVICE = "audio"
const String!
BATTERY_SERVICE = "batterymanager"
const Int
const Int
const Int
const Int
const Int
const Int
const Int
BIND_EXTERNAL_SERVICE = -2147483648
const Long
BIND_EXTERNAL_SERVICE_LONG = 4611686018427387904
const Int
const Int
const Int
const Int
const Int
const Int
const String!
BIOMETRIC_SERVICE = "biometric"
const String!
BLOB_STORE_SERVICE = "blob_store"
const String!
BLUETOOTH_SERVICE = "bluetooth"
const String!
BUGREPORT_SERVICE = "bugreport"
const String!
CAMERA_SERVICE = "camera"
const String!
CAPTIONING_SERVICE = "captioning"
const String!
CARRIER_CONFIG_SERVICE = "carrier_config"
const String!
CLIPBOARD_SERVICE = "clipboard"
const String!
COMPANION_DEVICE_SERVICE = "companiondevice"
const String!
CONNECTIVITY_DIAGNOSTICS_SERVICE = "connectivity_diagnostics"
const String!
CONNECTIVITY_SERVICE = "connectivity"
const String!
CONSUMER_IR_SERVICE = "consumer_ir"
const Int
const Int
const Int
const String!
CREDENTIAL_SERVICE = "credential"
const String!
CROSS_PROFILE_APPS_SERVICE = "crossprofileapps"
const Int
const Int
const String!
DEVICE_LOCK_SERVICE = "device_lock"
const String!
DEVICE_POLICY_SERVICE = "device_policy"
const String!
DISPLAY_HASH_SERVICE = "display_hash"
const String!
DISPLAY_SERVICE = "display"
const String!
DOMAIN_VERIFICATION_SERVICE = "domain_verification"
const String!
DOWNLOAD_SERVICE = "download"
const String!
DROPBOX_SERVICE = "dropbox"
const String!
EUICC_SERVICE = "euicc"
const String!
FILE_INTEGRITY_SERVICE = "file_integrity"
const String!
FINGERPRINT_SERVICE = "fingerprint"
const String!
GAME_SERVICE = "game"
const String!
GRAMMATICAL_INFLECTION_SERVICE = "grammatical_inflection"
const String!
HARDWARE_PROPERTIES_SERVICE = "hardware_properties"
const String!
HEALTHCONNECT_SERVICE = "healthconnect"
const String!
INPUT_METHOD_SERVICE = "input_method"
const String!
INPUT_SERVICE = "input"
const String!
IPSEC_SERVICE = "ipsec"
const String!
JOB_SCHEDULER_SERVICE = "jobscheduler"
const String!
KEYGUARD_SERVICE = "keyguard"
const String!
LAUNCHER_APPS_SERVICE = "launcherapps"
const String!
LAYOUT_INFLATER_SERVICE = "layout_inflater"
const String!
LOCALE_SERVICE = "locale"
const String!
LOCATION_SERVICE = "location"
const String!
MEDIA_COMMUNICATION_SERVICE = "media_communication"
const String!
MEDIA_METRICS_SERVICE = "media_metrics"
const String!
MEDIA_PROJECTION_SERVICE = "media_projection"
const String!
MEDIA_ROUTER_SERVICE = "media_router"
const String!
MEDIA_SESSION_SERVICE = "media_session"
const String!
MIDI_SERVICE = "midi"
const Int
MODE_APPEND = 32768
const Int
const Int

This property is deprecated.
const Int
const Int
const Int

This property is deprecated.
const Int

This property is deprecated.
const String!
const String!
NFC_SERVICE = "nfc"
const String!
NOTIFICATION_SERVICE = "notification"
const String!
NSD_SERVICE = "servicediscovery"
const String!
OVERLAY_SERVICE = "overlay"
const String!
PEOPLE_SERVICE = "people"
const String!
PERFORMANCE_HINT_SERVICE = "performance_hint"
const String!
POWER_SERVICE = "power"
const String!
PRINT_SERVICE = "print"
const Int
const Int
const Int
const String!
RESTRICTIONS_SERVICE = "restrictions"
const String!
ROLE_SERVICE = "role"
const String!
SEARCH_SERVICE = "search"
const String!
SENSOR_SERVICE = "sensor"
const String!
SHORTCUT_SERVICE = "shortcut"
const String!
STATUS_BAR_SERVICE = "statusbar"
const String!
STORAGE_SERVICE = "storage"
const String!
STORAGE_STATS_SERVICE = "storagestats"
const String!
SYSTEM_HEALTH_SERVICE = "systemhealth"
const String!
TELECOM_SERVICE = "telecom"
const String!
TELEPHONY_IMS_SERVICE = "telephony_ims"
const String!
const String!
TELEPHONY_SUBSCRIPTION_SERVICE = "telephony_subscription_service"
const String!
TEXT_CLASSIFICATION_SERVICE = "textclassification"
const String!
const String!
TV_INPUT_SERVICE = "tv_input"
const String!
TV_INTERACTIVE_APP_SERVICE = "tv_interactive_app"
const String!
UI_MODE_SERVICE = "uimode"
const String!
USAGE_STATS_SERVICE = "usagestats"
const String!
USB_SERVICE = "usb"
const String!
USER_SERVICE = "user"
const String!
VIBRATOR_MANAGER_SERVICE = "vibrator_manager"
const String!
VIBRATOR_SERVICE = "vibrator"

This property is deprecated.
const String!
VIRTUAL_DEVICE_SERVICE = "virtualdevice"
const String!
VPN_MANAGEMENT_SERVICE = "vpn_management"
const String!
WALLPAPER_SERVICE = "wallpaper"
const String!
WIFI_AWARE_SERVICE = "wifiaware"
const String!
WIFI_P2P_SERVICE = "wifip2p"
const String!
const String!
WIFI_SERVICE = "wifi"
const String!
WINDOW_SERVICE = "window"
From android.app.Service
const Int
const Int
const Int
const Int
const Int
const Int
const Int
const Int
const Int

This property is deprecated.
const Int

Inherited functions
From android.content.Context
Int
ColorStateList!
Drawable!
String!
getString(resId: Int)
T!
<T> getSystemService(serviceClass: Class<T!>!)
CharSequence!
getText(resId: Int)
TypedArray!
Unit
Unit
sendBroadcastWithMultiplePermissions(
    intent: Intent!,
    receiverPermissions: Array<String!>!
)
From android.content.ContextWrapper
Boolean
bindIsolatedService(
    service: Intent!,
    flags: Int,
    instanceName: String!,
    executor: Executor!,
    conn: ServiceConnection!
)
Boolean
bindService(service: Intent!, conn: ServiceConnection!, flags: Int)
Boolean
bindServiceAsUser(
    service: Intent!,
    conn: ServiceConnection!,
    flags: Int,
    user: UserHandle!
)
Int
Int
IntArray<Int>!
checkCallingOrSelfUriPermissions(
    uris: (Mutable)List<Uri!>!,
    modeFlags: Int
)
Int
Int
checkCallingUriPermission(uri: Uri!, modeFlags: Int)
IntArray<Int>!
checkCallingUriPermissions(uris: (Mutable)List<Uri!>!, modeFlags: Int)
Int
checkPermission(permission: String!, pid: Int, uid: Int)
Int
Int
checkUriPermission(uri: Uri!, pid: Int, uid: Int, modeFlags: Int)
IntArray<Int>!
checkUriPermissions(
    uris: (Mutable)List<Uri!>!,
    pid: Int,
    uid: Int,
    modeFlags: Int
)
Unit

This function is deprecated.
Context!
createAttributionContext(attributionTag: String!)
Context!
createConfigurationContext(overrideConfiguration: Configuration!)
Context!
createContext(contextParams: ContextParams!)
Context!
Context!
Context!
Context!
Context!
createPackageContext(packageName: String!, flags: Int)
Context!
createWindowContext(type: Int, options: Bundle!)
Array<String!>!
Boolean
Boolean
Boolean
Unit
enforceCallingOrSelfPermission(permission: String!, message: String!)
Unit
enforceCallingOrSelfUriPermission(
    uri: Uri!,
    modeFlags: Int,
    message: String!
)
Unit
enforceCallingPermission(permission: String!, message: String!)
Unit
enforceCallingUriPermission(uri: Uri!, modeFlags: Int, message: String!)
Unit
enforcePermission(permission: String!, pid: Int, uid: Int, message: String!)
Unit
enforceUriPermission(
    uri: Uri!,
    pid: Int,
    uid: Int,
    modeFlags: Int,
    message: String!
)
Array<String!>!
Context!
ApplicationInfo!
AssetManager!
AttributionSource!
String!
Context!
File!
ClassLoader!
File!
ContentResolver!
File!
File!
Int
File!
getDir(name: String!, mode: Int)
Display!
File!
Array<File!>!
File!
Array<File!>!
Array<File!>!

This function is deprecated.
File!
File!
Executor!
Looper!
File!
File!
Array<File!>!
String!
String!
PackageManager!
String!
String!
ContextParams!
Resources!
SharedPreferences!
getSharedPreferences(name: String!, mode: Int)
Any!
String!
getSystemServiceName(serviceClass: Class<Any!>!)
Resources.Theme!
Drawable!

This function is deprecated.
Int

This function is deprecated.
Int

This function is deprecated.
Unit
grantUriPermission(toPackage: String!, uri: Uri!, modeFlags: Int)
Boolean
Boolean
Boolean
Boolean
moveDatabaseFrom(sourceContext: Context!, name: String!)
Boolean
moveSharedPreferencesFrom(sourceContext: Context!, name: String!)
FileInputStream!
FileOutputStream!
openFileOutput(name: String!, mode: Int)
SQLiteDatabase!
openOrCreateDatabase(
    name: String!,
    mode: Int,
    factory: SQLiteDatabase.CursorFactory!
)
Drawable!

This function is deprecated.
Unit
Unit
Intent!
Unit

This function is deprecated.
Unit

This function is deprecated.
Unit
Unit
revokeUriPermission(uri: Uri!, modeFlags: Int)
Unit
Unit
Unit
sendOrderedBroadcast(intent: Intent!, receiverPermission: String!)
Unit
sendOrderedBroadcastAsUser(
    intent: Intent!,
    user: UserHandle!,
    receiverPermission: String!,
    resultReceiver: BroadcastReceiver!,
    scheduler: Handler!,
    initialCode: Int,
    initialData: String!,
    initialExtras: Bundle!
)
Unit

This function is deprecated.
Unit

This function is deprecated.
Unit
sendStickyOrderedBroadcast(
    intent: Intent!,
    resultReceiver: BroadcastReceiver!,
    scheduler: Handler!,
    initialCode: Int,
    initialData: String!,
    initialExtras: Bundle!
)

This function is deprecated.
Unit
sendStickyOrderedBroadcastAsUser(
    intent: Intent!,
    user: UserHandle!,
    resultReceiver: BroadcastReceiver!,
    scheduler: Handler!,
    initialCode: Int,
    initialData: String!,
    initialExtras: Bundle!
)

This function is deprecated.
Unit
setTheme(resid: Int)
Unit
setWallpaper(bitmap: Bitmap!)

This function is deprecated.
Unit
Unit
ComponentName!
Boolean
startInstrumentation(
    className: ComponentName!,
    profileFile: String!,
    arguments: Bundle!
)
Unit
startIntentSender(
    intent: IntentSender!,
    fillInIntent: Intent!,
    flagsMask: Int,
    flagsValues: Int,
    extraFlags: Int
)
ComponentName!
startService(service: Intent!)
Boolean
Unit
Unit
Unit
Unit
Unit
updateServiceGroup(conn: ServiceConnection!, group: Int, importance: Int)
From android.app.Service
Unit
Unit
dump(fd: FileDescriptor!, writer: PrintWriter!, args: Array<String!>!)
Application!
Int
Unit
Unit
Unit
onRebind(intent: Intent!)
Unit
onStart(intent: Intent!, startId: Int)

This function is deprecated.
Unit
onTaskRemoved(rootIntent: Intent!)
Unit
onTimeout(startId: Int)
Unit
onTrimMemory(level: Int)
Boolean
onUnbind(intent: Intent!)
Unit
startForeground(id: Int, notification: Notification!)
Unit
stopForeground(removeNotification: Boolean)

This function is deprecated.
Unit
Boolean
stopSelfResult(startId: Int)

Public constructors

JobIntentService

Added in 1.1.0
Deprecated in 1.6.0
JobIntentService()

Default empty constructor.

Public functions

enqueueWork

Added in 1.2.0
Deprecated in 1.6.0
java-static fun enqueueWork(context: Context, cls: Class<Any!>, jobId: Int, work: Intent): Unit

Call this to enqueue work for your subclass of JobIntentService. This will either directly start the service (when running on pre-O platforms) or enqueue work for it as a job (when running on O and later). In either case, a wake lock will be held for you to ensure you continue running. The work you enqueue will ultimately appear at onHandleWork.

Parameters
context: Context

Context this is being called from.
cls: Class<Any!>

The concrete class the work should be dispatched to (this is the class that is published in your manifest).
jobId: Int

A unique job ID for scheduling; must be the same value for all work enqueued for the same class.
work: Intent

The Intent of work to enqueue.

enqueueWork

Added in 1.1.0
Deprecated in 1.6.0
java-static fun enqueueWork(
    context: Context,
    component: ComponentName,
    jobId: Int,
    work: Intent
): Unit

Like enqueueWork, but supplies a ComponentName for the service to interact with instead of its class.

Parameters
context: Context

Context this is being called from.
component: ComponentName

The published ComponentName of the class this work should be dispatched to.
jobId: Int

A unique job ID for scheduling; must be the same value for all work enqueued for the same class.
work: Intent

The Intent of work to enqueue.

isStopped

Added in 1.1.0
Deprecated in 1.6.0
fun isStopped(): Boolean

Returns true if onStopCurrentWork has been called. You can use this, while executing your work, to see if it should be stopped.

onBind

Added in 1.1.0
Deprecated in 1.6.0
fun onBind(intent: Intent): IBinder!

Returns the IBinder for the android.app.job.JobServiceEngine when running as a JobService on O and later platforms.

onCreate

fun onCreate(): Unit

onDestroy

fun onDestroy(): Unit

onStartCommand

fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int

Processes start commands when running as a pre-O service, enqueueing them to be later dispatched in onHandleWork.

onStopCurrentWork

Added in 1.1.0
Deprecated in 1.6.0
fun onStopCurrentWork(): Boolean

This will be called if the JobScheduler has decided to stop this job. The job for this service does not have any constraints specified, so this will only generally happen if the service exceeds the job's maximum execution time.

Returns
Boolean

True to indicate to the JobManager whether you'd like to reschedule this work, false to drop this and all following work. Regardless of the value returned, your service must stop executing or the system will ultimately kill it. The default implementation returns true, and that is most likely what you want to return as well (so no work gets lost).

setInterruptIfStopped

Added in 1.1.0
Deprecated in 1.6.0
fun setInterruptIfStopped(interruptIfStopped: Boolean): Unit

Control whether code executing in onHandleWork will be interrupted if the job is stopped. By default this is false. If called and set to true, any time onStopCurrentWork is called, the class will first call AsyncTask.cancel(true) to interrupt the running task.

Parameters
interruptIfStopped: Boolean

Set to true to allow the system to interrupt actively running work.

Protected functions

onHandleWork

Added in 1.1.0
Deprecated in 1.6.0
protected abstract fun onHandleWork(intent: Intent): Unit

Called serially for each work dispatched to and processed by the service. This method is called on a background thread, so you can do long blocking operations here. Upon returning, that work will be considered complete and either the next pending work dispatched here or the overall service destroyed now that it has nothing else to do.

Be aware that when running as a job, you are limited by the maximum job execution time and any single or total sequential items of work that exceeds that limit will cause the service to be stopped while in progress and later restarted with the last unfinished work. (There is currently no limit on execution duration when running as a pre-O plain Service.)

Parameters
intent: Intent

The intent describing the work to now be processed.