1 /* 2 * Copyright (C) 2017 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License 15 */ 16 17 package com.android.dialer.common.concurrent; 18 19 import android.support.annotation.MainThread; 20 import android.support.annotation.NonNull; 21 import android.support.annotation.Nullable; 22 import android.support.annotation.WorkerThread; 23 import java.util.concurrent.ExecutorService; 24 25 /** 26 * Provides a consistent interface for doing background work in either UI or non-UI contexts. 27 * 28 * <p>See {@link DialerExecutors} for usage examples. 29 */ 30 public interface DialerExecutor<InputT> { 31 32 /** Functional interface for doing work in the background. */ 33 interface Worker<InputT, OutputT> { 34 @WorkerThread 35 @Nullable doInBackground(@ullable InputT input)36 OutputT doInBackground(@Nullable InputT input) throws Throwable; 37 } 38 39 /** Functional interface for handling the result of background work. */ 40 interface SuccessListener<OutputT> { 41 @MainThread onSuccess(@ullable OutputT output)42 void onSuccess(@Nullable OutputT output); 43 } 44 45 /** Functional interface for handling an error produced while performing background work. */ 46 interface FailureListener { 47 @MainThread onFailure(@onNull Throwable throwable)48 void onFailure(@NonNull Throwable throwable); 49 } 50 51 /** Builder for {@link DialerExecutor}. */ 52 interface Builder<InputT, OutputT> { 53 54 /** 55 * Optional. Default is no-op. 56 * 57 * @param successListener a function executed on the main thread upon task success. There are no 58 * restraints on this as it is executed on the main thread, so lambdas, anonymous, or inner 59 * classes of your activity or fragment are all fine. 60 */ 61 @NonNull onSuccess(@onNull SuccessListener<OutputT> successListener)62 Builder<InputT, OutputT> onSuccess(@NonNull SuccessListener<OutputT> successListener); 63 64 /** 65 * Optional. If this is not set and your worker throws an exception, the application will crash. 66 * 67 * @param failureListener a function executed on the main thread upon task failure. There are no 68 * restraints on this as it is executed on the main thread, so lambdas, anonymous, or inner 69 * classes of your activity or fragment are all fine. 70 */ 71 @NonNull onFailure(@onNull FailureListener failureListener)72 Builder<InputT, OutputT> onFailure(@NonNull FailureListener failureListener); 73 74 /** 75 * Builds the {@link DialerExecutor} which can be used to execute your task (repeatedly with 76 * differing inputs if desired). 77 */ 78 @NonNull build()79 DialerExecutor<InputT> build(); 80 } 81 82 /** Executes the task such that repeated executions for this executor are serialized. */ 83 @MainThread executeSerial(@ullable InputT input)84 void executeSerial(@Nullable InputT input); 85 86 /** 87 * Executes the task on a thread pool shared across the application. Multiple calls using this 88 * method may result in tasks being executed in parallel. 89 */ 90 @MainThread executeParallel(@ullable InputT input)91 void executeParallel(@Nullable InputT input); 92 93 /** 94 * Executes the task on a custom executor service. This should rarely be used; instead prefer 95 * {@link #executeSerial(Object)} or {@link #executeParallel(Object)}. 96 */ 97 @MainThread executeOnCustomExecutorService( @onNull ExecutorService executorService, @Nullable InputT input)98 void executeOnCustomExecutorService( 99 @NonNull ExecutorService executorService, @Nullable InputT input); 100 } 101