package roboguice.util;
/**
* Represent an action that may be run in the background. Following execution of the task, results are processed in
* the foreground thread using {@link #onSuccess(Object)} and {@link #onException(Exception)}.
* <p>
* Similar to java's {@link java.util.concurrent.Callable}, except the result of the
* background operation is passed to the UI thread for processing via {@link #onSuccess(Object)} and {@link #onException(Exception)}.
* <p>
* Similar to Android's {@link android.os.AsyncTask}, except it adds handling for
* exceptions and finally and call also be used with java's @{link java.util.concurrent.Executor} and {@link java.util.concurrent.ExecutorService}
* <p>
* To use, subclass from {@link AndroidCallable} and execute using an executor such as one from {@link java.util.concurrent.Executors}.
* @see AndroidCallable
* @param <ResultT>
*/
public interface AndroidCallableI<ResultT> {
/**
* Executed in the handler's thread (usually the UI thread) before the task's doInBackground() method is called.
* Exceptions will be handled by the onException callback.
*/
void onPreCall() throws Exception;
/**
* Executed in the executor's background thread.
* Exceptions will be handled by the onException callback.
*/
ResultT doInBackground() throws Exception;
/**
* Executed in the handler's thread (usually the UI thread) if doInBackground threw an exception.
* @param e the exception thrown by the {@link #doInBackground} method
*/
void onException(Exception e);
/**
* Executed in the handler's thread (usually the UI thread) if call returned a result.
* Exceptions will be thrown from the UI thread, which will crash the app if not caught.
* @param result the result returned by the {@link #doInBackground} method
*/
void onSuccess(ResultT result);
/**
* Executed in the handler's thread (usually the UI thread) after {@link #onSuccess(Object)} or {@link #onException(Exception)}
* are executed.
* Always executed iff {@link #doInBackground()} is executed. Not executed if the task is canceled before it is executed.
*/
void onFinally();
}