Major update:

- Renamed TaskHandler to TaskManager;
- Some critical bug fixes;
- Added the TaskAttachListener and corresponding attachListener(String, TaskAttachListener) method,  for restoring the UI state prior to attaching a Tasks Callback listener;
- Added some more documentation (still work-in-progress though);

Author: Rolf-Smit

README.md

@@ -25,10 +25,10 @@ dependencies {
 In order to, execute a task which modifies the user-interface and to retain it across configuration changes you will need to do three things:
 
 1. Create an implementation of the `Task` class;
-2. Execute the task using the `TaskHandler` in an`Activity` which implements the `Callback` interface;
-3. Retain the task when configuration changes by overriding the `onStart()` method and calling the `TaskHandler.attachListener()` method;
+2. Execute the task using the `TaskManager` in an`Activity` which implements the `Callback` interface;
+3. Retain the task when configuration changes by overriding the `onStart()` method and calling the `TaskManager.attachListener()` method;
 
-The Activity's `TaskHandler` makes sure that tasks can be retained across configuration changes and is responsible for removing the `Callback` listener when the Activity's user-interface is no longer valid. You are however responsible for re-attaching a new `Callback` listener when the Activity 's user-interface is restarted.
+The Activity's `TaskManager` makes sure that tasks can be retained across configuration changes and is responsible for removing the `Callback` listener when the Activity's user-interface is no longer valid. You are however responsible for re-attaching a new `Callback` listener when the Activity 's user-interface is restarted.
 
 ### 1.1 Creating the task
 
@@ -61,23 +61,23 @@ private class ExampleTask extends Task<Integer, String> {
 
 
 ### 1.2 Executing the task
-Before you can execute the `ExampleTask` you first need to get the current Activity's `TaskHandler`. A `TaskHandler` keeps references to tasks and executes them. You can obtain the current Activity's `TaskHandler` using the `TaskHandler.getActivityTaskHandler()` method:
+Before you can execute the `ExampleTask` you first need to get the current Activity's `TaskManager`. A `TaskManager` keeps references to tasks and executes them. You can obtain the current Activity's `TaskManager` using the `TaskManager.getActivityTaskManager()` method:
 
 ```java
-public TaskHandler getTaskHandler(){
-    return TaskHandler.getActivityTaskHandler(getSupportFragmentManager());
+public TaskManager getTaskManager(){
+    return TaskManager.getActivityTaskManager(getSupportFragmentManager());
 }
 ```
 
-Then you can execute the task using the `TaskHandler.execute()` method. This method needs two arguments, the task to execute and a `Callback` listener to send feedback to. Preferably your activity implements the `Callback` interface, but this isn't necessarily needed.
+Then you can execute the task using the `TaskManager.execute()` method. This method needs two arguments, the task to execute and a `Callback` listener to send feedback to. Preferably your activity implements the `Callback` interface, but this isn't necessarily needed.
 
 ```java
 public class Main extends AppCompatActivity implements Task.Callback {
 
 	@Override
 	public void onClick(View view){
 		ExampleTask task = new ExampleTask("activity-unique-tag");
-		getTaskHandler().execute(task, this);
+		getTaskManager().execute(task, this);
 	}
 
 	@Override
@@ -94,30 +94,30 @@ public class Main extends AppCompatActivity implements Task.Callback {
 ```
 
 ### 1.2 Retaining the task
-When the configuration changes (device rotates) the Activity's `TaskHandler` will automatically remove the `Callback` listeners from all active tasks. This is needed otherwise the tasks could leak Activity, Fragment or other references.
+When the configuration changes (device rotates) the Activity's `TaskManager` will automatically remove the `Callback` listeners from all active tasks. This is needed otherwise the tasks could leak Activity, Fragment or other references.
 
 > **In-depth:**
-> The `TaskHandler` will automatically remove the `Callback` listeners when the Activity is stopping (`onStop()`). At this moment the user-interface has become *"unstable"*, for example, when this happens the FragmentManager refuses to add new Fragments because the Activity's `onSaveInstanceState()` method has already been called. If the `Callback` listener is not removed by the `TaskHandler` before this point, then a `DialogFragment.show()` call will throw an exception when called in the `onPostExecute()` method. This is why the `Callback` listeners are removed when the Activity stops.
+> The `TaskManager` will automatically remove the `Callback` listeners when the Activity is stopping (`onStop()`). At this moment the user-interface has become *"unstable"*, for example, when this happens the FragmentManager refuses to add new Fragments because the Activity's `onSaveInstanceState()` method has already been called. If the `Callback` listener is not removed by the `TaskManager` before this point, then a `DialogFragment.show()` call will throw an exception when called in the `onPostExecute()` method. This is why the `Callback` listeners are removed when the Activity stops.
 
-To retain the task when your Activity is recreated you will need to re-attach a (new) `Callback` listener using the `TaskHandler.attachListener()` method. The best place to do this is in the `onStart()` method right after the user-interface has been created.
+To retain the task when your Activity is recreated you will need to re-attach a (new) `Callback` listener using the `TaskManager.attachListener()` method. The best place to do this is in the `onStart()` method right after the user-interface has been created.
 
 
 ```java
 @Override
 public void onStart(){
     super.onStart();
     //Re-attach the this Activity as listener for task
-    getTaskHandler().attachListener("activity-unique-tag", this);
+    getTaskManager().attachListener("activity-unique-tag", this);
 }
 ```
 
 ## 2. How it works
 ---
 ####**Retaining tasks**
-Tasks retained using the described method are stored in a *"no-ui-fragment"* this fragment retained across configuration changes and is added to your Activity's `FragmentManager` the first time you call `TaskHandler.getActivityTaskHandler()`. This fragment is from that point on bound to the Activity's life-cycle and holds an internal `TaskHandler`. The fragment makes sure that the internal `TaskHandler` removes all `Callback` listeners as soon as the Activity is stopping (`onStop()`).
+Tasks retained using the described method are stored in a *"no-ui-fragment"* this fragment retained across configuration changes and is added to your Activity's `FragmentManager` the first time you call `TaskManager.getActivityTaskManager()`. This fragment is from that point on bound to the Activity's life-cycle and holds an internal `TaskManager`. The fragment makes sure that the internal `TaskManager` removes all `Callback` listeners as soon as the Activity is stopping (`onStop()`).
 
 ####**Task without callback finishes**
-When a Task doesn't have a `Callback` listener to deliver it's results to it will skip the delivery and redeliver the results as soon as a new listener is attached. If you call the `TaskHandler.attachListener()` method in the `onStart()` method, then the listener will be fired and you need to be sure that the user-interface is ready.
+When a Task doesn't have a `Callback` listener to deliver it's results to it will skip the delivery and redeliver the results as soon as a new listener is attached. If you call the `TaskManager.attachListener()` method in the `onStart()` method, then the listener will be fired and you need to be sure that the user-interface is ready.
 
 Only the `onPostExecute()` and `onCanceled()` methods will be redelivered, other methodes won't be redelivered.
 
@@ -155,7 +155,7 @@ To get the tasks most recent progress update use the `getLastKnownProgress()` me
 If you need the `onProgressUpdated` and `onCanceled` callback methods you can implement the `AdvancedCallback` interface, which is an extension of the `Callback` interface.
 
 ####**TaskExecutor & Executor**
-You can also execute tasks without using a `TaskHandler` this means that you are responsible for removing and setting the `Callback` listener. Executing tasks without using the `TaskHandler` is handy when you don't need to get any feedback to the Activity's user-interface.
+You can also execute tasks without using a `TaskManager` this means that you are responsible for removing and setting the `Callback` listener. Executing tasks without using the `TaskManager` is handy when you don't need to get any feedback to the Activity's user-interface.
 
 ```java
 TaskExecutor.executeParallel(new ExampleTask());

demo/build.gradle

@@ -20,8 +20,8 @@ android {
 }
 
 dependencies {
-    //compile project(':library')
-    compile 'org.neotech.library:android-retainable-tasks:0.1.0'
+    compile project(':library')
+    //compile 'org.neotech.library:android-retainable-tasks:0.1.0'
 
     compile 'com.android.support:appcompat-v7:23.2.0'
     compile 'com.android.support:design:23.2.0'

demo/src/main/java/org/neotech/app/retainabletasksdemo/Main.java

@@ -1,5 +1,6 @@
 package org.neotech.app.retainabletasksdemo;
 
+import android.annotation.SuppressLint;
 import android.content.Intent;
 import android.net.Uri;
 import android.os.Bundle;
@@ -9,21 +10,26 @@
 import android.support.v7.app.AppCompatActivity;
 import android.support.v7.widget.Toolbar;
 import android.view.View;
+import android.widget.Button;
 import android.widget.Toast;
 
+import org.neotech.app.retainabletasksdemo.tasks.CountDownTask;
 import org.neotech.app.retainabletasksdemo.tasks.SimpleTask;
 import org.neotech.app.retainabletasksdemo.tasks.TaskWithoutCallback;
 import org.neotech.library.retainabletasks.Task;
 import org.neotech.library.retainabletasks.TaskExecutor;
-import org.neotech.library.retainabletasks.TaskHandler;
+import org.neotech.library.retainabletasks.TaskManager;
 
 public class Main extends AppCompatActivity implements View.OnClickListener, Task.AdvancedCallback, OnAlertDialogClickListener {
 
-    private static final String TASK_PROGRESS = "Demo-task";
+    private static final String TASK_RETAIN_UI_STATE = "retain-ui-state";
+    private static final String TASK_PROGRESS = "progress-dialog";
     private static final String DIALOG_PROGRESS = "progress-dialog";
 
     private ProgressDialog progressDialog;
 
+    private Button retainUserInterfaceButton;
+
     @Override
     protected void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
@@ -33,13 +39,34 @@ protected void onCreate(Bundle savedInstanceState) {
         findViewById(R.id.fab).setOnClickListener(this);
         findViewById(R.id.button_no_ui_task).setOnClickListener(this);
         findViewById(R.id.button_progress_task).setOnClickListener(this);
+
+        retainUserInterfaceButton = (Button) findViewById(R.id.button_retain_ui_state_task);
+        retainUserInterfaceButton.setOnClickListener(this);
     }
 
     @Override
     protected void onStart() {
         super.onStart();
         progressDialog = ProgressDialog.getExistingInstance(getSupportFragmentManager(), DIALOG_PROGRESS);
-        getTaskHandler().attachListener(TASK_PROGRESS, this);
+        getTaskManager().attachListener(TASK_PROGRESS, this);
+
+
+        getTaskManager().attachListener(TASK_RETAIN_UI_STATE, new TaskManager.TaskAttachListener() {
+            @Override
+            public Task.Callback onPreAttach(Task<?, ?> task) {
+                /**
+                 * the onPreAttach method will only be called if the task did not deliver its result
+                 * and thus is still available/referenced by the TaskManger.
+                 *
+                 * At this point the UI can be restored to the "task is running" state.
+                 */
+                if (!task.isResultDelivered()) { //This call isn't necessary.
+                    retainUserInterfaceButton.setEnabled(false);
+                    retainUserInterfaceButton.setText("" + task.getLastKnownProgress());
+                }
+                return Main.this;
+            }
+        });
     }
 
     @Override
@@ -48,47 +75,63 @@ public void onClick(View v) {
         if(id == R.id.fab){
             startActivity(new Intent(Intent.ACTION_VIEW, Uri.parse("https://github.com/NeoTech-Software/Android-Retainable-Tasks")));
         } else if(id == R.id.button_progress_task) {
-            if (getTaskHandler().isRunning(TASK_PROGRESS)) {
+            if (getTaskManager().isRunning(TASK_PROGRESS)) {
                 Toast.makeText(this, R.string.toast_task_already_running, Toast.LENGTH_SHORT).show();
             }
             SimpleTask task = new SimpleTask(TASK_PROGRESS);
-            getTaskHandler().execute(task, this);
+            getTaskManager().execute(task, this);
 
         } else if(id == R.id.button_no_ui_task){
             TaskWithoutCallback task = new TaskWithoutCallback(this);
             TaskExecutor.execute(task);
-
+        } else if(id == R.id.button_retain_ui_state_task){
+            CountDownTask task = new CountDownTask(TASK_RETAIN_UI_STATE, 10);
+            getTaskManager().execute(task, this);
+            retainUserInterfaceButton.setEnabled(false);
         }
     }
 
-    public TaskHandler getTaskHandler(){
-        return TaskHandler.getActivityTaskHandler(getSupportFragmentManager());
+    public TaskManager getTaskManager(){
+        return TaskManager.getActivityTaskManager(getSupportFragmentManager());
     }
 
     @Override
     public void onPreExecute(Task<?, ?> task) {
-        progressDialog = ProgressDialog.showIfNotShowing(getSupportFragmentManager(), DIALOG_PROGRESS);
+        if(task.getTag().equals(TASK_PROGRESS)) {
+            progressDialog = ProgressDialog.showIfNotShowing(getSupportFragmentManager(), DIALOG_PROGRESS);
+        }
     }
 
     @Override
     public void onPostExecute(Task<?, ?> task) {
-        progressDialog.dismiss();
-        Snackbar.make(findViewById(android.R.id.content), getString(R.string.toast_task_finished, getString(R.string.task_progress_dialog)), Snackbar.LENGTH_LONG).show();
+        if(task.getTag().equals(TASK_PROGRESS)) {
+            progressDialog.dismiss();
+            Snackbar.make(findViewById(android.R.id.content), getString(R.string.toast_task_finished, getString(R.string.task_progress_dialog)), Snackbar.LENGTH_LONG).show();
+        } else if(task.getTag().equals(TASK_RETAIN_UI_STATE)){
+            retainUserInterfaceButton.setEnabled(true);
+            retainUserInterfaceButton.setText(R.string.task_retain_ui_state);
+        }
     }
 
     @Override
     public void onCanceled(Task<?, ?> task) {
-        progressDialog.dismiss();
-        Snackbar.make(findViewById(android.R.id.content), getString(R.string.toast_task_canceled, getString(R.string.task_progress_dialog)), Snackbar.LENGTH_LONG).show();
+        if(task.getTag().equals(TASK_PROGRESS)) {
+            progressDialog.dismiss();
+            Snackbar.make(findViewById(android.R.id.content), getString(R.string.toast_task_canceled, getString(R.string.task_progress_dialog)), Snackbar.LENGTH_LONG).show();
+        }
     }
 
     @Override
     public void onProgressUpdate(Task<?, ?> task, Object progress) {
-        progressDialog.setProgress((int) progress);
+        if(task.getTag().equals(TASK_PROGRESS)) {
+            progressDialog.setProgress((int) progress);
+        } else if(task.getTag().equals(TASK_RETAIN_UI_STATE)){
+            retainUserInterfaceButton.setText("" + (int) progress);
+        }
     }
 
     @Override
     public void onDialogFragmentClick(DialogFragment fragment, int which) {
-        getTaskHandler().cancel(TASK_PROGRESS);
+        getTaskManager().cancel(TASK_PROGRESS);
     }
 }

demo/src/main/java/org/neotech/app/retainabletasksdemo/tasks/CountDownTask.java

@@ -0,0 +1,27 @@
+package org.neotech.app.retainabletasksdemo.tasks;
+
+import android.os.SystemClock;
+
+import org.neotech.library.retainabletasks.Task;
+
+/**
+ * Created by Rolf on 3-3-2016.
+ */
+public class CountDownTask extends Task<Integer, Void> {
+
+    private final int amount;
+
+    public CountDownTask(String tag, int amount) {
+        super(tag);
+        this.amount = amount;
+    }
+
+    @Override
+    protected Void doInBackground() {
+        for(int i = amount; i > 0; i--){
+            publishProgress(i);
+            SystemClock.sleep(1000); //Inaccurate count-down, but hey... its an example :)
+        }
+        return null;
+    }
+}

demo/src/main/res/layout/content_main.xml

@@ -30,5 +30,11 @@
             android:layout_width="wrap_content"
             android:text="@string/task_progress_dialog" />
 
+        <Button
+            android:id="@+id/button_retain_ui_state_task"
+            android:layout_height="wrap_content"
+            android:layout_width="wrap_content"
+            android:text="@string/task_retain_ui_state" />
+
     </LinearLayout>
 </ScrollView>

demo/src/main/res/values/strings.xml

@@ -8,6 +8,8 @@
 
     <string name="task_no_ui_callback">Task without UI callback</string>
     <string name="task_progress_dialog">Progress dialog task</string>
+    <string name="task_retain_ui_state">Retain UI state task</string>
+
     <string name="dialog_progress_title">Loading…</string>
     <string name="action_cancel">Cancel</string>
 </resources>

library/src/main/java/org/neotech/library/retainabletasks/BaseTaskHandler.java renamed to library/src/main/java/org/neotech/library/retainabletasks/BaseTaskManager.java

@@ -10,9 +10,9 @@
 /**
  * Created by Rolf on 29-2-2016.
  */
-public class BaseTaskHandler extends TaskHandler {
+public class BaseTaskManager extends TaskManager {
 
-    private static final String TAG = "SimpleTaskHandler";
+    private static final String TAG = "SimpleTaskManager";
 
     protected final HashMap<String, Task<?, ?>> tasks = new HashMap<>();
 
@@ -24,18 +24,37 @@ public class BaseTaskHandler extends TaskHandler {
     @Override
     @MainThread
     public Task<?, ?> attachListener(@NonNull String tag, @NonNull Task.Callback callback){
-        Task<?, ?> task = tasks.get(tag);
+        final Task<?, ?> task = tasks.get(tag);
         if(task == null){
             return null;
         }
         task.setCallback(new CallbackShadow(callback));
         return task;
     }
 
+    @Override
+    @MainThread
+    public Task<?, ?> attachListener(@NonNull String tag, @NonNull TaskAttachListener listener){
+        final Task<?, ?> task = tasks.get(tag);
+        if(task == null){
+            return null;
+        }
+        task.setCallback(new CallbackShadow(listener.onPreAttach(task)));
+        return task;
+    }
+
+    @Override
+    @MainThread
+    public Task<?, ?> attachListener(@NonNull Task<?, ?> task, @NonNull Task.Callback callback) {
+        task.setCallback(new CallbackShadow(callback));
+        return task;
+    }
+
     @Override
     @MainThread
     public <Progress, Result> void execute(@NonNull Task<Progress, Result> task, @NonNull Task.Callback callback){
-        if(tasks.get(task.getTag()) != null){
+        final Task currentTask = tasks.get(task.getTag());
+        if(currentTask != null && currentTask.isRunning()){
             throw new IllegalStateException("Task with an equal tag: '" + task.getTag() + "' has already been added and is currently running or finishing.");
         }
         tasks.put(task.getTag(), task);
@@ -45,11 +64,19 @@ public <Progress, Result> void execute(@NonNull Task<Progress, Result> task, @No
 
     @Override
     @MainThread
-    public boolean isRunning(String tag) {
+    public boolean isResultDelivered(@NonNull String tag) {
+        Task task = tasks.get(tag);
+        return task != null && task.isResultDelivered();
+    }
+
+    @Override
+    @MainThread
+    public boolean isRunning(@NonNull String tag) {
         Task task = tasks.get(tag);
         return task != null && task.isRunning();
     }
 
+
     @Override
     @MainThread
     public Task<?, ?> cancel(@NonNull String tag){