1 files changed, 134 insertions, 0 deletions
diff --git a/java/com/android/dialer/common/concurrent/DialerExecutors.java b/java/com/android/dialer/common/concurrent/DialerExecutors.java
new file mode 100644
index 000000000..148d8660c
--- /dev/null
+++ b/java/com/android/dialer/common/concurrent/DialerExecutors.java
@@ -0,0 +1,134 @@
+/*
+ * Copyright (C) 2017 The Android Open Source Project
+ *
+ * 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
+ */
+
+package com.android.dialer.common.concurrent;
+
+import android.app.FragmentManager;
+import android.support.annotation.NonNull;
+import com.android.dialer.common.Assert;
+import com.android.dialer.common.concurrent.DialerExecutor.Worker;
+
+/**
+ * Factory methods for creating {@link DialerExecutor} objects for doing background work.
+ *
+ * <p>You may create an executor from a UI component (activity or fragment) or a non-UI component.
+ * Using this class provides a number of benefits:
+ *
+ * <ul>
+ *   <li>Ensures that UI tasks keep running across configuration changes by using a headless
+ *       fragment.
+ *   <li>Forces exceptions to crash the application, unless the user implements their own onFailure
+ *       method.
+ *   <li>Checks for dead UI components which can be encountered if a UI task runs longer than its
+ *       UI. If a dead UI component is encountered, onSuccess/onFailure are not called (because they
+ *       can't be) but a message is logged.
+ *   <li>Helps prevents memory leaks in UI tasks by ensuring that callbacks are nulled out when the
+ *       headless fragment is detached.
+ *   <li>UI and non-UI threads are shared across the application and run at reasonable priorities
+ * </ul>
+ *
+ * <p>Executors accept a single input and output parameter which should be immutable data objects.
+ * If you don't require an input or output, use Void and null as needed.
+ *
+ * <p>You may optionally specify onSuccess and onFailure listeners; the default behavior on success
+ * is a no-op and the default behavior on failure is to crash the application.
+ *
+ * <p>To use an executor from a UI component, you must create it in your onCreate method and then
+ * use it from anywhere:
+ *
+ * <pre><code>
+ *
+ * public class MyActivity extends Activity {
+ *
+ *   private final DialerExecutor&lt;MyInputType&gt; myExecutor;
+ *
+ *   public void onCreate(Bundle state) {
+ *     super.onCreate(bundle);
+ *
+ *     // Must be called in onCreate; don't use non-static or anonymous inner classes for worker!
+ *     myExecutor = DialerExecutors.createUiTaskBuilder(fragmentManager, taskId, worker)
+ *         .onSuccess(this::onSuccess)  // Lambdas, anonymous, or non-static inner classes all fine
+ *         .onFailure(this::onFailure)  // Lambdas, anonymous, or non-static inner classes all fine
+ *         .build();
+ *     );
+ *   }
+ *
+ *   private static class MyWorker implements Worker&lt;MyInputType, MyOutputType&gt; {
+ *     MyOutputType doInBackground(MyInputType input) { ... }
+ *   }
+ *   private void onSuccess(MyOutputType output) { ... }
+ *   private void onFailure(Throwable throwable) { ... }
+ *
+ *   private void userDidSomething() { myExecutor.executeParallel(input); }
+ * }
+ * </code></pre>
+ *
+ * <p>Usage for non-UI tasks is the same, except that tasks can be created from anywhere instead of
+ * in onCreate. Non-UI tasks use low-priority threads separate from the UI task threads so as not to
+ * compete with more critical UI tasks.
+ *
+ * <pre><code>
+ *
+ * public class MyManager {
+ *
+ *   private final DialerExecutor&lt;MyInputType&gt; myExecutor;
+ *
+ *   public void init() {
+ *     // Don't use non-static or anonymous inner classes for worker!
+ *     myExecutor = DialerExecutors.createNonUiTaskBuilder(worker)
+ *         .onSuccess(this::onSuccess)  // Lambdas, anonymous, or non-static inner classes all fine
+ *         .onFailure(this::onFailure)  // Lambdas, anonymous, or non-static inner classes all fine
+ *         .build();
+ *     );
+ *   }
+ *
+ *   private static class MyWorker implements Worker&lt;MyInputType, MyOutputType&gt; {
+ *     MyOutputType doInBackground(MyInputType input) { ... }
+ *   }
+ *   private void onSuccess(MyOutputType output) { ... }
+ *   private void onFailure(Throwable throwable) { ... }
+ *
+ *   private void userDidSomething() { myExecutor.executeParallel(input); }
+ * }
+ * </code></pre>
+ *
+ * Note that non-UI tasks are intended to be relatively quick; for example reading/writing shared
+ * preferences or doing simple database work. If you submit long running non-UI tasks you may
+ * saturate the shared application threads and block other tasks. Also, this class does not create
+ * any wakelocks, so a long running task could be killed if the device goes to sleep while your task
+ * is still running. If you have to do long running or periodic work, consider using a job
+ * scheduler.
+ */
+public final class DialerExecutors {
+
+  /** @see DialerExecutorFactory#createUiTaskBuilder(FragmentManager, String, Worker) */
+  @NonNull
+  public static <InputT, OutputT> DialerExecutor.Builder<InputT, OutputT> createUiTaskBuilder(
+      @NonNull FragmentManager fragmentManager,
+      @NonNull String taskId,
+      @NonNull Worker<InputT, OutputT> worker) {
+    return new DefaultDialerExecutorFactory()
+        .createUiTaskBuilder(
+            Assert.isNotNull(fragmentManager), Assert.isNotNull(taskId), Assert.isNotNull(worker));
+  }
+
+  /** @see DialerExecutorFactory#createNonUiTaskBuilder(Worker) */
+  @NonNull
+  public static <InputT, OutputT> DialerExecutor.Builder<InputT, OutputT> createNonUiTaskBuilder(
+      @NonNull Worker<InputT, OutputT> worker) {
+    return new DefaultDialerExecutorFactory().createNonUiTaskBuilder(Assert.isNotNull(worker));
+  }
+}