com.birbit.android.jobqueue

Class JobManager

java.lang.Object

com.birbit.android.jobqueue.JobManager

public class JobManager
extends java.lang.Object

Field Summary

Fields

Modifier and Type	Field and Description
static long	MIN_DELAY_TO_USE_SCHEDULER_IN_MS The min delay in MS which will trigger usage of JobScheduler.
static long	NETWORK_CHECK_INTERVAL
static long	NOT_DELAYED_JOB_DELAY
static long	NOT_RUNNING_SESSION_ID
static long	NS_PER_MS

Constructor Summary

Constructors

Constructor and Description
JobManager(Configuration configuration) Creates a JobManager with the given configuration

Method Summary

Modifier and Type	Method and Description
void	addCallback(JobManagerCallback callback) Adds a JobManagerCallback to observe this JobManager.
void	addJob(Job job) Adds the Job to the JobManager and waits until the add is handled.
void	addJobInBackground(Job job) Adds a Job to the JobManager.
void	addJobInBackground(Job job, AsyncAddCallback callback) Adds a Job in a background thread and calls the provided callback once the Job is added to the JobManager.
CancelResult	cancelJobs(TagConstraint constraint, java.lang.String... tags) Cancels jobs that match the given criteria.
void	cancelJobsInBackground(CancelResult.AsyncCancelCallback cancelCallback, TagConstraint constraint, java.lang.String... tags) Cancels the Jobs that match the given criteria.
void	clear() Clears all waiting Jobs in the JobManager.
int	count() Returns the number of jobs in the JobManager.
int	countReadyJobs() Returns the number of jobs that are ready to be executed but waiting in the queue.
void	destroy() Destroys the JobManager.
int	getActiveConsumerCount() Returns the number of consumer threads that are currently running Jobs.
java.lang.Thread	getJobManagerExecutionThread() Returns the main thread of the JobManager.
JobStatus	getJobStatus(java.lang.String id) Returns the current status of a given job
Scheduler	getScheduler() The scheduler that was given to this JobManager when it was initialized.
boolean	removeCallback(JobManagerCallback callback) Removes the JobManagerCallback from the callbacks list.
void	start() Starts the JobManager if it is not already running.
void	stop() Stops the JobManager.
void	stopAndWaitUntilConsumersAreFinished() Stops the JobManager and waits until all currently running Jobs are complete (or failed).
void	waitUntilConsumersAreFinished() Waits until all consumers are destroyed.

Methods inherited from class java.lang.Object

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

Field Detail

NS_PER_MS

public static final long NS_PER_MS

See Also:

Constant Field Values

NOT_RUNNING_SESSION_ID

public static final long NOT_RUNNING_SESSION_ID

See Also:

Constant Field Values

NOT_DELAYED_JOB_DELAY

public static final long NOT_DELAYED_JOB_DELAY

See Also:

Constant Field Values

NETWORK_CHECK_INTERVAL

public static final long NETWORK_CHECK_INTERVAL

MIN_DELAY_TO_USE_SCHEDULER_IN_MS

public static final long MIN_DELAY_TO_USE_SCHEDULER_IN_MS

The min delay in MS which will trigger usage of JobScheduler. If a job is added with a delay in less than this value, JobManager will not use the scheduler to wake up the application.

See Also:

Constant Field Values

Constructor Detail

JobManager

public JobManager(Configuration configuration)

Creates a JobManager with the given configuration

Parameters:

configuration - The configuration to be used for the JobManager

See Also:

Configuration.Builder

Method Detail

getJobManagerExecutionThread

public java.lang.Thread getJobManagerExecutionThread()

Returns the main thread of the JobManager.

This is the thread where the Jobs' onAdded methods are run.

Returns:

The thread used by the JobManager for its own logic.

getScheduler

public Scheduler getScheduler()

The scheduler that was given to this JobManager when it was initialized.

The scheduler is used by the JobService to communicate with the JobManager.

Returns:

The scheduler that was given to this JobManager or null if it does not exist

start

public void start()

Starts the JobManager if it is not already running.

See Also:

stop()

stop

public void stop()

Stops the JobManager. Currently running Jobs will continue to run but no new Jobs will be run until restarted.

See Also:

start()

getActiveConsumerCount

public int getActiveConsumerCount()

Returns the number of consumer threads that are currently running Jobs. This number includes consumer threads that are currently idle.

You cannot call this method on the main thread because it may potentially block it for a long time.

Returns:

The number of consumer threads

destroy

public void destroy()

Destroys the JobManager. You cannot make any calls to this JobManager after this call. Useful to be called after your tests.

See Also:

stopAndWaitUntilConsumersAreFinished()

stopAndWaitUntilConsumersAreFinished

public void stopAndWaitUntilConsumersAreFinished()

Stops the JobManager and waits until all currently running Jobs are complete (or failed). Useful to be called in your tests.

You cannot call this method on the main thread because it may potentially block it for a long time.

See Also:

destroy()

waitUntilConsumersAreFinished

public void waitUntilConsumersAreFinished()

Waits until all consumers are destroyed. If min consumer count is NOT 0, this method will never return.

You cannot call this method on the main thread because it may potentially block it for a long time.

addJobInBackground

public void addJobInBackground(Job job)

Adds a Job to the JobManager. This method instantly returns and does not wait until the Job is added. You should always prefer this method over addJob(Job).

Parameters:

job - The Job to be added

See Also:

addJobInBackground(Job, AsyncAddCallback), addJob(Job)

cancelJobsInBackground

public void cancelJobsInBackground(CancelResult.AsyncCancelCallback cancelCallback,
                                   TagConstraint constraint,
                                   java.lang.String... tags)

Cancels the Jobs that match the given criteria. If a Job that matches the criteria is currently running, JobManager waits until it finishes its Job.onRun() method before calling the callback.

Parameters:

cancelCallback - The callback to call once cancel is handled

constraint - The constraint to be used to match tags

tags - The list of tags

addCallback

public void addCallback(JobManagerCallback callback)

Adds a JobManagerCallback to observe this JobManager.

Parameters:

callback - The callback to be added

removeCallback

public boolean removeCallback(JobManagerCallback callback)

Removes the JobManagerCallback from the callbacks list. This method is safe to be called inside any method of the JobManagerCallback.

Parameters:

callback - The callback to be removed

Returns:

true if the callback is removed, false otherwise (if it did not exist).

addJob

public void addJob(Job job)

Adds the Job to the JobManager and waits until the add is handled.

You cannot call this method on the main thread because it may potentially block it for a long time. Even if you are not on the main thread, you should prefer using addJobInBackground(Job) or addJobInBackground(Job, AsyncAddCallback) if you don't need to block your thread until the Job is actually added.

Parameters:

job - The Job to be added

See Also:

addJobInBackground(Job), addJobInBackground(Job, AsyncAddCallback)

addJobInBackground

public void addJobInBackground(Job job,
                               AsyncAddCallback callback)

Adds a Job in a background thread and calls the provided callback once the Job is added to the JobManager.

Parameters:

job - The Job to be added

callback - The callback to be invoked once Job is saved in the JobManager's queues

cancelJobs

public CancelResult cancelJobs(TagConstraint constraint,
                               java.lang.String... tags)

Cancels jobs that match the given criteria. This method blocks until the cancellation is handled, which might be a long time if a Job that matches the given criteria is currently running. Consider using cancelJobsInBackground(CancelResult.AsyncCancelCallback, TagConstraint, String...) if possible.

You cannot call this method on the main thread because it may potentially block it for a long time.

Parameters:

constraint - The constraints to be used for tags

tags - The list of tags

Returns:

A cancel result that has the list of cancelled and failed to cancel Jobs. A job might fail to cancel if it already started before cancel request is handled.

count

public int count()

Returns the number of jobs in the JobManager. This number does not include jobs that are currently running.

You cannot call this method on the main thread because it may potentially block it for a long time.

Returns:

The number of jobs that are waiting to be run

countReadyJobs

public int countReadyJobs()

Returns the number of jobs that are ready to be executed but waiting in the queue.

You cannot call this method on the main thread because it may potentially block it for a long time.

Returns:

The number of jobs that are ready to be executed but waiting in the queue.

getJobStatus

public JobStatus getJobStatus(java.lang.String id)

Returns the current status of a given job

You cannot call this method on the main thread because it may potentially block it for a long time.

Parameters:

id - The id of the job (Job.getId())

Returns:

The current status of the Job

clear

public void clear()

Clears all waiting Jobs in the JobManager. Note that this won't touch any job that is currently running.

You cannot call this method on the main thread because it may potentially block it for a long time.