com.evernote.android.job

Class JobRequest.Builder

java.lang.Object

com.evernote.android.job.JobRequest.Builder

Enclosing class:

JobRequest

public static final class JobRequest.Builder
extends Object

Builder class for constructing JobRequests.

Field Summary

Fields

Modifier and Type	Field and Description
(package private) String	mTag

Constructor Summary

Constructors

Constructor and Description
Builder(String tag) Creates a new instance to build a JobRequest.

Method Summary

Modifier and Type	Method and Description
JobRequest.Builder	addExtras(PersistableBundleCompat extras) Adds optional extras.
JobRequest	build()
boolean	equals(Object o)
int	hashCode()
JobRequest.Builder	setBackoffCriteria(long backoffMs, JobRequest.BackoffPolicy backoffPolicy) Change the back-off policy for a non periodic job.
JobRequest.Builder	setExact(long exactInMs) Specify that the job should run at an exact time.
JobRequest.Builder	setExecutionWindow(long startInMs, long endInMs) Set the time window when the job will be run.
JobRequest.Builder	setExtras(PersistableBundleCompat extras) Set optional extras.
JobRequest.Builder	setPeriodic(long intervalMs) Specify that this job should recur with the provided interval, not more than once per period.
JobRequest.Builder	setPeriodic(long intervalMs, long flexMs) Specify that this job should recur with the provided interval and flex, not more than once per period.
JobRequest.Builder	setRequiredNetworkType(JobRequest.NetworkType networkType) Set some description of the kind of network type your job needs to have.
JobRequest.Builder	setRequirementsEnforced(boolean enforced) It's possible to set several requirements for a job, however, not all of them need to be considered by the underlying JobApi.
JobRequest.Builder	setRequiresBatteryNotLow(boolean requiresBatteryNotLow) Specify that to run this job, the device battery shouldn't be below a curtain threshold.
JobRequest.Builder	setRequiresCharging(boolean requiresCharging) Specify that to run this job, the device needs to be plugged in.
JobRequest.Builder	setRequiresDeviceIdle(boolean requiresDeviceIdle) Specify that to run, the job needs the device to be in idle mode.
JobRequest.Builder	setRequiresStorageNotLow(boolean requiresStorageNotLow) Specify that to run this job, the device storage shouldn't be low.
JobRequest.Builder	setTransientExtras(Bundle extras) Set optional transient extras.
JobRequest.Builder	setUpdateCurrent(boolean updateCurrent) Sets whether this request should overwrite any preexisting jobs with the same tag.
JobRequest.Builder	startNow() Specify that the job should start immediately.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

mTag

final String mTag

Constructor Detail

Builder

public Builder(@NonNull
               String tag)

Creates a new instance to build a JobRequest. Note that the tag doesn't need to be unique. Each created request has an unique ID to differentiate between jobs with the same tag.

When your job is about to start you receive a callback in your JobCreator to create a Job for this tag.

Parameters:

tag - The tag is used to identify your Job in JobCreator.create(String).

Method Detail

setExecutionWindow

public JobRequest.Builder setExecutionWindow(long startInMs,
                                             long endInMs)

Set the time window when the job will be run. Note that it's mandatory to set a time for one-off tasks, but it's not allowed to call this method together with setPeriodic(long) or setExact(long). For those types jobs it doesn't make sense to have a time window.

The window specified is treated as offset from now, e.g. the job will run between System.currentTimeMillis() + startInMs and System.currentTimeMillis() + endInMs.

The maximum value for each argument is Long.MAX_VALUE / 3 * 2 (about 53_375_995_583 days). Otherwise some APIs schedule the job immediately. No exception is thrown if an argument is greater than the maximum value, the arguments are silently being clamped.

NOTE: It's not recommended to have such big execution windows. The AlarmManager used as fallback API doesn't allow setting a start date. Although being inexact, the execution time is the arithmetic average of startInMs and endInMs. The result could be that your job never runs on pre Android 5.0 devices, if one argument is too large.

Parameters:

startInMs - Earliest point from which your task is eligible to run.

endInMs - Latest point at which your task must be run.

setExtras

public JobRequest.Builder setExtras(@Nullable
                                    PersistableBundleCompat extras)

Set optional extras. This is persisted, so only primitive types are allowed.

Parameters:

extras - Bundle containing extras which you can retrieve with Job.Params.getExtras().

addExtras

public JobRequest.Builder addExtras(@NonNull
                                    PersistableBundleCompat extras)

Adds optional extras. This is persisted, so only primitive types are allowed. This method overrides values with the same keys inside of extras, which were set before.

Parameters:

extras - Bundle containing extras which you can retrieve with Job.Params.getExtras().

setRequirementsEnforced

public JobRequest.Builder setRequirementsEnforced(boolean enforced)

It's possible to set several requirements for a job, however, not all of them need to be considered by the underlying JobApi. If the requirements are enforced, then the device state is checked before your job runs. If at least one requirement isn't met, then the job is rescheduled and not run.

It's possible to check single requirements in your job, if you keep this field set to false. The Job class provides several methods, e.g. Job.isRequirementChargingMet().

Note that it's not allowed to set requirements for exact jobs. That wouldn't make sense, because the job needs to run at a specific time no matter of the device's state.

The default value is set to false.

Parameters:

enforced - If true, then all set requirements are manually checked.

setRequiredNetworkType

public JobRequest.Builder setRequiredNetworkType(@Nullable
                                                 JobRequest.NetworkType networkType)

Set some description of the kind of network type your job needs to have. Not calling this function means the network is not necessary, as the default is JobRequest.NetworkType.ANY.

Note that if the deadline is met and the requirements aren't enforced, then your job will run and ignore this requirement.

Parameters:

networkType - The required network type.

See Also:

setRequirementsEnforced(boolean), setExecutionWindow(long, long)

setRequiresCharging

public JobRequest.Builder setRequiresCharging(boolean requiresCharging)

Specify that to run this job, the device needs to be plugged in. The default is set to false.

Note that if the deadline is met and the requirements aren't enforced, then your job will run and ignore this requirement.

Parameters:

requiresCharging - Whether or not the device needs to be plugged in.

See Also:

setRequirementsEnforced(boolean), setExecutionWindow(long, long)

setRequiresDeviceIdle

public JobRequest.Builder setRequiresDeviceIdle(boolean requiresDeviceIdle)

Specify that to run, the job needs the device to be in idle mode. This defaults to false. Idle mode is a loose definition provided by the system, which means that the device is not in use, and has not been in use for some time. As such, it is a good time to perform resource heavy jobs.

Note that if the deadline is met and the requirements aren't enforced, then your job will run and ignore this requirement.

Parameters:

requiresDeviceIdle - Whether or not the device needs be idle.

See Also:

setRequirementsEnforced(boolean), setExecutionWindow(long, long)

setRequiresBatteryNotLow

public JobRequest.Builder setRequiresBatteryNotLow(boolean requiresBatteryNotLow)

Specify that to run this job, the device battery shouldn't be below a curtain threshold. The default is set to false.

Note that if the deadline is met and the requirements aren't enforced, then your job will run and ignore this requirement.

Parameters:

requiresBatteryNotLow - Whether or not the device batter shouldn't be low.

See Also:

setRequirementsEnforced(boolean), setExecutionWindow(long, long)

setRequiresStorageNotLow

public JobRequest.Builder setRequiresStorageNotLow(boolean requiresStorageNotLow)

Specify that to run this job, the device storage shouldn't be low. The default is set to false. Note: This requirement only has an affect on Android O, but not lower versions. It's never guaranteed that enough space is available, when your job runs. This is more like a hint.

Note that if the deadline is met and the requirements aren't enforced, then your job will run and ignore this requirement.

Parameters:

requiresStorageNotLow - Whether or not the device storage shouldn't be low.

See Also:

setRequirementsEnforced(boolean), setExecutionWindow(long, long)

setExact

public JobRequest.Builder setExact(long exactInMs)

Specify that the job should run at an exact time. This type of job must only be used for situations where it is actually required that the alarm go off even while in idle. A reasonable example would be for a calendar notification that should make a sound so the user is aware of it.

Note that an exact job can't be periodic. It's also not allowed to specify any requirement, the exact timing is the most important requirement for such a job. This method overrides any specified time window.

The default value is set to false. Internally an exact job is always using the AlarmManager.

The milliseconds specified are treated as offset from now, e.g. the job will run at System.currentTimeMillis() + exactInMs.

The maximum value of the argument is Long.MAX_VALUE / 3 * 2 (about 53_375_995_583 days). No exception is thrown if the argument is greater than the maximum value, the argument is silently being clamped.

Parameters:

exactInMs - The exact offset when the job should run from when the job was scheduled.

See Also:

AlarmManager.setExact(int, long, android.app.PendingIntent), AlarmManager.setExactAndAllowWhileIdle(int, long, android.app.PendingIntent)

startNow

public JobRequest.Builder startNow()

Specify that the job should start immediately. This is similar to an exact job and has the same constraints, e.g. no other requirements like a specific network condition are allowed. This method overrides any specified time window.

The advantage if a job that starts immediately compared to implementing your own Service is that jobs run in parallel and can be rescheduled if necessary. It also respect the background execution limit introduced in Android O, meaning that if it's not allowed to start a Service, then the work is delayed.

See Also:

setExact(long)

setPeriodic

public JobRequest.Builder setPeriodic(long intervalMs)

Specify that this job should recur with the provided interval, not more than once per period. As default a job isn't periodic.

It isn't allowed to specify a time window for a periodic job. Instead you set an interval with this function. Since Job.Result.RESCHEDULE is ignored for periodic jobs, setting a back-off criteria is illegal as well.

Parameters:

intervalMs - The job should run at most once every intervalMs. The minimum value is 15min.

setPeriodic

public JobRequest.Builder setPeriodic(long intervalMs,
                                      long flexMs)

Specify that this job should recur with the provided interval and flex, not more than once per period. The flex controls how close to the end of a period the job can run. For example, specifying an interval of 60 seconds and a flex of 15 seconds will allow the scheduler to determine the best moment between the 45th and 60th second at which to execute your job.

As default a job isn't periodic. It isn't allowed to specify a time window for a periodic job. Instead you set an interval with this function. Since Job.Result.RESCHEDULE is ignored for periodic jobs, setting a back-off criteria is illegal as well.

Parameters:

intervalMs - The job should run at most once every intervalMs. The minimum value is 15min.

flexMs - How close to the end of the period the job should run. The minimum value is 5min.

See Also:

JobRequest.MIN_INTERVAL, JobRequest.MIN_FLEX

setBackoffCriteria

public JobRequest.Builder setBackoffCriteria(long backoffMs,
                                             @NonNull
                                             JobRequest.BackoffPolicy backoffPolicy)

Change the back-off policy for a non periodic job. The default value is set to 30 seconds and JobRequest.BackoffPolicy.EXPONENTIAL. The time is increasing each time a job fails and returns Job.Result.RESCHEDULE, but capped at 5 hours.

Note that it's not allowed to change the back-off criteria for a periodic job.

Parameters:

backoffMs - The initial interval to wait when the job has been rescheduled.

backoffPolicy - Is either JobRequest.BackoffPolicy.LINEAR or JobRequest.BackoffPolicy.EXPONENTIAL.

See Also:

Job.Result.RESCHEDULE, Job.onReschedule(int)

setUpdateCurrent

public JobRequest.Builder setUpdateCurrent(boolean updateCurrent)

Sets whether this request should overwrite any preexisting jobs with the same tag. If true, then this request calls JobManager.cancelAllForTag(String) with the given tag before being scheduled.

Parameters:

updateCurrent - If true this request will cancel any preexisting job with the same tag while being scheduled.

setTransientExtras

public JobRequest.Builder setTransientExtras(@Nullable
                                             Bundle extras)

Set optional transient extras. WARNING: It's not guaranteed that a transient job will run at all, e.g. rebooting the device or force closing the app will cancel the job. This is only helpful for jobs which should start soon and can be cancelled automatically.

If the passed in bundle is null or empty, then the previous extras are reset to the default and the job won't be transient.

Parameters:

extras - Bundle containing extras you want the scheduler to hold on to for you.

build

public JobRequest build()

Returns:

The JobRequest with this parameters to hand to the JobManager.

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object