com.almworks.sqlite4java
Class SQLiteJob<T>

java.lang.Object
  com.almworks.sqlite4java.SQLiteJob<T>

Type Parameters:

T - type of the result

All Implemented Interfaces:

java.util.concurrent.Future<T>

public abstract class SQLiteJob<T>
extends java.lang.Object
implements java.util.concurrent.Future<T>

SQLiteJob is a unit of work accepted by SQLiteQueue. You can implement job(com.almworks.sqlite4java.SQLiteConnection) method and add the job to the queue with SQLiteQueue.execute(J) 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 the job() 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 as SQLiteJob<Object> or SQLiteJob<Void> and return null from the job() method.

Job implements Future interface and can be used along with different types of future results.

Also, you can override methods jobStarted(com.almworks.sqlite4java.SQLiteConnection), jobFinished(T), jobCancelled() and jobError(java.lang.Throwable) 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.

Author:

Igor Sereda

See Also:

SQLiteQueue

Constructor Summary

SQLiteJob()

Method Summary

void	cancel() Cancels this job.
boolean	cancel(boolean mayInterruptIfRunning) Attempts to cancel execution of this job.
T	complete() Wait if necessary for the job to complete and return the result.
T	get() Waits if necessary for the job to complete, and then retrieves its result.
T	get(long timeout, java.util.concurrent.TimeUnit unit) Waits if necessary for at most the given time for the job to complete, and then retrieves its result, if available.
java.lang.Throwable	getError() Returns the error thrown by the job.
protected SQLiteQueue	getQueue() Returns the instance of the queue that is currently running the job.
boolean	isCancelled() Returns true if this job was cancelled before it completed normally.
boolean	isDone() Returns true if this job completed.
protected abstract T	job(SQLiteConnection connection) Performs work on the SQLite database.
protected void	jobCancelled() This method is called after job has been cancelled, either due to call to the cancel(boolean) method, or because queue has stopped, or for any other reason.
protected void	jobError(java.lang.Throwable error) This method is called after job(com.almworks.sqlite4java.SQLiteConnection) method has thrown an exception.
protected void	jobFinished(T result) This method is called when the job is no longer in the queue.
protected void	jobStarted(SQLiteConnection connection) This method is called when the job is about to be executed, before call to job(com.almworks.sqlite4java.SQLiteConnection) method.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

SQLiteJob

public SQLiteJob()

Method Detail

job

protected abstract T job(SQLiteConnection connection)
                  throws java.lang.Throwable

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.

Parameters:

connection - an open connection to the database, not null

Returns:

the result, or null

Throws:

java.lang.Throwable - on any problem

See Also:

SQLiteQueue.execute(J)

jobStarted

protected void jobStarted(SQLiteConnection connection)
                   throws java.lang.Throwable

This method is called when the job is about to be executed, before call to job(com.almworks.sqlite4java.SQLiteConnection) method.

This method may not be called at all if a job is cancelled before execution starts.

Parameters:

connection - an open connection to the database, not null

Throws:

java.lang.Throwable - on any problem

jobFinished

protected void jobFinished(T result)
                    throws java.lang.Throwable

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(J) 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.

Parameters:

result - the result of the job, or null if the job was cancelled or has thrown exception

Throws:

java.lang.Throwable - on any problem

jobError

protected void jobError(java.lang.Throwable error)
                 throws java.lang.Throwable

This method is called after job(com.almworks.sqlite4java.SQLiteConnection) method has thrown an exception. The exception is passed as a parameter.

Parameters:

error - exception thrown by the job

Throws:

java.lang.Throwable - on any problem, or the rethrown exception

jobCancelled

protected void jobCancelled()
                     throws java.lang.Throwable

This method is called after job has been cancelled, either due to call to the cancel(boolean) method, or because queue has stopped, or for any other reason.

Throws:

java.lang.Throwable - on any problem

getQueue

protected final SQLiteQueue getQueue()

Returns the instance of the queue that is currently running the job. May return null.

Returns:

the queue that is currently running this job, if available.

getError

public java.lang.Throwable getError()

Returns the error thrown by the job.

Returns:

the error thrown by the job(com.almworks.sqlite4java.SQLiteConnection) method, or null.

isDone

public boolean isDone()

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.

Specified by:

isDone in interface java.util.concurrent.Future<T>

Returns:

true if this task completed

cancel

public boolean cancel(boolean mayInterruptIfRunning)

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(T) callbacks are called during the execution of this method.

Specified by:

cancel in interface java.util.concurrent.Future<T>

Parameters:

mayInterruptIfRunning - true if the thread executing this task should be interrupted; otherwise, in-progress tasks are allowed to complete

Returns:

false if the task could not be cancelled, typically because it has already completed normally; true otherwise

cancel

public void cancel()

Cancels this job. Convenience method to call cancel(true).

See Also:

cancel(boolean)

isCancelled

public boolean isCancelled()

Returns true if this job was cancelled before it completed normally.

Specified by:

isCancelled in interface java.util.concurrent.Future<T>

Returns:

true if this job was cancelled before it completed

get

public T get()
      throws java.lang.InterruptedException,
             java.util.concurrent.ExecutionException

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.

Specified by:

get in interface java.util.concurrent.Future<T>

Returns:

the result

Throws:

java.util.concurrent.CancellationException - if the job was cancelled

java.util.concurrent.ExecutionException - if the job threw an exception

java.lang.InterruptedException - if the current thread was interrupted while waiting

get

public T get(long timeout,
             java.util.concurrent.TimeUnit unit)
      throws java.lang.InterruptedException,
             java.util.concurrent.ExecutionException,
             java.util.concurrent.TimeoutException

Waits if necessary for at most the given time for the job to complete, and then retrieves its result, if available.

Specified by:

get in interface java.util.concurrent.Future<T>

Parameters:

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

the result

Throws:

java.util.concurrent.CancellationException - if the job was cancelled

java.util.concurrent.ExecutionException - if the job threw an exception

java.lang.InterruptedException - if the current thread was interrupted while waiting

java.util.concurrent.TimeoutException - if the wait timed out

complete

public T complete()

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.

Returns:

the result of the job, or null if it has been cancelled or has erred

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object