Performs work on the SQLite database.
Performs work on the SQLite database.
This method is called only once from the database thread, when the job is selected and executed by the queue. After job is completed, it is removed from the queue and next job is executed.
If job method throws any exception, it's recorded, logged, but otherwise it does not affect other jobs (except for side-effects of unfinished SQL work). This may be changed by overriding job's or queue's related methods.
an open connection to the database, not null
the result, or null
Throwable
on any problem
SQLiteQueue#execute
Cancels this job.
Cancels this job. Convenience method to call cancel(true)
.
#cancel(boolean)
Attempts to cancel execution of this job.
Attempts to cancel execution of this job. This attempt will fail if the job has already completed, has already been cancelled, or could not be cancelled for some other reason. If successful, and this job has not started when cancel is called, this job should never run. If the job has already started, then the mayInterruptIfRunning parameter determines whether the thread executing this task should be interrupted in an attempt to stop the task.
When an active job is being cancelled with mayInterruptIfRunning parameter,
SQLiteConnection#interrupt
method is called to cancel a potentially long-running SQL. If there's
no SQL running, it will have no effect. The running job may check #isCancelled
method and finish
prematurely. There are no other means to cancel a running job.
If the job is still pending, then #jobCancelled
and #jobFinished
callbacks are called during
the execution of this method.
true if the thread executing this task should be interrupted; otherwise, in-progress tasks are allowed to complete
false if the task could not be cancelled, typically because it has already completed normally; true otherwise
Wait if necessary for the job to complete and return the result.
Wait if necessary for the job to complete and return the result.
This is a convenience method for calling #get()
without having to catch exceptions.
the result of the job, or null if it has been cancelled or has erred
Waits if necessary for at most the given time for the job to complete, and then retrieves its result, if available.
Waits if necessary for at most the given time for the job to complete, and then retrieves its result, if available.
the maximum time to wait
the time unit of the timeout argument
the result
ExecutionException
if the job threw an exception
InterruptedException
if the current thread was interrupted while waiting
TimeoutException
if the wait timed out
java.util.concurrent.CancellationException
if the job was cancelled
Waits if necessary for the job to complete, and then retrieves its result.
Waits if necessary for the job to complete, and then retrieves its result.
Calling this method, as well as convenience method #complete
, is a way to block the current thread
and wait for the result.
the result
ExecutionException
if the job threw an exception
InterruptedException
if the current thread was interrupted while waiting
java.util.concurrent.CancellationException
if the job was cancelled
Returns the error thrown by the job.
Returns the error thrown by the job.
the error thrown by the { @link #job} method, or null.
Returns the instance of the queue that is currently running the job.
Returns the instance of the queue that is currently running the job. May return null.
the queue that is currently running this job, if available.
Returns true if this job was cancelled before it completed normally.
Returns true if this job was cancelled before it completed normally.
true if this job was cancelled before it completed
Returns true if this job completed.
Returns true if this job completed.
Completion may be due to normal termination, an exception, or cancellation -- in all of these cases, this method will return true.
true if this task completed
This method is called after job has been cancelled, either due to call to the #cancel
method,
or because queue has stopped, or for any other reason.
This method is called after job has been cancelled, either due to call to the #cancel
method,
or because queue has stopped, or for any other reason.
Throwable
on any problem
This method is called after #job
method has thrown an exception.
This method is called after #job
method has thrown an exception. The exception is passed
as a parameter.
exception thrown by the job
Throwable
on any problem, or the rethrown exception
This method is called when the job is no longer in the queue.
This method is called when the job is no longer in the queue. Overriding this method is the best way to asynchronously process the result of the job.
This method is called always, regardless
of the job execution result, and even if the job is cancelled before execution. More strictly, it is called
once between the time SQLiteQueue#execute
is called and the time when this job is no longer in the queue
nor being executed.
The result of the job is passed as a parameter.
the result of the job, or null if the job was cancelled or has thrown exception
Throwable
on any problem
This method is called when the job is about to be executed, before call to #job
method.
This method is called when the job is about to be executed, before call to #job
method.
This method may not be called at all if a job is cancelled before execution starts.
an open connection to the database, not null
Throwable
on any problem
SQLiteJob is a unit of work accepted by
SQLiteQueue
. You can implement#job
method and add the job to the queue withSQLiteQueue#execute
method.A job can optionally have a result. Type parameter
<T>
defines the type of the result, and the value of the result is returned by thejob()
method. If job finishes unsuccessfully or is cancelled, the result is always null. If you don't need the job to have a result, define it asSQLiteJob<Object>
orSQLiteJob<Void>
and return null from thejob()
method.Job implements
Future
interface and can be used along with different types of future results.Also, you can override methods
#jobStarted
,#jobFinished
,#jobCancelled
and#jobError
to implement callbacks during the job's lifecycle.SQLiteJob is a one-time object. Once the job is finished, it cannot be executed again.
Public methods of SQLiteJob are thread-safe unless specified otherwise. Protected methods are mostly called from the database thread and must be overridden carefully.
When programming a job, it's a good practice to keep transaction boundaries within single job. That is, if you BEGIN TRANSACTION in the job, make sure you COMMIT or ROLLBACK in the end. Otherwise, your transaction will remain unfinished, locks held, and you possible wouldn't know which job will execute next in the context of this unfinished transaction.
type of the result
SQLiteQueue