Job Configuration

Jobs have a couple of properties which define their behavior on different cases.

• Priority Higher is better. Next available job consumer will get the highest priority job first. (if it is ready to run). By design, memory only jobs are higher priority than persistent jobs. If two jobs have the same priority, the jobs which is enqueued first runs first. (assuming both are ready to run)

• Network Requirement If you mark the job as requires network, Job Manager will not run the job until the device has network connection. This won't block other jobs from running if they don't require network, even if they have lower priority. Starting with V2, you can also specify the network type to be unmetered using params#requireUnmeteredNetwork. It is also possible to set a timeout for these requirements. For example, you can create a job that requires unmetered network for the first day and then fall back to any connection.

new Params(1)
  .requireUnmeteredNetworkWithTimeout(TimeUnit.DAYS.toMillis(1))
  .requireNetwork()

• Persistence Sometimes, it is very important to ensure a job runs, no matter what happens to the app. (crash etc :) ). In this case, you can mark the job as persistent and Job Manager will take care of it. If your app crashed for some reason or gets killed by the OS, next time it re-opens, Job Manager will try to re-run it. This is very helpful for any app where user creates content to ensure your application eventually syncs user's content to server.

• Grouping It is a common use case where you don't want to run certain jobs in parallel. For example, when multiple jobs edit the same object. For such cases, you can assign same groupId to these jobs and Job Manager will ensure they run sequentially (fyi different job classes may have the same id. it depends on the job instance, not the class). A great example for this is a messaging client. If user has a bunch of messages waiting to be sent to different conversations, you need to ensure that messages going to the same conversation are in order. Meanwhile, you can send messages to different conversations in parallel. It is very easy to solve with Job Manager by setting SendMessageJob's groupId to conversation id. Within the group, priority rules still apply.

• Delaying Jobs Sometimes you want to run a job after some time passes. For instance, you want to acquire GCM tokens and send it to your server when app starts but you don't want it to fight for network with your more important requests. In this case, you can enqueue related job with a delay and Job Manager will wait until it should run. When it is ready to run, other rules still apply (network requirement etc) IMPORTANT: In V1, JobManager used to reset this delay when the application restarts. In V2, this is no more the default behavior but you can still change it via Configuration#resetDelaysOnRestart.

• Retry Logic If a job throws an exception while running, Job Manager calls shouldReRunOnThrowable method to decide if the job should be re-tried or cancelled. If job reaches retry limit (by default 20), Job Manager will automatically cancel it without calling shouldReRunOnThrowable but will call onCancel method. You can override retry count per job by overriding getRetryLimit method.

• Tags When creating a Job, you can attach it a list of tags, which are just strings. These tags can be used to cancel jobs later on if they are not needed anymore.

• Single Instance Jobs It is a common requirement to have a single instance of particular jobs so that if you create multiple instances of it, only 1 will run / wait in the queue at a given time. You can achieve this via params#singleInstanceBy. When a job is added with the same single instance tag, if there is an existing job that is waiting in the queue, the new job will instantly be cancelled after its onAdded method is called. If the previous job is already running, the new job will be added and already running job will be cancelled if it fails or nothing will happen if it finishes without an error.