Goro
Goro performs asynchronous operations in a queue. You may ask Goro to perform some task with schedule
method invocation:
Goro goro = Goro.create();
goro.schedule(myOperations);
Tasks are instances of Callable
.
All the operations you ask Goro to perform are put in a queue and executed one by one. Goro allows you to organize multiple queues. You can specify what queue a task should be sent to with the second argument of schedule
method:
goro.schedule("firstQueue", myOperations1);
goro.schedule("secondQueue", myOperations2);
goro.schedule("firstQueue", myOperations3);
goro.schedule("secondQueue", myOperations4);
Queue is defined with a name. Goro does not limit number of your queues and lazily creates a new queue when a new name is passed. Controlling number of queues (actually number of different strings you pass to Goro) is your responsibility.
While operations scheduled for the same queue are guaranteed to be executed sequentially, operations in different queues may be executed in parallel.
After scheduling your task to be performed, Goro returns a Future
instance that may be used to cancel your task or wait for its finishing synchronously.
Future<?> taskFuture = goro.schedule(task);
taskFuture.cancel(true);
Future
returned by Goro has an extended interface ObservableFuture
, which allows you to asynchronously listen to task execution results:
// executed in the task thread
goro.schedule(task).subscribe(new FutureObserver() {
public void onSuccess(Result value) {
Log.i(TAG, "Task result: " + value);
}
public void onError(Throwable error) {
Log.e(TAG, "Task error: " + error);
}
});
// customize how observer is executed
goro.schedule(task).subscribe(uiThreadExecutor, observer);
You may also get an Executor
instance for a particular queue to integrate Goro with other libraries:
// --- RxJava ---
// Perform actions in "actions queue"
Observable.from([1, 2, 3])
.subscribeOn(Schedulers.executor(goro.getExecutor("actions queue")))
// Subscribe to scheduled task result
Observable.from(goro.schedule(myTask)).subscribe(...);
// --- Bolts ---
// Fetch something and post database write operation to a dedicated queue
fetchAsync(object).continueWith(new Continuation<ParseObject, Long>() {
public Long then(ParseObject object) throws Exception {
return database.storeUser(object.get("name"), object.get("age"));
}
}, goro.getExecutor("database"));
Goro Motivation
Developing Android apps you'll find out that it's a good practice to ensure sequential order of some of your asynchronous operations, like remote backend interactions or writing to the local database. Actually this is perhaps one of the main reasons why Android AsyncTask
executes its tasks one by one. However often you want to go beyond one global queue: e. g. you want to have separate series of networking and local database operations. And here Goro helps.
Service
Usually we run Goro within a Service
context to tell Android system that there are ongoing tasks and ensure that our process is not the first candidate for termination. Such a service is GoroService
. If you use aar
package of this library in a Gradle build based project, the service will be added to your app automatically. Otherwise you'll need to insert the following line into your AndroidManifest.xml
:
<service android:name="com.stanfy.enroscar.goro.GoroService" />
The service creates a Goro
instance when it's created. To interact with this instance you'll need to bind to the service. Use BoundGoro
for this:
public class MyApplciation extends Applciation {
@Override
public void onCreate() {
super.onCreate();
Goro goro = Goro.create();
GoroService.setup(this, goro);
}
}
public class MyActivity extends Activity {
// Goro instance
private BoundGoro goro;
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// The factory method is supplied with a Context used to execute bindService method.
goro = Goro.bindWith(this);
findViewById(R.id.submitButton).setOnClickListener(new OnClickListener() {
public void onClick(View view) {
goro.schedule(submissionTask);
}
});
}
protected void onStart() {
super.onStart();
goro.bind();
}
protected void onStop() {
super.onStop();
goro.unbind();
}
}
We may also ask GoroService
to perform some task sending an intent containing our Callable
instance. Yet this instance must also implement Parcelable
to be able to be packaged into Intent
extras. This way we won't need any service binding.
context.startService(GoroService.taskIntent(context, myTask));
context.startService(GoroService.taskIntent(context, "notDefaultQueue", myTask2));
GoroService
can be run in the foreground (to support background execution in android 8 https://developer.android.com/about/versions/oreo/android-8.0-changes.html#back-all):
Intent intent = GoroService.foregroundTaskIntent(context, myTask, notificationId, notification);
ContextCompat.startForegroundService(intent);
Intent intent2 = GoroService.foregroundTaskIntent(context, "notDefaultQueue", myTask2, notificationId, notification);
ContextCompat.startForegroundService(intent2);
Intent constructed with GoroService.taskIntent
can also be used to obtain a PendingIntent
and schedule task execution with AlarmManager
or Notification
:
Intent taskIntent = GoroService.taskIntent(context, myTask);
PendingIntent pending = PendingIntent.getService(context, 0, taskIntent, 0);
AlarmManager alarmManager = (AlarmManager) context.getSystemService(Context.ALARM_SERVICE);
alarmManager.set(AlarmManager.ELAPSED_REALTIME, scheduleTime, pending);
new Notification.Builder(context).setContentIntent(pending);
Goro listeners
You may add listeners that will be notified when each task starts, finishes, fails, or is canceled.
goro.addTaskListener(myListener);
All the listener callbacks are invoked in the main thread. Listener can be added or removed in the main thread only too.
Errors Handling
Goro schedule
method returns you an ObservableFuture
instance. Hence you can handle an error thrown by a scheduled Callable
in try-catch
block that wraps future's get
method invocation.
Future<Result> f = goro.schedule(task);
// ...
try {
Result result = f.get();
} catch (ExecutionException e) {
Exception thrownException = e.getCause();
}
Also the thrown exception will be passed to all observers that are subscribed to the Future
instance:
goro.schedule(task).subscribe(new FutureObserver() {
public void onSuccess(Result value) { }
public void onError(Throwable error) {
// handle you error here
}
});
This is your responsibility to handle an error. If the returned Future
instance is not interacted in any way, the thrown error will be never handled by anyone. Although your app won't crash, you'll never know about the error.
When you schedule your task with an Intent
sent to GoroService
(either directly with context.startService(GoroService.taskIntent(task))
or with execution of PendingIntent
), you do not have these means to track an error though. Hence, GoroService
sets its own observer, and if an exception is thrown by a Callable
in such conditions, service will throw GoroException
wrapping the cause, which will crash the app. This policy can be soften, if you set EXTRA_IGNORE_ERROR
to true
on the Intent
passed to the service. However we discourage you from doing this. And if you do, ensure that you have set up a global GoroListener
that can handle the error.
Usage
Goro is an Android library packaged as AAR and available in Maven Central. Add this dependency to your Android project in build.gradle
:
dependencies {
compile 'com.stanfy.enroscar:enroscar-goro:2.0.0@aar'
}
Using this library with Android Gradle plugin will automatically add GoroService
to your application components, so that you won't need to add anything to you AndroidManifest
file.
If you do not plan to use GoroService
as it is provided, change your dependency specification to fetch a JAR instead of AAR:
dependencies {
compile 'com.stanfy.enroscar:enroscar-goro:2.0.0'
}
You may also simply grab a JAR or an AAR from Maven Central. Or use it with Maven:
<dependency>
<groupId>com.stanfy.enroscar</groupId>
<artifactId>enroscar-goro</artifactId>
<version>$latestVersion</version>
</dependency>
Queues are not threads
There is no mapping between queues and actual threads scheduled operations are executed in. By default, to perform tasks Goro uses the same thread pool that AsyncTask
operate with. On older Android versions, where this thread pool is not available in public API, Goro creates its own pool manually with configuration similar to what is used in AsyncTask
.
You may also specify different actual executor for Goro either with GoroService.setDelegateExecutor(myThreadPool)
or with new Goro(myThreadPool)
depending on how you use Goro.
Sample
In this repository you'll also find a sample demonstrating what Goro does.
RxJava Integration
As long as you have RxJava jar in your classpath, you can use class RxGoro
, which can wrap a Goro
instance and provide schedule
methods that return rx.Observable
instead of Future
.
License
Copyright 2012-2015 Stanfy Corp.
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.