JobParameters
public
class
JobParameters
extends Object
implements
Parcelable
java.lang.Object | |
↳ | android.app.job.JobParameters |
Contains the parameters used to configure/identify your job. You do not create this object yourself, instead it is handed in to your application by the System.
Summary
Constants | |
---|---|
int |
STOP_REASON_APP_STANDBY
The current standby bucket requires that the job stop now. |
int |
STOP_REASON_BACKGROUND_RESTRICTION
The app is restricted from running in the background. |
int |
STOP_REASON_CANCELLED_BY_APP
The job was cancelled directly by the app, either by calling
|
int |
STOP_REASON_CONSTRAINT_BATTERY_NOT_LOW
The requested battery-not-low constraint is no longer satisfied. |
int |
STOP_REASON_CONSTRAINT_CHARGING
The requested charging constraint is no longer satisfied. |
int |
STOP_REASON_CONSTRAINT_CONNECTIVITY
The requested connectivity constraint is no longer satisfied. |
int |
STOP_REASON_CONSTRAINT_DEVICE_IDLE
The requested idle constraint is no longer satisfied. |
int |
STOP_REASON_CONSTRAINT_STORAGE_NOT_LOW
The requested storage-not-low constraint is no longer satisfied. |
int |
STOP_REASON_DEVICE_STATE
The device state (eg. |
int |
STOP_REASON_ESTIMATED_APP_LAUNCH_TIME_CHANGED
The system's estimate of when the app will be launched changed significantly enough to decide this job shouldn't be running right now. |
int |
STOP_REASON_PREEMPT
The job was stopped to run a higher priority job of the app. |
int |
STOP_REASON_QUOTA
The app has consumed all of its current quota. |
int |
STOP_REASON_SYSTEM_PROCESSING
The system is doing some processing that requires stopping this job. |
int |
STOP_REASON_TIMEOUT
The job used up its maximum execution time and timed out. |
int |
STOP_REASON_UNDEFINED
There is no reason the job is stopped. |
int |
STOP_REASON_USER
The user stopped the job. |
Inherited constants |
---|
Fields | |
---|---|
public
static
final
Creator<JobParameters> |
CREATOR
|
Public methods | |
---|---|
void
|
completeWork(JobWorkItem work)
Report the completion of executing a |
JobWorkItem
|
dequeueWork()
Dequeue the next pending |
int
|
describeContents()
Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. |
ClipData
|
getClipData()
|
int
|
getClipGrantFlags()
|
PersistableBundle
|
getExtras()
|
int
|
getJobId()
|
String
|
getJobNamespace()
Get the namespace this job was placed in. |
Network
|
getNetwork()
Return the network that should be used to perform any network requests for this job. |
int
|
getStopReason()
|
Bundle
|
getTransientExtras()
|
String[]
|
getTriggeredContentAuthorities()
For jobs with |
Uri[]
|
getTriggeredContentUris()
For jobs with |
boolean
|
isExpeditedJob()
|
boolean
|
isOverrideDeadlineExpired()
For jobs with |
boolean
|
isUserInitiatedJob()
|
void
|
writeToParcel(Parcel dest, int flags)
Flatten this object in to a Parcel. |
Inherited methods | |
---|---|
Constants
STOP_REASON_APP_STANDBY
public static final int STOP_REASON_APP_STANDBY
The current standby bucket requires that the job stop now.
Constant Value: 12 (0x0000000c)
STOP_REASON_BACKGROUND_RESTRICTION
public static final int STOP_REASON_BACKGROUND_RESTRICTION
The app is restricted from running in the background.
Constant Value: 11 (0x0000000b)
STOP_REASON_CANCELLED_BY_APP
public static final int STOP_REASON_CANCELLED_BY_APP
The job was cancelled directly by the app, either by calling
JobScheduler#cancel(int)
, JobScheduler#cancelAll()
, or by scheduling a
new job with the same job ID.
Constant Value: 1 (0x00000001)
STOP_REASON_CONSTRAINT_BATTERY_NOT_LOW
public static final int STOP_REASON_CONSTRAINT_BATTERY_NOT_LOW
The requested battery-not-low constraint is no longer satisfied.
Constant Value: 5 (0x00000005)
STOP_REASON_CONSTRAINT_CHARGING
public static final int STOP_REASON_CONSTRAINT_CHARGING
The requested charging constraint is no longer satisfied.
Constant Value: 6 (0x00000006)
STOP_REASON_CONSTRAINT_CONNECTIVITY
public static final int STOP_REASON_CONSTRAINT_CONNECTIVITY
The requested connectivity constraint is no longer satisfied.
See also:
Constant Value: 7 (0x00000007)
STOP_REASON_CONSTRAINT_DEVICE_IDLE
public static final int STOP_REASON_CONSTRAINT_DEVICE_IDLE
The requested idle constraint is no longer satisfied.
Constant Value: 8 (0x00000008)
STOP_REASON_CONSTRAINT_STORAGE_NOT_LOW
public static final int STOP_REASON_CONSTRAINT_STORAGE_NOT_LOW
The requested storage-not-low constraint is no longer satisfied.
Constant Value: 9 (0x00000009)
STOP_REASON_DEVICE_STATE
public static final int STOP_REASON_DEVICE_STATE
The device state (eg. Doze, battery saver, memory usage, etc) requires JobScheduler stop this job.
Constant Value: 4 (0x00000004)
STOP_REASON_ESTIMATED_APP_LAUNCH_TIME_CHANGED
public static final int STOP_REASON_ESTIMATED_APP_LAUNCH_TIME_CHANGED
The system's estimate of when the app will be launched changed significantly enough to decide this job shouldn't be running right now. This will mostly apply to prefetch jobs.
Constant Value: 15 (0x0000000f)
STOP_REASON_PREEMPT
public static final int STOP_REASON_PREEMPT
The job was stopped to run a higher priority job of the app.
Constant Value: 2 (0x00000002)
STOP_REASON_QUOTA
public static final int STOP_REASON_QUOTA
The app has consumed all of its current quota. Each app is assigned a quota of how much it can run jobs within a certain time frame. The quota is informed, in part, by app standby buckets. Once an app has used up all of its quota, it won't be able to start jobs until quota is replenished, is changed, or is temporarily not applied.
See also:
Constant Value: 10 (0x0000000a)
STOP_REASON_SYSTEM_PROCESSING
public static final int STOP_REASON_SYSTEM_PROCESSING
The system is doing some processing that requires stopping this job.
Constant Value: 14 (0x0000000e)
STOP_REASON_TIMEOUT
public static final int STOP_REASON_TIMEOUT
The job used up its maximum execution time and timed out. Each individual job has a maximum
execution time limit, regardless of how much total quota the app has. See the note on
JobScheduler
and JobInfo
for the execution time limits.
Constant Value: 3 (0x00000003)
STOP_REASON_UNDEFINED
public static final int STOP_REASON_UNDEFINED
There is no reason the job is stopped. This is the value returned from the JobParameters
object passed to JobService#onStartJob(JobParameters)
.
Constant Value: 0 (0x00000000)
STOP_REASON_USER
public static final int STOP_REASON_USER
The user stopped the job. This can happen either through force-stop, adb shell commands, uninstalling, or some other UI.
Constant Value: 13 (0x0000000d)
Fields
Public methods
completeWork
public void completeWork (JobWorkItem work)
Report the completion of executing a JobWorkItem
previously returned by
dequeueWork()
. This tells the system you are done with the
work associated with that item, so it will not be returned again. Note that if this
is the last work in the queue, completing it here will not finish the overall
job -- for that to happen, you still need to call dequeueWork()
again.
If you are enqueueing work into a job, you must call this method for each piece
of work you process. Do not call
JobService#jobFinished(JobParameters, boolean)
or else you can lose work in your queue.
Parameters | |
---|---|
work |
JobWorkItem : The work you have completed processing, as previously returned by
dequeueWork()
This value cannot be null . |
dequeueWork
public JobWorkItem dequeueWork ()
Dequeue the next pending JobWorkItem
from these JobParameters associated with their
currently running job. Calling this method when there is no more work available and all
previously dequeued work has been completed will result in the system taking care of
stopping the job for you --
you should not call JobService#jobFinished(JobParameters, boolean)
yourself
(otherwise you risk losing an upcoming JobWorkItem that is being enqueued at the same time).
Once you are done with the JobWorkItem
returned by this method, you must call
completeWork(android.app.job.JobWorkItem)
with it to inform the system that you are done
executing the work. The job will not be finished until all dequeued work has been
completed. You do not, however, have to complete each returned work item before deqeueing
the next one -- you can use dequeueWork()
multiple times before completing
previous work if you want to process work in parallel, and you can complete the work
in whatever order you want.
If the job runs to the end of its available time period before all work has been
completed, it will stop as normal. You should return true from
JobService#onStopJob(JobParameters)
in order to have the job rescheduled, and by
doing so any pending as well as remaining uncompleted work will be re-queued
for the next time the job runs.
This example shows how to construct a JobService that will serially dequeue and process work that is available for it:
public class JobWorkService extends JobService { private NotificationManager mNM; private CommandProcessor mCurProcessor; /** * This is a task to dequeue and process work in the background. */ final class CommandProcessor extends AsyncTask<Void, Void, Void> { private final JobParameters mParams; CommandProcessor(JobParameters params) { mParams = params; } @Override protected Void doInBackground(Void... params) { boolean cancelled; JobWorkItem work; /** * Iterate over available work. Once dequeueWork() returns null, the * job's work queue is empty and the job has stopped, so we can let this * async task complete. */ while (!(cancelled=isCancelled()) && (work=mParams.dequeueWork()) != null) { String txt = work.getIntent().getStringExtra("name"); Log.i("JobWorkService", "Processing work: " + work + ", msg: " + txt); showNotification(txt); // Process work here... we'll pretend by sleeping. try { Thread.sleep(5000); } catch (InterruptedException e) { } hideNotification(); // Tell system we have finished processing the work. Log.i("JobWorkService", "Done with: " + work); mParams.completeWork(work); } if (cancelled) { Log.i("JobWorkService", "CANCELLED!"); } return null; } } @Override public void onCreate() { mNM = (NotificationManager)getSystemService(NOTIFICATION_SERVICE); Toast.makeText(this, R.string.service_created, Toast.LENGTH_SHORT).show(); } @Override public void onDestroy() { hideNotification(); Toast.makeText(this, R.string.service_destroyed, Toast.LENGTH_SHORT).show(); } @Override public boolean onStartJob(JobParameters params) { // Start task to pull work out of the queue and process it. mCurProcessor = new CommandProcessor(params); mCurProcessor.executeOnExecutor(AsyncTask.THREAD_POOL_EXECUTOR); // Allow the job to continue running while we process work. return true; } @Override public boolean onStopJob(JobParameters params) { // Have the processor cancel its current work. mCurProcessor.cancel(true); // Tell the system to reschedule the job -- the only reason we would be here is // because the job needs to stop for some reason before it has completed all of // its work, so we would like it to remain to finish that work in the future. return true; } /** * Show a notification while this service is running. */ private void showNotification(String text) { // The PendingIntent to launch our activity if the user selects this notification PendingIntent contentIntent = PendingIntent.getActivity(this, 0, new Intent(this, JobWorkServiceActivity.class), 0); // Set the info for the views that show in the notification panel. Notification.Builder noteBuilder = new Notification.Builder(this) .setSmallIcon(R.drawable.stat_sample) // the status icon .setTicker(text) // the status text .setWhen(System.currentTimeMillis()) // the time stamp .setContentTitle(getText(R.string.service_start_arguments_label)) // the label .setContentText(text) // the contents of the entry .setContentIntent(contentIntent); // The intent to send when the entry is clicked // We show this for as long as our service is processing a command. noteBuilder.setOngoing(true); // Send the notification. // We use a string id because it is a unique number. We use it later to cancel. mNM.notify(R.string.job_service_created, noteBuilder.build()); } private void hideNotification() { mNM.cancel(R.string.service_created); } }
Returns | |
---|---|
JobWorkItem |
Returns a new JobWorkItem if there is one pending, otherwise null.
If null is returned, the system will also stop the job if all work has also been completed.
(This means that for correct operation, you must always call dequeueWork() after you have
completed other work, to check either for more work or allow the system to stop the job.) |
describeContents
public int describeContents ()
Describe the kinds of special objects contained in this Parcelable
instance's marshaled representation. For example, if the object will
include a file descriptor in the output of writeToParcel(android.os.Parcel, int)
,
the return value of this method must include the
CONTENTS_FILE_DESCRIPTOR
bit.
Returns | |
---|---|
int |
a bitmask indicating the set of special object types marshaled
by this Parcelable object instance.
Value is either 0 or CONTENTS_FILE_DESCRIPTOR |
getClipData
public ClipData getClipData ()
Returns | |
---|---|
ClipData |
The clip you passed in when constructing this job with
JobInfo.Builder.setClipData(ClipData, int) . Will be null
if it was not set. |
getClipGrantFlags
public int getClipGrantFlags ()
Returns | |
---|---|
int |
The clip grant flags you passed in when constructing this job with
JobInfo.Builder.setClipData(ClipData, int) . Will be 0
if it was not set. |
getExtras
public PersistableBundle getExtras ()
Returns | |
---|---|
PersistableBundle |
The extras you passed in when constructing this job with
JobInfo.Builder.setExtras(android.os.PersistableBundle) . This will
never be null. If you did not set any extras this will be an empty bundle. |
getJobId
public int getJobId ()
Returns | |
---|---|
int |
The unique id of this job, specified at creation time. |
getJobNamespace
public String getJobNamespace ()
Get the namespace this job was placed in.
Returns | |
---|---|
String |
The namespace this job was scheduled in. Will be null if there was no
explicit namespace set and this job is therefore in the default namespace. |
See also:
getNetwork
public Network getNetwork ()
Return the network that should be used to perform any network requests for this job.
Devices may have multiple active network connections simultaneously, or they may not have a default network route at all. To correctly handle all situations like this, your job should always use the network returned by this method instead of implicitly using the default network route.
Note that the system may relax the constraints you originally requested,
such as allowing a JobInfo#NETWORK_TYPE_UNMETERED
job to run over
a metered network when there is a surplus of metered data available.
Starting in Android version Build.VERSION_CODES.UPSIDE_DOWN_CAKE
,
this will return null
if the app does not hold the permissions specified in
JobInfo.Builder#setRequiredNetwork(NetworkRequest)
.
Returns | |
---|---|
Network |
the network that should be used to perform any network requests
for this job, or null if this job didn't set any required
network type or if the job executed when there was no available network to use. |
getStopReason
public int getStopReason ()
getTransientExtras
public Bundle getTransientExtras ()
Returns | |
---|---|
Bundle |
The transient extras you passed in when constructing this job with
JobInfo.Builder.setTransientExtras(android.os.Bundle) . This will
never be null. If you did not set any extras this will be an empty bundle. |
getTriggeredContentAuthorities
public String[] getTriggeredContentAuthorities ()
For jobs with JobInfo.Builder.addTriggerContentUri(TriggerContentUri)
set, this
reports which content authorities have triggered the job. It will only be null if no
authorities have triggered it -- that is, the job executed for some other reason, such
as a deadline expiring. If this is non-null, you can use getTriggeredContentUris()
to retrieve the details of which URIs changed (as long as that has not exceeded the maximum
number it can reported).
Returns | |
---|---|
String[] |
getTriggeredContentUris
public Uri[] getTriggeredContentUris ()
For jobs with JobInfo.Builder.addTriggerContentUri(TriggerContentUri)
set, this
reports which URIs have triggered the job. This will be null if either no URIs have
triggered it (it went off due to a deadline or other reason), or the number of changed
URIs is too large to report. Whether or not the number of URIs is too large, you can
always use getTriggeredContentAuthorities()
to determine whether the job was
triggered due to any content changes and the authorities they are associated with.
Returns | |
---|---|
Uri[] |
isExpeditedJob
public boolean isExpeditedJob ()
Returns | |
---|---|
boolean |
Whether this job is running as an expedited job or not. A job is guaranteed to have
all expedited job guarantees for the duration of the job execution if this returns
true . This will return false if the job that wasn't requested to run as a
expedited job, or if it was requested to run as an expedited job but the app didn't have
any remaining expedited job quota at the time of execution. |
See also:
isOverrideDeadlineExpired
public boolean isOverrideDeadlineExpired ()
For jobs with JobInfo.Builder.setOverrideDeadline(long)
set, this
provides an easy way to tell whether the job is being executed due to the deadline
expiring. Note: If the job is running because its deadline expired, it implies that its
constraints will not be met. However,
periodic jobs
will only ever
run when their constraints are satisfied, therefore, the constraints will still be satisfied
for a periodic job even if the deadline has expired.
Returns | |
---|---|
boolean |
isUserInitiatedJob
public boolean isUserInitiatedJob ()
Returns | |
---|---|
boolean |
Whether this job is running as a user-initiated job or not. A job is guaranteed to
have all user-initiated job guarantees for the duration of the job execution if this returns
true . This will return false if the job wasn't requested to run as a
user-initiated job, or if it was requested to run as a user-initiated job but the app didn't
meet any of the requirements at the time of execution, such as having the
Manifest.permission.RUN_USER_INITIATED_JOBS permission. |
writeToParcel
public void writeToParcel (Parcel dest, int flags)
Flatten this object in to a Parcel.
Parameters | |
---|---|
dest |
Parcel : The Parcel in which the object should be written.
This value cannot be null . |
flags |
int : Additional flags about how the object should be written.
May be 0 or Parcelable.PARCELABLE_WRITE_RETURN_VALUE .
Value is either 0 or a combination of Parcelable.PARCELABLE_WRITE_RETURN_VALUE , and android.os.Parcelable.PARCELABLE_ELIDE_DUPLICATES |