com.birbit.android.jobqueue

Class Job

java.lang.Object

com.birbit.android.jobqueue.Job

All Implemented Interfaces:

java.io.Serializable

public abstract class Job
extends java.lang.Object
implements java.io.Serializable

Base class for all of your jobs.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_RETRY_LIMIT

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Job(Params params)

Method Summary

Modifier and Type	Method and Description
void	assertNotCancelled() Convenience method that checks if job is cancelled and throws a RuntimeException if it is cancelled.
android.content.Context	getApplicationContext() Convenience method to get the application context in a Job.
int	getCurrentRunCount() Before each run, JobManager sets this number.
long	getDelayInMs() used by JobManager to assign proper delay at the time job is added.
java.lang.String	getId()
int	getPriority() used by JobManager to assign proper priority at the time job is added.
protected int	getRetryLimit() By default, jobs will be retried DEFAULT_RETRY_LIMIT times.
java.lang.String	getRunGroupId() Some jobs may require being run synchronously.
java.lang.String	getSingleInstanceId() Some jobs only need a single instance to be queued to run.
java.util.Set<java.lang.String>	getTags() Returns a readonly set of tags attached to this Job.
boolean	isCancelled() Returns true if job is cancelled.
boolean	isDeadlineReached() Returns true if the job's deadline is reached.
boolean	isPersistent() Whether we should add this job to disk or non-persistent queue
abstract void	onAdded() Called when the job is added to disk and committed.
protected abstract void	onCancel(int cancelReason, java.lang.Throwable throwable) Called when a job is cancelled.
abstract void	onRun() The actual method that should to the work.
boolean	requiresNetwork() Returns whether job requires a network connection to be run or not.
boolean	requiresUnmeteredNetwork() Returns whether job requires a unmetered network connection to be run or not.
protected abstract RetryConstraint	shouldReRunOnThrowable(java.lang.Throwable throwable, int runCount, int maxRunCount) If onRun method throws an exception, this method is called.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_RETRY_LIMIT

public static final int DEFAULT_RETRY_LIMIT

See Also:

Constant Field Values

Constructor Detail

Job

protected Job(Params params)

Method Detail

getId

public final java.lang.String getId()

getPriority

public final int getPriority()

used by JobManager to assign proper priority at the time job is added.

Returns:

priority (higher = better)

getDelayInMs

public final long getDelayInMs()

used by JobManager to assign proper delay at the time job is added. This field is not persisted!

Returns:

delay in ms

getTags

public final java.util.Set<java.lang.String> getTags()

Returns a readonly set of tags attached to this Job.

Returns:

Set of Tags. If tags do not exists, returns null.

isPersistent

public final boolean isPersistent()

Whether we should add this job to disk or non-persistent queue

Returns:

True if this job should be persistent between app restarts

onAdded

public abstract void onAdded()

Called when the job is added to disk and committed. This means job will eventually run. This is a good time to update local database and dispatch events.

Changes to this class will not be preserved if your job is persistent !!!

Also, if your app crashes right after adding the job, onRun might be called without an onAdded call

Note that this method is called on JobManager's thread and will block any other action so it should be fast and not make any web requests (File IO is OK).

onRun

public abstract void onRun()
                    throws java.lang.Throwable

The actual method that should to the work. It should finish w/o any exception. If it throws any exception, shouldReRunOnThrowable(Throwable, int, int) will be called to decide either to dismiss the job or re-run it.

Throws:

java.lang.Throwable - Can throw and exception which will mark job run as failed

onCancel

protected abstract void onCancel(int cancelReason,
                                 java.lang.Throwable throwable)

Called when a job is cancelled.

Parameters:

cancelReason - It is one of:

• CancelReason.REACHED_RETRY_LIMIT
• CancelReason.CANCELLED_VIA_SHOULD_RE_RUN
• CancelReason.CANCELLED_WHILE_RUNNING
• CancelReason.SINGLE_INSTANCE_WHILE_RUNNING
• CancelReason.SINGLE_INSTANCE_ID_QUEUED

throwable - The exception that was thrown from the last execution of onRun()

shouldReRunOnThrowable

protected abstract RetryConstraint shouldReRunOnThrowable(java.lang.Throwable throwable,
                                                          int runCount,
                                                          int maxRunCount)

If onRun method throws an exception, this method is called.

If you simply want to return retry or cancel, you can use RetryConstraint.RETRY or RetryConstraint.CANCEL.

You can also use a custom RetryConstraint where you can change the Job's priority or add a delay until the next run (e.g. exponential back off).

Note that changing the Job's priority or adding a delay may alter the original run order of the job. So if the job was added to the queue with other jobs and their execution order is important (e.g. they use the same groupId), you should not change job's priority or add a delay unless you really want to change their execution order.

Parameters:

throwable - The exception that was thrown from onRun()

runCount - The number of times this job run. Starts from 1.

maxRunCount - The max number of times this job can run. Decided by getRetryLimit()

Returns:

A RetryConstraint to decide whether this Job should be tried again or not and if yes, whether we should add a delay or alter its priority. Returning null from this method is equal to returning RetryConstraint.RETRY.

getCurrentRunCount

public final int getCurrentRunCount()

Before each run, JobManager sets this number.

Might be useful for the onRun() method

Returns:

The current retry count of the Job

getRunGroupId

public final java.lang.String getRunGroupId()

Some jobs may require being run synchronously. For instance, if it is a job like sending a comment, we should never run them in parallel (unless they are being sent to different conversations). By assigning same groupId to jobs, you can ensure that that type of jobs will be run in the order they were given (if their priority is the same).

Returns:

The groupId of the job or null if it is not grouped

getSingleInstanceId

public final java.lang.String getSingleInstanceId()

Some jobs only need a single instance to be queued to run. For instance, if a user has made several changes to a resource while offline, you can save every change locally during onAdded(), but only update the resource remotely once with the latest changes.

Returns:

The single instance id of the job or null if it is not a single instance job

getRetryLimit

protected int getRetryLimit()

By default, jobs will be retried DEFAULT_RETRY_LIMIT times. If job fails this many times, onCancel will be called w/o calling shouldReRunOnThrowable(Throwable, int, int)

Returns:

The number of times the job should be re-tried before being cancelled automatically

isCancelled

public final boolean isCancelled()

Returns true if job is cancelled. Note that if the job is already running when it is cancelled, this flag is still set to true but job is NOT STOPPED (e.g. JobManager does not interrupt the thread). If you have a long job that may be cancelled, you can check this field and handle it manually.

Note that, if your job returns successfully from onRun() method, it will be considered as successfully completed, thus will be added to CancelResult.getFailedToCancel() list. If you want this job to be considered as cancelled, you should throw an exception. You can also use assertNotCancelled() method to do it.

Calling this method outside onRun() method has no meaning since onRun() will not be called if the job is cancelled before it is called.

Returns:

true if the Job is cancelled

assertNotCancelled

public void assertNotCancelled()

Convenience method that checks if job is cancelled and throws a RuntimeException if it is cancelled.

getApplicationContext

public android.content.Context getApplicationContext()

Convenience method to get the application context in a Job.

This context is set when job is added to a JobManager.

Returns:

The application context

isDeadlineReached

public boolean isDeadlineReached()

Returns true if the job's deadline is reached.

Note that this method is safe to access only when the job is running. Value is undefined if it is called outside the onRun() method.

Returns:

true if job reached its deadline, false otherwise

requiresNetwork

public final boolean requiresNetwork()

Returns whether job requires a network connection to be run or not.

Returns:

True if job requires a network to be run, false otherwise.

requiresUnmeteredNetwork

public final boolean requiresUnmeteredNetwork()

Returns whether job requires a unmetered network connection to be run or not.

Returns:

True if job requires a unmetered network to be run, false otherwise.