com.github.ignition.core.tasks
Class IgnitedAsyncTask<ContextT extends android.content.Context,ParameterT,ProgressT,ReturnT>

java.lang.Object
  android.os.AsyncTask<ParameterT,ProgressT,ReturnT>
      com.github.ignition.core.tasks.IgnitedAsyncTask<ContextT,ParameterT,ProgressT,ReturnT>

Type Parameters:

ContextT -

ParameterT -

ProgressT -

ReturnT -

All Implemented Interfaces:

IgnitedAsyncTaskContextHandler<ProgressT,ReturnT>, IgnitedAsyncTaskHandler<ContextT,ProgressT,ReturnT>

public abstract class IgnitedAsyncTask<ContextT extends android.content.Context,ParameterT,ProgressT,ReturnT>
extends android.os.AsyncTask<ParameterT,ProgressT,ReturnT>
implements IgnitedAsyncTaskHandler<ContextT,ProgressT,ReturnT>, IgnitedAsyncTaskContextHandler<ProgressT,ReturnT>

An extension to AsyncTask that removes some of the boilerplate that's typically involved. Some of the things handled for you by this class are:

• handles a Context reference for you, which is passed to all status callbacks
• allows worker method to throw exceptions, which will be passed to onTaskFailed(Context, Exception)
• allows re-using a task as a skeleton that delegates to different worker implementations via IgnitedAsyncTask.IgnitedAsyncTaskCallable
• allows a Context to register itself as a callback handler via IgnitedAsyncTaskContextHandler
• allows any arbitrary object to register itself as a callback handler via IgnitedAsyncTaskHandler

Since this class keeps a reference to a Context (either directly or indirectly through a callback handler), you MUST ensure that this reference is cleared when the Context gets destroyed. You can handle Context and handler connection and disconnection using the connect(ContextT) and disconnect() methods. For Activities, a good place to call them is onCreate and onDestroy respectively.

Please note that the callbacks added by this class will ONLY be called if the context reference is valid. You can still receive AsyncTask's callbacks by overriding the callbacks defined in that class.

Author:

Matthias Kaeppler

Nested Class Summary

static interface

IgnitedAsyncTask.IgnitedAsyncTaskCallable<ContextT extends android.content.Context,ParameterT,ProgressT,ReturnT>

Nested classes/interfaces inherited from class android.os.AsyncTask

android.os.AsyncTask.Status

Field Summary

protected boolean

cancelOnActivityBack

Constructor Summary

IgnitedAsyncTask()

Method Summary

void	connect(ContextT context) Connects a context object to this task.
void	connect(IgnitedAsyncTaskHandler<ContextT,ProgressT,ReturnT> handler) Connects an IgnitedAsyncTaskHandler to this task to receive callbacks.
void	disconnect() Disconnects all context references, also those that are both a Context and handler at the same time.
protected ReturnT	doInBackground(ParameterT... params) No, you want to override run(Object...) instead.
boolean	failed()
ContextT	getContext() Returns the task's current context reference.
IgnitedAsyncTaskContextHandler<ProgressT,ReturnT>	getContextHandler() If you have connected a Context which implements the IgnitedAsyncTaskContextHandler interface, this instance will be returned.
IgnitedAsyncTaskHandler<ContextT,ProgressT,ReturnT>	getDelegateHandler() If you have connected a Context or POJO which implements the IgnitedAsyncTaskHandler interface, this instance will be returned.
boolean	isCancelOnActivityBack()
boolean	isFinished()
boolean	isPending()
boolean	isRunning()
protected void	onPostExecute(ReturnT result) Don't override this method; use onTaskCompleted(ContextT, ReturnT), onTaskSuccess(ContextT, ReturnT), and onTaskFailed(ContextT, java.lang.Exception) instead.
protected void	onPreExecute() If you rely on a valid context reference, override onTaskStarted(Context) instead.
protected void	onProgressUpdate(ProgressT... values) If you rely on a valid context reference, override #onProgress instead.
boolean	onTaskCompleted(ContextT context, ReturnT result) Implement this method to handle a completed task execution, regardless of outcome.
boolean	onTaskCompleted(ReturnT result) Implement this method to handle a completed task execution, regardless of outcome.
boolean	onTaskFailed(ContextT context, Exception error) Override this method to handle an error that occurred during task execution in a graceful manner.
boolean	onTaskFailed(Exception error) Override this method to handle an error that occurred during task execution in a graceful manner.
boolean	onTaskProgress(ContextT context, ProgressT... progress) Override this method to update progress elements on the UI thread.
boolean	onTaskProgress(ProgressT... progress) Override this method to update progress elements on the UI thread.
boolean	onTaskStarted() Override this method to prepare task execution.
boolean	onTaskStarted(ContextT context) Override this method to prepare task execution.
boolean	onTaskSuccess(ContextT context, ReturnT result) Implement this method to handle a successful task execution.
boolean	onTaskSuccess(ReturnT result) Implement this method to handle a successful task execution.
ReturnT	run(ParameterT... params) Implement this method to define your task execution.
void	setCallable(IgnitedAsyncTask.IgnitedAsyncTaskCallable<ContextT,ParameterT,ProgressT,ReturnT> callable) Use an IgnitedAsyncTask.IgnitedAsyncTaskCallable instead of overriding run(ParameterT...).
void	setCancelOnActivityBack(boolean cancelOnActivityBack)
void	setContext(ContextT context) DON'T use this to handle the task's context reference.

Methods inherited from class android.os.AsyncTask

cancel, execute, get, get, getStatus, isCancelled, onCancelled, publishProgress

Methods inherited from class java.lang.Object

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

Field Detail

cancelOnActivityBack

protected boolean cancelOnActivityBack

Constructor Detail

IgnitedAsyncTask

public IgnitedAsyncTask()

Method Detail

setCancelOnActivityBack

public void setCancelOnActivityBack(boolean cancelOnActivityBack)

isCancelOnActivityBack

public boolean isCancelOnActivityBack()

connect

public void connect(ContextT context)

Connects a context object to this task. Use this method immediately after first creating the task, and again in Activity.onCreate(android.os.Bundle) to re-connect tasks that you retained via Activity.onRetainNonConfigurationInstance(). Make sure to always disconnect() a context in Activity.onDestroy().

As long as this context is not null, it will be passed to any handler callbacks associated with this task, as well as to the task's own callbacks. If the context you pass here implements IgnitedAsyncTaskContextHandler, it will be registered to receive callbacks itself. If instead it implements the more generic IgnitedAsyncTaskHandler, and if no other handler of this type has been connected before (!), then the context will also receive these callbacks. If however an ordinary POJO had already been connected to this task as a IgnitedAsyncTaskHandler, then the context will not receive callbacks via this interface (this is because a context must be disconnected from the task in onDestroy, while ordinary handlers that are not Contexts will be retained by the task instance).

connect

public void connect(IgnitedAsyncTaskHandler<ContextT,ProgressT,ReturnT> handler)

Connects an IgnitedAsyncTaskHandler to this task to receive callbacks. The context instance wrapped by this handler will be passed to connect(Context).

Parameters:

handler - the handler object to receive task callbacks

disconnect

public void disconnect()

Disconnects all context references, also those that are both a Context and handler at the same time. Call this method in Context#onDestroy. Note that this will NOT disconnect handlers which are not Contexts but plain POJOs, so make sure you do not leak an implicit reference to the same context from any handlers you have connected.

getContext

public ContextT getContext()

Returns the task's current context reference. Can be null. Handling the context reference is done in connect(Context) and disconnect().

Specified by:

getContext in interface IgnitedAsyncTaskHandler<ContextT extends android.content.Context,ProgressT,ReturnT>

setContext

public void setContext(ContextT context)

DON'T use this to handle the task's context reference. Use connect(Context) and disconnect() instead.

Specified by:

setContext in interface IgnitedAsyncTaskHandler<ContextT extends android.content.Context,ProgressT,ReturnT>

getContextHandler

public IgnitedAsyncTaskContextHandler<ProgressT,ReturnT> getContextHandler()

If you have connected a Context which implements the IgnitedAsyncTaskContextHandler interface, this instance will be returned. Null otherwise.

getDelegateHandler

public IgnitedAsyncTaskHandler<ContextT,ProgressT,ReturnT> getDelegateHandler()

If you have connected a Context or POJO which implements the IgnitedAsyncTaskHandler interface, this instance will be returned. Null otherwise.

onPreExecute

protected void onPreExecute()

If you rely on a valid context reference, override onTaskStarted(Context) instead.

Overrides:

onPreExecute in class android.os.AsyncTask<ParameterT,ProgressT,ReturnT>

onTaskStarted

public boolean onTaskStarted(ContextT context)

Override this method to prepare task execution. The default implementation simply returns false. This variant of the method is only called if context is not null.

Specified by:

onTaskStarted in interface IgnitedAsyncTaskHandler<ContextT extends android.content.Context,ProgressT,ReturnT>

Parameters:

context - The most recent instance of the Context that executed this IgnitedAsyncTask

See Also:

AsyncTask#onPreExecute}

onTaskStarted

public boolean onTaskStarted()

Override this method to prepare task execution. The default implementation simply returns false. This variant of the method is called even when no context is connected.

Specified by:

onTaskStarted in interface IgnitedAsyncTaskContextHandler<ProgressT,ReturnT>

See Also:

AsyncTask#onPreExecute}

onProgressUpdate

protected void onProgressUpdate(ProgressT... values)

If you rely on a valid context reference, override #onProgress instead.

Overrides:

onProgressUpdate in class android.os.AsyncTask<ParameterT,ProgressT,ReturnT>

onTaskProgress

public boolean onTaskProgress(ContextT context,
                              ProgressT... progress)

Override this method to update progress elements on the UI thread. The default implementation simply returns false. This variant of the method is only called if context is not null.

Specified by:

onTaskProgress in interface IgnitedAsyncTaskHandler<ContextT extends android.content.Context,ProgressT,ReturnT>

Parameters:

context - The most recent instance of the Context that executed this IgnitedAsyncTask

progress - the progress values

See Also:

AsyncTask#publishProgress}, AsyncTask#onProgressUpdate}

onTaskProgress

public boolean onTaskProgress(ProgressT... progress)

Override this method to update progress elements on the UI thread. The default implementation simply returns false. This variant of the method is called even when no context is connected.

Specified by:

onTaskProgress in interface IgnitedAsyncTaskContextHandler<ProgressT,ReturnT>

Parameters:

progress - the progress values

See Also:

AsyncTask#publishProgress}, AsyncTask#onProgressUpdate}

doInBackground

protected final ReturnT doInBackground(ParameterT... params)

No, you want to override run(Object...) instead.

Specified by:

doInBackground in class android.os.AsyncTask<ParameterT,ProgressT,ReturnT>

run

public ReturnT run(ParameterT... params)
            throws Exception

Implement this method to define your task execution. If your task logic is pluggable, but shares progress reporting or pre/post execute hooks, you can also set a IgnitedAsyncTask.IgnitedAsyncTaskCallable via setCallable(IgnitedAsyncTaskCallable)

Typically you do not call this method directly; instead it's called by #execute() and run on a worker thread. If however you want to execute the task synchronously, you can invoke this method directly.

Parameters:

params - the parameters for your task

Returns:

the result of your task

Throws:

Exception

See Also:

AsyncTask#doInBackground}

onPostExecute

protected void onPostExecute(ReturnT result)

Don't override this method; use onTaskCompleted(ContextT, ReturnT), onTaskSuccess(ContextT, ReturnT), and onTaskFailed(ContextT, java.lang.Exception) instead.

Overrides:

onPostExecute in class android.os.AsyncTask<ParameterT,ProgressT,ReturnT>

onTaskCompleted

public boolean onTaskCompleted(ContextT context,
                               ReturnT result)

Implement this method to handle a completed task execution, regardless of outcome. The default implementation simply returns false. This variant of the method is only called if context is not null.

Specified by:

onTaskCompleted in interface IgnitedAsyncTaskHandler<ContextT extends android.content.Context,ProgressT,ReturnT>

Parameters:

context - The most recent instance of the Context that executed this IgnitedAsyncTask the result of the task execution

See Also:

AsyncTask#onPostExecute}

onTaskCompleted

public boolean onTaskCompleted(ReturnT result)

Implement this method to handle a completed task execution, regardless of outcome. The default implementation simply returns false. This variant of the method is called even when no context is connected.

Specified by:

onTaskCompleted in interface IgnitedAsyncTaskContextHandler<ProgressT,ReturnT>

Parameters:

result - the result of the task execution

See Also:

AsyncTask#onPostExecute}

onTaskSuccess

public boolean onTaskSuccess(ContextT context,
                             ReturnT result)

Implement this method to handle a successful task execution. The default implementation simply returns false. This variant of the method is only called if context is not null.

Specified by:

onTaskSuccess in interface IgnitedAsyncTaskHandler<ContextT extends android.content.Context,ProgressT,ReturnT>

Parameters:

context - The most recent instance of the Context that executed this IgnitedAsyncTask

result - the result of the task execution

onTaskSuccess

public boolean onTaskSuccess(ReturnT result)

Implement this method to handle a successful task execution. The default implementation simply returns false. This variant of the method is called even when no context is connected.

Specified by:

onTaskSuccess in interface IgnitedAsyncTaskContextHandler<ProgressT,ReturnT>

Parameters:

result - the result of the task execution

onTaskFailed

public boolean onTaskFailed(ContextT context,
                            Exception error)

Override this method to handle an error that occurred during task execution in a graceful manner. The default implementation returns false. This variant of the method is only called if context is not null.

Specified by:

onTaskFailed in interface IgnitedAsyncTaskHandler<ContextT extends android.content.Context,ProgressT,ReturnT>

Parameters:

context - The most recent instance of the Context that executed this IgnitedAsyncTask

error - The exception that was thrown during task execution

onTaskFailed

public boolean onTaskFailed(Exception error)

Override this method to handle an error that occurred during task execution in a graceful manner. The default implementation returns false. This variant of the method is called even when no context is connected.

Specified by:

onTaskFailed in interface IgnitedAsyncTaskContextHandler<ProgressT,ReturnT>

Parameters:

error - The exception that was thrown during task execution

failed

public boolean failed()

Returns:

true if an Exception was thrown in run(ParameterT...)

isPending

public boolean isPending()

See Also:

AsyncTask.Status.PENDING

isRunning

public boolean isRunning()

See Also:

AsyncTask.Status.RUNNING

isFinished

public boolean isFinished()

See Also:

AsyncTask.Status.FINISHED

setCallable

public void setCallable(IgnitedAsyncTask.IgnitedAsyncTaskCallable<ContextT,ParameterT,ProgressT,ReturnT> callable)

Use an IgnitedAsyncTask.IgnitedAsyncTaskCallable instead of overriding run(ParameterT...). This can be useful when creating task skeletons that need to implement the worker method differently.

Parameters:

callable -