An utility library for Android to run actions in background. It handles orientation changes and delegates results to the visible Activity
.
Download the latest version or grab via Gradle:
dependencies {
compile 'net.vrallev.android:android-task:1.1.4'
}
The class TaskExecutor
serves as entry point. Your background actions need to extend the class Task
. Your callback method needs be annotated with TaskResult
and has to accept exactly one result object, which the Task
returns. You may want to take a look at the demo.
public class MyActivity extends Activity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
int taskId = new MyTask().start(this);
}
@TaskResult
public void onResult(Integer result) {
// handle result, this method gets called on the UI thread and only if the activity is visible
}
}
public class MyTask extends Task<Integer> {
@Override
protected Integer execute() {
return 5;
}
}
You can create your own TaskExecutor
instance, if you want to change the behavior.
new Builder()
.setExecutorService(Executors.newSingleThreadExecutor()) // default CachedThreadPool
.setPostResult(PostResult.ON_ANY_THREAD) // default PostResult.UI_THREAD
.build()
.asSingleton();
The TaskExecutor
returns an ID. You can restore this ID in onCreate(Bundle savedInstanceState
to find your Task
.
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
if (savedInstanceState != null) {
int taskId = savedInstanceState.getInt(TASK_ID_KEY, -1);
MyTask task = TaskExecutor.getInstance().getTask(taskId);
}
}
A callback method can have a second parameter to get the specific Task
instance.
@TaskResult
public void onResult(Integer result, MyTask task) {
// handle result, this method gets called on the UI thread and only if the activity is visible
}
You can annotate the callback method with a concrete ID, if you want to reuse a Task
but provide different callbacks. Attention: If your callback method has an ID, then a Task
submitted without an ID won't find this callback method.
public void startTask() {
Task myTask = new MyTask();
TaskExecutor.getInstance().execute(myTask, this, "my_id");
}
@TaskResult(id = "my_id")
public void onResult(Integer result, MyTask task) {
// handle result, this method gets called on the UI thread and only if the activity is visible
}
If you want to submit a Task
, which should not return any result and shouldn't invoke any callback method, then extend TaskNoCallback
. Compared to a normal Thread
the purpose of this class is that you still have access to the Context
and can find the Task
in the TaskExecutor
.
public class SimpleNoCallbackTask extends TaskNoCallback {
@Override
protected void executeTask() {
// do anything
}
}
It's possible to replace the callback, if another Activity
or Fragment
should handle the result.
public class ReplaceCallbackActivity extends Activity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
List<IntegerTask> tasks = TaskExecutor.getInstance().getAllTasks(IntegerTask.class);
for (IntegerTask task : tasks) {
task.replaceCallback(this);
}
}
@TaskResult
public void onResult(Integer integer) {
Toast.makeText(this, "Replaced " + integer, Toast.LENGTH_SHORT).show();
}
}
The TaskExecutor
monitors the state of the Activity
. When a Task
finished, the TaskExecutor
searches the callback method and invokes it on the visible Activity
or Fragment
.
UI components are only referenced with a WeakReference
to avoid memory leaks. If a callback method can't be found or the Activity
was already cleared, then the result from the Task
is dropped.
Your class, which can receive callbacks, must be an instance of Activity
, FragmentActivity
or Fragment
from the support library.
The library uses reflection to find your callback method at runtime. This costs time, but classes are scanned in the background.
Copyright 2015 Ralf Wondratschek
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.