com.evernote.android.job

Class JobManager

java.lang.Object

com.evernote.android.job.JobManager

public final class JobManager
extends Object

Entry point for scheduling jobs. Depending on the platform and SDK version it uses different APIs to schedule jobs. The JobScheduler is preferred, if the OS is running Lollipop or above. Otherwise it uses the AlarmManager as fallback. It's also possible to use the GcmNetworkManager, if the manager can be found in your classpath, the Google Play Services are installed and the service was added in the manifest. Take a look at the README for more help.

Before you can use the JobManager you must call create(Context) first and add a JobCreator to map tags to your desired jobs with addJobCreator(JobCreator). It's recommended to do this in the Application.onCreate() method.

In order to schedule a job you must extend the Job class. A Job is a simple class with one abstract method which is invoked on a background thread. Thus a Job doesn't need to be registered in the manifest. Create a JobRequest with the corresponding JobRequest.Builder, set your desired parameters and call schedule(JobRequest). If you want to update a pending request, call JobRequest.cancelAndEdit() on the request, update your parameters and call schedule(JobRequest) again.

Method Summary

Modifier and Type	Method and Description
void	addJobCreator(JobCreator jobCreator) Registers this instance to create jobs for a specific tag.
boolean	cancel(int jobId) Cancel either the pending JobRequest or the running Job.
int	cancelAll() Cancel all pending JobRequests and running jobs.
int	cancelAllForTag(String tag) Cancel all pending JobRequests and running jobs.
static JobManager	create(Context context) Initializes the singleton.
(package private) void	destroy()
Set<JobRequest>	getAllJobRequests()
(package private) Set<JobRequest>	getAllJobRequests(String tag, boolean includeStarted, boolean cleanUpTransient)
Set<JobRequest>	getAllJobRequestsForTag(String tag)
SparseArray<Job.Result>	getAllJobResults() Finished jobs are kept in memory until the garbage collector cleans them up.
Set<Job>	getAllJobs() Jobs are cached in memory even if they already have finished.
Set<Job>	getAllJobsForTag(String tag) Jobs are cached in memory even if they already have finished.
(package private) Context	getContext()
Job	getJob(int jobId) Jobs are cached in memory even if they already have finished.
(package private) JobCreatorHolder	getJobCreatorHolder()
(package private) JobExecutor	getJobExecutor()
(package private) JobProxy	getJobProxy(JobApi api)
JobRequest	getJobRequest(int jobId)
(package private) JobRequest	getJobRequest(int jobId, boolean includeStarted)
(package private) JobStorage	getJobStorage()
static JobManager	instance() Ensure that you've called create(Context) first.
void	removeJobCreator(JobCreator jobCreator) Remove the mapping to stop it from creating new jobs.
void	schedule(JobRequest request) Schedule a request which will be executed in the future.

Methods inherited from class java.lang.Object

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

Method Detail

create

public static JobManager create(@NonNull
                                Context context)
                         throws JobManagerCreateException

Initializes the singleton. It's necessary to call this function before using the JobManager. Calling it multiple times has not effect.

Parameters:

context - Any Context to instantiate the singleton object.

Returns:

The new or existing singleton object.

Throws:

JobManagerCreateException - When the singleton couldn't be created.

instance

public static JobManager instance()

Ensure that you've called create(Context) first. Otherwise this method throws an exception.

Returns:

The JobManager object.

schedule

public void schedule(@NonNull
                     JobRequest request)

Schedule a request which will be executed in the future. If you want to update an existing JobRequest, call JobRequest.cancelAndEdit(), update your parameters and call this method again. Calling this method with the same request multiple times without cancelling it is idempotent.

Parameters:

request - The JobRequest which will run in the future.

getJobRequest

public JobRequest getJobRequest(int jobId)

Parameters:

jobId - The unique ID of the pending JobRequest.

Returns:

The JobRequest if it's pending or null otherwise.

getJobRequest

JobRequest getJobRequest(int jobId,
                         boolean includeStarted)

getAllJobRequests

@NonNull
public Set<JobRequest> getAllJobRequests()

Returns:

A duplicate Set containing all pending JobRequests or an empty set. Never returns null. The set may be modified without direct effects to the actual backing store.

See Also:

getJobRequest(int)

getAllJobRequestsForTag

public Set<JobRequest> getAllJobRequestsForTag(@NonNull
                                               String tag)

Parameters:

tag - The tag of the pending requests.

Returns:

A duplicate Set containing all pending JobRequests associated with this tag or an empty set. Never returns null. The set may be modified without direct effects to the actual backing store.

getAllJobRequests

Set<JobRequest> getAllJobRequests(@Nullable
                                  String tag,
                                  boolean includeStarted,
                                  boolean cleanUpTransient)

getJob

public Job getJob(int jobId)

Jobs are cached in memory even if they already have finished. But finished jobs are never restored after the app has launched. Since finished jobs could cause memory leaks, they wrapped inside of a WeakReference and can be removed from memory. If you need to know the results of finished jobs or whether a job has been run, you can call getAllJobResults().

Parameters:

jobId - The unique ID of the running or finished Job.

Returns:

The Job if it's running or has been finished and is still cached. Returns null otherwise.

getAllJobs

@NonNull
public Set<Job> getAllJobs()

Jobs are cached in memory even if they already have finished. But finished jobs are never restored after the app has relaunched. Since finished jobs could cause memory leaks, they wrapped inside of a WeakReference and can be removed from memory. If you need to know the results of finished jobs or whether a job has been run, you can call getAllJobResults().

Returns:

A duplicate Set containing all running and cached finished jobs or an empty set. Never returns null. The set may be modified without direct effects to the actual backing store.

getAllJobsForTag

@NonNull
public Set<Job> getAllJobsForTag(@NonNull
                                          String tag)

Jobs are cached in memory even if they already have finished. But finished jobs are never restored after the app has relaunched. Since finished jobs could cause memory leaks, they wrapped inside of a WeakReference and can be removed from memory. If you need to know the results of finished jobs or whether a job has been run, you can call getAllJobResults().

Parameters:

tag - The tag of the running or finished jobs.

Returns:

A duplicate Set containing all running and cached finished jobs associated with this tag or an empty set. Never returns null. The set may be modified without direct effects to the actual backing store.

getAllJobResults

@NonNull
public SparseArray<Job.Result> getAllJobResults()

Finished jobs are kept in memory until the garbage collector cleans them up. This method returns the results of all finished jobs even after they have been cleaned up. However, neither finished jobs nor their results are restored after the app has been relaunched.

Returns:

The results of all finished jobs. They key is the corresponding job ID.

cancel

public boolean cancel(int jobId)

Cancel either the pending JobRequest or the running Job.

Parameters:

jobId - The unique ID of the JobRequest or running Job.

Returns:

true if a request or job were found and canceled.

cancelAll

public int cancelAll()

Cancel all pending JobRequests and running jobs.

Returns:

The count of canceled requests and running jobs.

cancelAllForTag

public int cancelAllForTag(@NonNull
                           String tag)

Cancel all pending JobRequests and running jobs.

Parameters:

tag - The tag of the pending job requests and running jobs.

Returns:

The count of canceled requests and running jobs.

addJobCreator

public void addJobCreator(JobCreator jobCreator)

Registers this instance to create jobs for a specific tag. It's possible to have multiple JobCreators with a first come first serve order.

Parameters:

jobCreator - The mapping between a specific job tag and the job class.

removeJobCreator

public void removeJobCreator(JobCreator jobCreator)

Remove the mapping to stop it from creating new jobs.

Parameters:

jobCreator - The mapping between a specific job tag and the job class.

getJobStorage

JobStorage getJobStorage()

getJobExecutor

JobExecutor getJobExecutor()

getJobCreatorHolder

JobCreatorHolder getJobCreatorHolder()

getContext

Context getContext()

destroy

void destroy()

getJobProxy

JobProxy getJobProxy(JobApi api)